@duckcodeailabs/dql-cli 1.14.1 → 1.14.3-rc.1

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

@@ -1,9 +1,10 @@
-import { deadlineScale, planAnalystTurn, rerankCandidates } from '@duckcodeailabs/dql-agent';
+import { classifyProviderFailure, deadlineScale, planAnalystTurn, attachAskTraceObserverV1, analyticalErrorDetail, rerankCandidates, askTraceObserverForV1, } 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, createAnalystLaneHandler, parseProposal, renderContextValidationRefusalForUser, validateSqlAgainstLocalContext, resolveOrchestratorPolicy, } from '@duckcodeailabs/dql-agent';
-import { CassetteStore, resolveCassetteModeFromEnv, withCassette } from '../../commands/agent-eval-cassette.js';
-import { buildManifest, normalizeDqlArtifactReference, resolveDbtManifestPath } from '@duckcodeailabs/dql-core';
-import { existsSync, readFileSync } from 'node:fs';
+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 { 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';
@@ -12,6 +13,17 @@ import { getEffectiveProviderConfig } from '../../settings/provider-settings.js'
 import { ClaudeCodeCliProvider, CodexCliProvider } from '../../providers/subscription-cli.js';
 import { ClaudeOAuthProvider, claudeOAuthConnected } from '../../providers/oauth/claude-oauth.js';
 import { CodexOAuthProvider, codexOAuthConnected } from '../../providers/oauth/codex-oauth.js';
+/**
+ * The local runtime rejects a missing connection before it hands a statement
+ * to a connector. Keep this check structural: parsing a user-facing message
+ * here would let an unrelated warehouse failure disappear from SQL telemetry.
+ */
+function isPreSqlConnectionConfigurationError(error) {
+    const detail = analyticalErrorDetail(error);
+    return detail?.origin === 'host'
+        && detail.stage === 'execute'
+        && detail.code === 'connection_not_configured';
+}
 const SPECS = {
     anthropic: {
         label: 'Anthropic Claude',
@@ -75,6 +87,136 @@ 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),
+    });
+}
+/** One-way runtime correlation only; never persist the provider/model string. */
+function runtimeFingerprint(value) {
+    return `sha256:${createHash('sha256').update(value).digest('hex')}`;
+}
+/**
+ * Tool names are executable contract identifiers, not user/model supplied
+ * values. Keep even that narrow surface allowlisted so an unexpected provider
+ * payload cannot turn a trace into a metadata side channel.
+ */
+const TRACEABLE_ASK_TOOL_KINDS = new Set([
+    'check_compatibility',
+    'compile_resolved_analytical_plan',
+    'compile_semantic_query',
+    'describe_notebook_dataset',
+    'execute_local_analysis',
+    'explain_metric',
+    'get_table_schema',
+    'list_notebook_datasets',
+    'preview_query',
+    'propose_cross_source_join',
+    'query_semantic_model',
+    'sample_notebook_dataset',
+    'scan_manifest',
+    'search_metadata',
+    'search_project_files',
+    'search_semantic_layer',
+    'search_values',
+    'validate_sql',
+]);
+const ASK_TRACE_TOOL_CALLBACK = Symbol('dql.askTraceToolCallback');
+/**
+ * A same-provider transport retry is minted only by this physical runner after
+ * it observed a typed transient failure.  The public option field is carried
+ * to providers for receipt correlation, but it is not itself authority to
+ * borrow an earlier receipt.
+ */
+const RUNNER_OWNED_RETRY_LINEAGE = Symbol('dql.runnerOwnedRetryLineage');
+function frozenExploratoryRepairAuthorityForRequest(req) {
+    const plan = req.resolvedAnalyticalPlan;
+    return req.orchestrationMode !== 'research'
+        && req.selectedCascadeTier === 'exploratory_sql'
+        && plan?.mode === 'authoritative'
+        && plan.capability === 'bounded_exploration'
+        && Boolean(plan.planId && plan.fingerprint && plan.snapshotId)
+        && (plan.sourceRelationIds?.length ?? 0) > 0
+        && Boolean(req.generatedProposalTargetFingerprint
+            && req.prepareExploratorySqlExecution
+            && req.executeAgenticGeneratedSql);
+}
+function repairAuthorityAdmissionError() {
+    return Object.assign(new Error('Repair transport admission denied because this ordinary Ask has no matching frozen exploratory repair authority.'), { code: 'PROVIDER_REPAIR_AUTHORITY_ADMISSION_DENIED' });
+}
+function retryLineageAdmissionError() {
+    return Object.assign(new Error('Provider retry admission denied because retry lineage was not minted by this runner after a transient same-provider failure.'), { code: 'PROVIDER_RETRY_LINEAGE_ADMISSION_DENIED' });
+}
+function recordPhysicalToolCallTrace(observer, event, attemptIndex) {
+    if (!observer.enabled)
+        return;
+    const now = Date.now();
+    const duration = Math.max(0, Math.min(86_400_000, event.durationMs ?? 0));
+    const startedAt = new Date(now - duration).toISOString();
+    const completedAt = new Date(now).toISOString();
+    const call = {
+        version: 1,
+        toolCallId: `tool-${attemptIndex}`,
+        toolKind: TRACEABLE_ASK_TOOL_KINDS.has(event.name) ? event.name : 'unknown_tool',
+        attemptIndex,
+        ...(event.isError ? { safeErrorCode: 'tool_error' } : {}),
+    };
+    const span = observer.startSpan({
+        name: 'tool.call',
+        stage: 'tool',
+        startedAt,
+        payload: { kind: 'tool', call },
+        reasonCode: 'started',
+    });
+    observer.finishSpan(span, {
+        completedAt,
+        outcome: event.isError ? 'error' : 'ok',
+        reasonCode: event.isError ? 'tool_failure' : 'completed',
+        payload: { kind: 'tool', call },
+    });
+}
+function createAskTraceToolCallback(observer) {
+    let attemptIndex = 0;
+    const callback = (event) => {
+        recordPhysicalToolCallTrace(observer, event, ++attemptIndex);
+    };
+    Object.defineProperty(callback, ASK_TRACE_TOOL_CALLBACK, {
+        value: true,
+        enumerable: false,
+    });
+    return callback;
+}
+function isAskTraceToolCallback(callback) {
+    return Boolean(callback?.[ASK_TRACE_TOOL_CALLBACK]);
+}
 function createCertifiedFitConfirmation(provider, signal) {
     return async ({ question, questionPlan, block, fit }) => {
         const response = await provider.generate([
@@ -228,6 +370,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;
@@ -279,16 +455,27 @@ function emitProposalFromText(text, emit) {
  * 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 per project root because this runs on every turn and the answer is a
- * migration setting, not live state. A malformed file resolves to `null`, which
- * `resolveOrchestratorPolicy` turns into `legacy` — a broken config must not
- * route real questions onto an unproven path.
+ * 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 !== undefined)
-        return cached;
+    if (cached && cached.fingerprint === fingerprint)
+        return cached.value;
     let resolved = null;
     try {
         const raw = readFileSync(join(projectRoot, 'dql.config.json'), 'utf-8');
@@ -300,7 +487,7 @@ function readAgentConfig(projectRoot) {
     catch {
         resolved = null;
     }
-    agentConfigCache.set(projectRoot, resolved);
+    agentConfigCache.set(projectRoot, { fingerprint, value: resolved });
     return resolved;
 }
 function readOrchestratorConfig(projectRoot) {
@@ -325,10 +512,15 @@ function readOrchestratorConfig(projectRoot) {
  * 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.
+ * so today it buys nothing a user can see. Ordinary Ask already has a
+ * candidate-ID meaning call that produces the host-owned analytical plan, so
+ * it must never spend an extra provider transport on turn planning even when
+ * a stale local config enables it. Research remains the only explicit lane
+ * that may opt in to a separate plan stage.
  */
-function turnPlanningEnabled(projectRoot) {
+function turnPlanningEnabled(projectRoot, orchestrationMode) {
+    if (orchestrationMode !== 'research')
+        return false;
     const orchestrator = readAgentConfig(projectRoot)?.orchestrator;
     if (!orchestrator || typeof orchestrator !== 'object')
         return false;
@@ -355,11 +547,43 @@ function valueLookupEnabled(projectRoot) {
 function agenticLaneForRequest(req) {
     return req.orchestrationMode === 'research' ? 'research' : 'generated';
 }
-export function applyEvalCassette(provider) {
+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));
+    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.
@@ -373,7 +597,7 @@ export function createGovernedTextProvider(id, projectRoot) {
     if (!spec)
         return undefined;
     try {
-        return applyEvalCassette(spec.create(projectRoot));
+        return applyEvalCassette(spec.create(projectRoot), projectRoot);
     }
     catch {
         return undefined;
@@ -383,9 +607,25 @@ export function createDqlAgentProviderRunner(id, providerOverride) {
     return {
         async run(req, emit, signal) {
             const spec = SPECS[id];
-            const rawProvider = applyEvalCassette(providerOverride ?? spec.create(req.projectRoot));
+            const rawProvider = applyEvalCassette(providerOverride ?? spec.create(req.projectRoot), req.projectRoot);
+            const askTrace = askTraceObserverForV1(req);
+            // A router-frozen exact certified block is a deterministic execution
+            // lane. It may not probe provider readiness merely because it shares the
+            // answer-loop adapter with provider-dependent routes. The flag is
+            // server-owned and the deterministic provider below throws if a future
+            // branch accidentally tries to generate text, so this cannot create a
+            // silent provider fallback.
+            const providerPreflightRequired = req.providerPreflightRequired !== false;
             const isResearch = req.orchestrationMode === 'research';
-            const maxProviderDispatches = isResearch ? 8 : 4;
+            const frozenExploratoryRepairRoute = frozenExploratoryRepairAuthorityForRequest(req);
+            // Ordinary analytical Ask has one candidate-ID interpretation, one
+            // generation, and — only for an already frozen exploratory plan — one
+            // same-plan model-decline correction. The shared run ledger remains the
+            // authority across calls; this per-provider ceiling keeps un-ledgered
+            // direct callers in the same bounded shape.  A legacy text-tool run is
+            // not an analytical repair route and retains its established three-tool
+            // plus final-response wrapper cap; it cannot acquire the repair phase.
+            const maxProviderDispatches = isResearch ? 8 : frozenExploratoryRepairRoute ? 3 : 4;
             const researchRowsOptIn = isResearch && req.researchResultRowsOptIn === true;
             const sharedDispatchEvidence = req.providerDispatchEvidenceSink;
             let providerRoundTrips = 0;
@@ -394,6 +634,11 @@ export function createDqlAgentProviderRunner(id, providerOverride) {
             let pendingColumnCount = 0;
             let pendingCumulativeResultRowCount = 0;
             let pendingResearchPurpose = 'research_narration';
+            let physicalToolAttemptIndex = 0;
+            let physicalProviderAttemptIndex = 0;
+            let lastFailedProviderSpanId;
+            let physicalDispatchSequence = 0;
+            let lastAdmittedPhysicalDispatch;
             const providerEgressReceipts = [];
             const dispatchEvidence = (fallbackReason) => {
                 const shared = sharedDispatchEvidence?.snapshot(fallbackReason);
@@ -408,106 +653,598 @@ export function createDqlAgentProviderRunner(id, providerOverride) {
                         fallbackReason,
                     };
             };
+            /**
+             * Count a SQL call at the physical execution boundary, not merely when
+             * the answer loop asks the host to prepare one. A tagged missing
+             * connection fails before the connector sees SQL, so it must remain zero
+             * in the durable receipt and trace. Other rejected execution callbacks
+             * retain the historical count: they may have reached the warehouse and
+             * failed there.
+             */
+            const executeAtSqlBoundary = async (work) => {
+                try {
+                    const result = await work();
+                    sqlExecutions += 1;
+                    return result;
+                }
+                catch (error) {
+                    if (!isPreSqlConnectionConfigurationError(error))
+                        sqlExecutions += 1;
+                    throw error;
+                }
+            };
             signal.addEventListener('abort', () => {
                 const reason = signal.reason;
                 if (reason && typeof reason === 'object') {
                     Object.assign(reason, { providerDispatchEvidence: dispatchEvidence('cancelled') });
                 }
             }, { once: true });
-            const withPhysicalDispatchObserver = (options) => ({
-                ...(options ?? {}),
-                // 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,
-                ...(sharedDispatchEvidence?.mayStartToolCall
-                    ? { mayStartToolCall: () => sharedDispatchEvidence.mayStartToolCall() }
-                    : {}),
-                onProviderDispatch: (event) => {
-                    const purpose = isResearch ? pendingResearchPurpose : 'answer_generation';
-                    if (sharedDispatchEvidence) {
-                        const envelope = sharedDispatchEvidence.observe(event, {
-                            purpose,
-                            dispatchPhase: 'generation',
-                            optIn: pendingResultRowCount > 0 && researchRowsOptIn,
-                            serializedResultShape: {
-                                resultRowCount: pendingResultRowCount,
-                                columnCount: pendingColumnCount,
-                            },
-                            ...(pendingCumulativeResultRowCount > 0
-                                ? { cumulativeResultRowCount: pendingCumulativeResultRowCount }
-                                : {}),
-                        });
-                        pendingResultRowCount = 0;
-                        pendingColumnCount = 0;
-                        pendingCumulativeResultRowCount = 0;
-                        pendingResearchPurpose = 'research_narration';
-                        return envelope;
+            const providerAttemptPayload = (event, input) => {
+                const diagnostic = input.diagnostic;
+                const config = getEffectiveProviderConfig(req.projectRoot, id);
+                let baseOrigin;
+                if (config.baseUrl) {
+                    try {
+                        baseOrigin = new URL(config.baseUrl).origin;
                     }
-                    // Fallback path only (CLI/MCP-direct runs carry no shared ledger).
-                    // Kept in step with `maxProviderDispatches` above so the same question
-                    // does not get a different budget depending on which surface asked it.
-                    if (!isResearch && providerRoundTrips >= 4) {
-                        throw Object.assign(new Error('Provider dispatch budget exhausted after four ordinary generation attempts.'), {
-                            code: 'PROVIDER_DISPATCH_BUDGET_EXHAUSTED',
+                    catch {
+                        baseOrigin = config.baseUrl;
+                    }
+                }
+                const model = event.model ?? config.model;
+                return {
+                    version: 1,
+                    phase: input.phase,
+                    purpose: input.purpose,
+                    physicalAttemptIndex: ++physicalProviderAttemptIndex,
+                    providerFingerprint: diagnostic?.providerFingerprint ?? runtimeFingerprint(event.provider),
+                    ...(diagnostic?.modelFingerprint || model ? { modelFingerprint: diagnostic?.modelFingerprint ?? runtimeFingerprint(model) } : {}),
+                    ...(diagnostic?.baseOriginFingerprint || baseOrigin ? { baseOriginFingerprint: diagnostic?.baseOriginFingerprint ?? runtimeFingerprint(baseOrigin) } : {}),
+                    ...(input.retryOfSpanId ? { retryOfSpanId: input.retryOfSpanId } : {}),
+                    admission: input.admission,
+                    ...(diagnostic?.httpStatusClass ? { httpStatusClass: diagnostic.httpStatusClass } : {}),
+                    ...(diagnostic?.retryable !== undefined ? { retryable: diagnostic.retryable } : {}),
+                    ...(diagnostic?.safeAction ? { safeAction: diagnostic.safeAction } : {}),
+                    ...(diagnostic?.cause ? { cause: diagnostic.cause } : {}),
+                    provenance: 'live',
+                };
+            };
+            const providerDiagnosticForTrace = (error, phase) => providerBoundaryDiagnostic({
+                providerId: id,
+                projectRoot: req.projectRoot,
+                phase,
+                error,
+                code: error && typeof error === 'object' ? String(error.code ?? '') : undefined,
+            });
+            /**
+             * The wrapper is the authoritative physical-dispatch boundary. Preserve
+             * a Research phase that the host explicitly set, but ordinary Ask only
+             * accepts the frozen-plan repair marker; every other Ask transport is
+             * answer generation.
+             */
+            const providerDispatchIdentity = (options) => {
+                const requestedPhase = options?.dispatchPhase;
+                const requestedPurpose = options?.egressPurpose;
+                // In an ordinary Ask, `repair` and `repair_sql` are a paired,
+                // server-owned capability.  Preserve the requested repair identity in
+                // a denied trace so support can see what was refused, but do not admit
+                // it unless this runner captured the immutable exploratory RAP and
+                // the answer loop supplied the single-send repair shape.
+                const ordinaryRepairRequested = !isResearch
+                    && (requestedPhase === 'repair' || requestedPurpose === 'repair_sql');
+                const ordinaryRepairAuthorized = ordinaryRepairRequested
+                    && frozenExploratoryRepairRoute
+                    && requestedPhase === 'repair'
+                    && requestedPurpose === 'repair_sql'
+                    && options?.maxProviderDispatches === 1
+                    && options?.retryOfAttemptIndex === undefined;
+                const researchPhase = requestedPhase === 'classification'
+                    || requestedPhase === 'meaning_resolution'
+                    || requestedPhase === 'planning'
+                    || requestedPhase === 'generation'
+                    || requestedPhase === 'narration'
+                    || requestedPhase === 'repair';
+                const dispatchPhase = isResearch && researchPhase
+                    ? requestedPhase
+                    : ordinaryRepairRequested
+                        ? 'repair'
+                        : 'generation';
+                const purpose = dispatchPhase === 'repair'
+                    ? 'repair_sql'
+                    : isResearch && (requestedPurpose === 'research_narration'
+                        || requestedPurpose === 'research_tool'
+                        || requestedPurpose === 'answer_generation')
+                        ? requestedPurpose
+                        : isResearch
+                            ? pendingResearchPurpose
+                            : 'answer_generation';
+                const retryRequested = options?.retryOfAttemptIndex !== undefined;
+                const runnerRetry = options?.[RUNNER_OWNED_RETRY_LINEAGE];
+                const retryAuthorized = retryRequested
+                    && Boolean(runnerRetry
+                        && runnerRetry.parentAttemptIndex === options?.retryOfAttemptIndex
+                        && runnerRetry.phase === dispatchPhase
+                        && runnerRetry.purpose === purpose);
+                return {
+                    dispatchPhase,
+                    purpose,
+                    ordinaryRepairRequested,
+                    ordinaryRepairAuthorized,
+                    retryRequested,
+                    retryAuthorized,
+                };
+            };
+            const withPhysicalDispatchObserver = (options) => {
+                // The answer loop can label exactly one frozen-plan correction as a
+                // repair. Do not let arbitrary provider options mint another phase:
+                // the local runner owns all other ordinary Ask dispatches as generation.
+                const identity = providerDispatchIdentity(options);
+                const { dispatchPhase, purpose, ordinaryRepairRequested, ordinaryRepairAuthorized, retryRequested, retryAuthorized, } = identity;
+                const requestedPhysicalCap = typeof options?.maxProviderDispatches === 'number'
+                    && Number.isInteger(options.maxProviderDispatches)
+                    && options.maxProviderDispatches > 0
+                    ? options.maxProviderDispatches
+                    : maxProviderDispatches;
+                // A repair response is one physical send even if a lower-level
+                // provider supports protocol retries. The frozen plan's one repair
+                // reservation must not turn into an unbounded transport loop.
+                const physicalDispatchCap = dispatchPhase === 'repair'
+                    ? 1
+                    : Math.min(maxProviderDispatches, requestedPhysicalCap);
+                const onToolCall = options?.onToolCall;
+                const onProviderDispatch = options?.onProviderDispatch;
+                const onProviderDispatchComplete = options?.onProviderDispatchComplete;
+                const onProviderDispatchRejected = options?.onProviderDispatchRejected;
+                const pending = new Map();
+                const keyForDispatch = (event) => `${event.provider}:${event.operation}:${event.attemptIndex}`;
+                // An admission failure can be surfaced both by a throwing admission
+                // callback and a provider's optional rejection callback. It is one
+                // unsent attempt, not two trace rows.
+                const admittedKeys = new Set();
+                const deniedKeys = new Set();
+                const finish = (entry, outcome, error, httpStatus) => {
+                    if (!entry.spanId)
+                        return;
+                    if (outcome === 'ok') {
+                        askTrace.finishSpan(entry.spanId, {
+                            outcome: 'ok',
+                            reasonCode: 'completed',
+                            payload: { kind: 'provider', attempt: entry.attempt },
                         });
+                        return;
                     }
-                    const envelope = prepareProviderWireEnvelopeForDispatch(rawProvider.name, event.envelope);
-                    assertProviderPayloadAllowed(envelope, {
-                        allowResultRows: false,
-                        maxResultRows: 0,
-                        purpose,
+                    const diagnostic = providerDiagnosticForTrace(error ?? (typeof httpStatus === 'number' ? Object.assign(new Error(`HTTP ${httpStatus}`), { code: `HTTP_${httpStatus}` }) : undefined), dispatchPhase);
+                    const failureAttempt = {
+                        ...entry.attempt,
+                        ...(diagnostic.httpStatusClass ? { httpStatusClass: diagnostic.httpStatusClass } : {}),
+                        retryable: diagnostic.retryable,
+                        safeAction: diagnostic.safeAction,
+                        cause: outcome === 'cancelled' ? 'cancelled' : diagnostic.cause,
+                    };
+                    askTrace.finishSpan(entry.spanId, {
+                        outcome: outcome === 'cancelled' ? 'cancelled' : 'error',
+                        reasonCode: outcome === 'cancelled' ? 'cancelled' : 'provider_failure',
+                        payload: { kind: 'provider', attempt: failureAttempt },
                     });
-                    providerRoundTrips += 1;
-                    providerEgressReceipts.push(createProviderDispatchEgressReceipt({
-                        purpose,
-                        dispatchPhase: 'generation',
-                        provider: rawProvider.name,
-                        permittedCategories: pendingResultRowCount > 0
-                            ? ['instructions', 'question', 'schema_metadata', 'governed_context', 'result_rows']
-                            : ['instructions', 'question', 'schema_metadata', 'governed_context'],
-                        optIn: pendingResultRowCount > 0 && researchRowsOptIn,
-                        envelope,
-                        serializedResultShape: {
-                            resultRowCount: pendingResultRowCount,
-                            columnCount: pendingColumnCount,
+                    lastFailedProviderSpanId = entry.spanId;
+                };
+                const physicalOptions = {
+                    ...(options ?? {}),
+                    // The raw provider loop has the same outer ceiling as the local Ask
+                    // contract. The run-scoped ledger is the authority for phase limits:
+                    // one planning/generation transport plus, only when the answer loop
+                    // presents a frozen exploratory repair marker, one repair transport.
+                    maxProviderDispatches: physicalDispatchCap,
+                    ...(sharedDispatchEvidence?.mayStartToolCall
+                        ? { mayStartToolCall: () => sharedDispatchEvidence.mayStartToolCall() }
+                        : {}),
+                    onProviderDispatch: (event) => {
+                        try {
+                            // This is the last synchronous boundary before a native provider
+                            // serializes bytes.  A caller cannot mint an ordinary Ask repair
+                            // merely by placing lifecycle labels in `ProviderToolLoopOptions`.
+                            if (ordinaryRepairRequested && !ordinaryRepairAuthorized) {
+                                throw repairAuthorityAdmissionError();
+                            }
+                            // Retry correlation is likewise host-owned. The shared ledger
+                            // validates the parent receipt too, but this marker prevents a
+                            // caller from claiming an arbitrary earlier attempt before that
+                            // receipt check can admit a wire body.
+                            if (retryRequested && !retryAuthorized) {
+                                throw retryLineageAdmissionError();
+                            }
+                            if (sharedDispatchEvidence) {
+                                const envelope = sharedDispatchEvidence.observe(event, {
+                                    purpose,
+                                    dispatchPhase,
+                                    optIn: pendingResultRowCount > 0 && researchRowsOptIn,
+                                    serializedResultShape: {
+                                        resultRowCount: pendingResultRowCount,
+                                        columnCount: pendingColumnCount,
+                                    },
+                                    ...(pendingCumulativeResultRowCount > 0
+                                        ? { cumulativeResultRowCount: pendingCumulativeResultRowCount }
+                                        : {}),
+                                    ...(options?.retryOfAttemptIndex !== undefined
+                                        ? { retryOfAttemptIndex: options.retryOfAttemptIndex }
+                                        : {}),
+                                });
+                                pendingResultRowCount = 0;
+                                pendingColumnCount = 0;
+                                pendingCumulativeResultRowCount = 0;
+                                pendingResearchPurpose = 'research_narration';
+                                const observedEnvelope = onProviderDispatch?.(event) ?? envelope;
+                                const attempt = providerAttemptPayload(event, {
+                                    admission: 'admitted',
+                                    phase: dispatchPhase,
+                                    purpose,
+                                    retryOfSpanId: lastFailedProviderSpanId,
+                                });
+                                const spanId = askTrace.startSpan({ name: 'provider.attempt', stage: 'provider', reasonCode: 'started', payload: { kind: 'provider', attempt } });
+                                const key = keyForDispatch(event);
+                                lastAdmittedPhysicalDispatch = {
+                                    sequence: ++physicalDispatchSequence,
+                                    attemptIndex: event.attemptIndex,
+                                    phase: dispatchPhase,
+                                    purpose,
+                                };
+                                admittedKeys.add(key);
+                                pending.set(key, [...(pending.get(key) ?? []), { spanId, attempt }]);
+                                return observedEnvelope;
+                            }
+                            // Fallback path only (CLI/MCP-direct runs carry no shared ledger).
+                            // Kept in step with `maxProviderDispatches` above so the same question
+                            // does not get a different budget depending on which surface asked it.
+                            if (!isResearch && providerRoundTrips >= physicalDispatchCap) {
+                                throw Object.assign(new Error(`Provider dispatch budget exhausted after ${physicalDispatchCap} ordinary Ask attempts.`), {
+                                    code: 'PROVIDER_DISPATCH_BUDGET_EXHAUSTED',
+                                });
+                            }
+                            const envelope = prepareProviderWireEnvelopeForDispatch(rawProvider.name, event.envelope);
+                            assertProviderPayloadAllowed(envelope, {
+                                allowResultRows: false,
+                                maxResultRows: 0,
+                                purpose,
+                            });
+                            providerRoundTrips += 1;
+                            providerEgressReceipts.push(createProviderDispatchEgressReceipt({
+                                purpose,
+                                dispatchPhase,
+                                provider: rawProvider.name,
+                                ...(options?.retryOfAttemptIndex !== undefined
+                                    ? { retryOfAttemptIndex: options.retryOfAttemptIndex }
+                                    : {}),
+                                permittedCategories: pendingResultRowCount > 0
+                                    ? ['instructions', 'question', 'schema_metadata', 'governed_context', 'result_rows']
+                                    : ['instructions', 'question', 'schema_metadata', 'governed_context'],
+                                optIn: pendingResultRowCount > 0 && researchRowsOptIn,
+                                envelope,
+                                serializedResultShape: {
+                                    resultRowCount: pendingResultRowCount,
+                                    columnCount: pendingColumnCount,
+                                },
+                                ...(pendingCumulativeResultRowCount > 0
+                                    ? { cumulativeResultRowCount: pendingCumulativeResultRowCount }
+                                    : {}),
+                            }));
+                            pendingResultRowCount = 0;
+                            pendingColumnCount = 0;
+                            pendingCumulativeResultRowCount = 0;
+                            pendingResearchPurpose = 'research_narration';
+                            const observedEnvelope = onProviderDispatch?.(event) ?? envelope;
+                            const attempt = providerAttemptPayload(event, {
+                                admission: 'admitted',
+                                phase: dispatchPhase,
+                                purpose,
+                                retryOfSpanId: lastFailedProviderSpanId,
+                            });
+                            const spanId = askTrace.startSpan({ name: 'provider.attempt', stage: 'provider', reasonCode: 'started', payload: { kind: 'provider', attempt } });
+                            const key = keyForDispatch(event);
+                            lastAdmittedPhysicalDispatch = {
+                                sequence: ++physicalDispatchSequence,
+                                attemptIndex: event.attemptIndex,
+                                phase: dispatchPhase,
+                                purpose,
+                            };
+                            admittedKeys.add(key);
+                            pending.set(key, [...(pending.get(key) ?? []), { spanId, attempt }]);
+                            return observedEnvelope;
+                        }
+                        catch (error) {
+                            // The send was denied before an HTTP attempt. Preserve that
+                            // distinction so support does not misread a budget/admission guard
+                            // as a provider outage.
+                            const key = keyForDispatch(event);
+                            if (!admittedKeys.has(key) && !deniedKeys.has(key)) {
+                                deniedKeys.add(key);
+                                const diagnostic = providerDiagnosticForTrace(error, dispatchPhase);
+                                const attempt = providerAttemptPayload(event, {
+                                    admission: 'denied',
+                                    phase: dispatchPhase,
+                                    purpose,
+                                    diagnostic,
+                                    retryOfSpanId: lastFailedProviderSpanId,
+                                });
+                                const spanId = askTrace.startSpan({ name: 'provider.attempt', stage: 'provider', reasonCode: 'provider_failure', payload: { kind: 'provider', attempt } });
+                                askTrace.finishSpan(spanId, {
+                                    outcome: 'denied',
+                                    reasonCode: 'provider_failure',
+                                    payload: { kind: 'provider', attempt },
+                                });
+                                lastFailedProviderSpanId = spanId;
+                            }
+                            try {
+                                onProviderDispatchRejected?.({
+                                    provider: event.provider,
+                                    operation: event.operation,
+                                    attemptIndex: event.attemptIndex,
+                                    ...(event.model ? { model: event.model } : {}),
+                                    error,
+                                });
+                            }
+                            catch {
+                                // A source observer cannot turn a denied local admission into a
+                                // provider send or a second failure record.
+                            }
+                            throw error;
+                        }
+                    },
+                    onProviderDispatchComplete: (event) => {
+                        const key = keyForDispatch(event);
+                        const entries = pending.get(key) ?? [];
+                        const entry = entries[0];
+                        // A successful HTTP response or subscription child-process exit is
+                        // merely a physical milestone. Keep the same span open until the
+                        // parser/stream/result path settles; this prevents a malformed 200
+                        // response from being recorded as a successful provider attempt.
+                        if (entry && event.outcome === 'ok' && (event.settlement === 'transport' || event.settlement === 'process')) {
+                            entry.attempt = {
+                                ...entry.attempt,
+                                ...(event.settlement === 'transport' ? { transportOutcome: 'ok' } : { processOutcome: 'ok' }),
+                            };
+                        }
+                        else {
+                            const closed = entries.shift();
+                            if (entries.length > 0)
+                                pending.set(key, entries);
+                            else
+                                pending.delete(key);
+                            if (closed)
+                                finish(closed, event.outcome, event.error, event.httpStatus);
+                        }
+                        onProviderDispatchComplete?.(event);
+                    },
+                    onProviderDispatchRejected: (event) => {
+                        // `prepareProviderHttpDispatch` rejected this before it could send
+                        // bytes. Keep it as a denied admission rather than pretending an
+                        // HTTP attempt happened (or losing dispatch-budget evidence).
+                        const key = keyForDispatch(event);
+                        if (!admittedKeys.has(key) && !deniedKeys.has(key)) {
+                            deniedKeys.add(key);
+                            const diagnostic = providerDiagnosticForTrace(event.error, dispatchPhase);
+                            const attempt = providerAttemptPayload(event, {
+                                admission: 'denied',
+                                phase: dispatchPhase,
+                                purpose,
+                                diagnostic,
+                                retryOfSpanId: lastFailedProviderSpanId,
+                            });
+                            const spanId = askTrace.startSpan({
+                                name: 'provider.attempt',
+                                stage: 'provider',
+                                reasonCode: 'provider_failure',
+                                payload: { kind: 'provider', attempt },
+                            });
+                            askTrace.finishSpan(spanId, {
+                                outcome: 'denied',
+                                reasonCode: 'provider_failure',
+                                payload: { kind: 'provider', attempt },
+                            });
+                            lastFailedProviderSpanId = spanId;
+                        }
+                        try {
+                            onProviderDispatchRejected?.(event);
+                        }
+                        catch { /* observer is fail-open */ }
+                    },
+                    onToolCall: (event) => {
+                        // Native providers call this callback at the physical tool boundary.
+                        // Text-protocol loops use the trace-marked callback they received
+                        // directly, so this avoids recording a single tool twice.
+                        if (!isAskTraceToolCallback(onToolCall)) {
+                            recordPhysicalToolCallTrace(askTrace, event, ++physicalToolAttemptIndex);
+                        }
+                        onToolCall?.(event);
+                    },
+                };
+                return {
+                    options: physicalOptions,
+                    settle: (outcome, error) => {
+                        for (const entries of pending.values()) {
+                            for (const entry of entries)
+                                finish(entry, outcome, error);
+                        }
+                        pending.clear();
+                    },
+                };
+            };
+            // 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, identity, parent) => {
+                // A frozen exploratory run deliberately reserves its third physical
+                // dispatch for the same-plan SQL repair. A transient retry of meaning
+                // or generation would consume that reservation, so it is forbidden.
+                if (signal.aborted
+                    || transientRetryUsed
+                    || frozenExploratoryRepairRoute
+                    || identity.dispatchPhase === 'repair'
+                    || !parent
+                    || parent.phase !== identity.dispatchPhase
+                    || parent.purpose !== identity.purpose)
+                    return false;
+                const diagnostic = providerDiagnosticForTrace(error, identity.dispatchPhase);
+                return diagnostic.retryable && (diagnostic.cause === 'rate_limited'
+                    || diagnostic.cause === 'gateway'
+                    || diagnostic.cause === 'network'
+                    || diagnostic.cause === 'provider_timeout');
+            };
+            const retrySameProviderOnce = async (sourceOptions, operation) => {
+                const identity = providerDispatchIdentity(sourceOptions);
+                const dispatchSequenceBefore = physicalDispatchSequence;
+                try {
+                    return await operation(sourceOptions);
+                }
+                catch (error) {
+                    const parent = lastAdmittedPhysicalDispatch?.sequence && lastAdmittedPhysicalDispatch.sequence > dispatchSequenceBefore
+                        ? lastAdmittedPhysicalDispatch
+                        : undefined;
+                    if (!mayRetrySameProvider(error, identity, parent))
+                        throw error;
+                    transientRetryUsed = true;
+                    emit({ kind: 'thinking', text: 'The configured AI provider had a transient error; retrying it once within this run budget.' });
+                    // The retry carries immutable phase/purpose/provider lineage. The
+                    // ledger re-validates the parent receipt before it admits any bytes.
+                    const retryOptions = {
+                        ...(sourceOptions ?? {}),
+                        dispatchPhase: identity.dispatchPhase,
+                        egressPurpose: identity.purpose,
+                        retryOfAttemptIndex: parent.attemptIndex,
+                    };
+                    Object.defineProperty(retryOptions, RUNNER_OWNED_RETRY_LINEAGE, {
+                        value: {
+                            parentAttemptIndex: parent.attemptIndex,
+                            phase: identity.dispatchPhase,
+                            purpose: identity.purpose,
                         },
-                        ...(pendingCumulativeResultRowCount > 0
-                            ? { cumulativeResultRowCount: pendingCumulativeResultRowCount }
-                            : {}),
-                    }));
-                    pendingResultRowCount = 0;
-                    pendingColumnCount = 0;
-                    pendingCumulativeResultRowCount = 0;
-                    pendingResearchPurpose = 'research_narration';
-                    return envelope;
-                },
-            });
+                        enumerable: false,
+                    });
+                    return operation(retryOptions);
+                }
+            };
+            const invokePhysicalProvider = async (sourceOptions, invoke) => {
+                const observed = withPhysicalDispatchObserver(sourceOptions);
+                try {
+                    const result = await invoke(observed.options);
+                    // Built-in HTTP providers close each span via
+                    // `onProviderDispatchComplete`; this only closes a custom provider
+                    // that exposes admission but not the optional completion callback.
+                    observed.settle('ok');
+                    return result;
+                }
+                catch (error) {
+                    observed.settle(signal.aborted ? 'cancelled' : 'error', error);
+                    throw error;
+                }
+            };
             const provider = {
                 name: rawProvider.name,
                 available: () => rawProvider.available(),
-                generate: (...args) => {
-                    return rawProvider.generate(args[0], withPhysicalDispatchObserver(args[1]));
-                },
+                generate: (...args) => retrySameProviderOnce(args[1], (sourceOptions) => invokePhysicalProvider(sourceOptions, (options) => rawProvider.generate(args[0], options))),
                 ...(rawProvider.generateWithTools ? {
-                    generateWithTools: (...args) => {
-                        return rawProvider.generateWithTools(args[0], args[1], withPhysicalDispatchObserver(args[2]));
-                    },
+                    generateWithTools: (...args) => retrySameProviderOnce(args[2], (sourceOptions) => invokePhysicalProvider(sourceOptions, (options) => rawProvider.generateWithTools(args[0], args[1], options))),
                 } : {}),
                 ...(rawProvider.generateStream ? {
-                    generateStream: (...args) => {
-                        return rawProvider.generateStream(args[0], withPhysicalDispatchObserver(args[1]), args[2]);
-                    },
+                    generateStream: (...args) => invokePhysicalProvider(args[1], (options) => rawProvider.generateStream(args[0], options, args[2])),
                 } : {}),
             };
-            const available = await provider.available().catch(() => false);
-            if (!available) {
-                emit({ kind: 'error', message: `${spec.label} is not configured or reachable. ${spec.setup}` });
-                return;
+            if (providerPreflightRequired) {
+                // Readiness is a real provider operation, not a proxy for a later
+                // answer-loop invocation. Record its own outcome before a route can
+                // depend on this provider, while keeping the observer wholly fail-open.
+                const preflightSpan = askTrace.startSpan({
+                    name: 'provider.preflight',
+                    stage: 'provider',
+                    reasonCode: 'started',
+                    payload: {
+                        kind: 'provider',
+                        attempt: {
+                            version: 1,
+                            phase: 'preflight',
+                            physicalAttemptIndex: 0,
+                            providerFingerprint: runtimeFingerprint(rawProvider.name),
+                            readiness: 'unknown',
+                            admission: 'unknown',
+                            provenance: 'live',
+                        },
+                    },
+                });
+                let preflightError;
+                let available = false;
+                try {
+                    available = await provider.available();
+                }
+                catch (error) {
+                    preflightError = error;
+                }
+                if (!available) {
+                    const message = `${spec.label} is not configured or reachable. ${spec.setup}`;
+                    const diagnostic = providerBoundaryDiagnostic({
+                        providerId: id,
+                        projectRoot: req.projectRoot,
+                        phase: 'preflight',
+                        error: preflightError ?? message,
+                        // Local Ollama readiness is a reachability concern; configured
+                        // remote providers missing credentials are authentication issues.
+                        code: preflightError && typeof preflightError === 'object'
+                            ? String(preflightError.code ?? '')
+                            : id === 'ollama' ? 'NETWORK_FAILURE' : 'AUTHENTICATION_FAILED',
+                    });
+                    askTrace.finishSpan(preflightSpan, {
+                        outcome: 'unavailable',
+                        reasonCode: 'provider_preflight',
+                        payload: {
+                            kind: 'provider',
+                            attempt: {
+                                version: 1,
+                                phase: 'preflight',
+                                physicalAttemptIndex: 0,
+                                providerFingerprint: diagnostic.providerFingerprint ?? runtimeFingerprint(rawProvider.name),
+                                ...(diagnostic.modelFingerprint ? { modelFingerprint: diagnostic.modelFingerprint } : {}),
+                                ...(diagnostic.baseOriginFingerprint ? { baseOriginFingerprint: diagnostic.baseOriginFingerprint } : {}),
+                                readiness: 'unavailable',
+                                admission: 'unknown',
+                                retryable: diagnostic.retryable,
+                                safeAction: diagnostic.safeAction,
+                                cause: diagnostic.cause,
+                                provenance: 'live',
+                            },
+                        },
+                    });
+                    emit({
+                        kind: 'error',
+                        message,
+                        providerDiagnostic: diagnostic,
+                    });
+                    return;
+                }
+                askTrace.finishSpan(preflightSpan, {
+                    outcome: 'ok',
+                    reasonCode: 'completed',
+                    payload: {
+                        kind: 'provider',
+                        attempt: {
+                            version: 1,
+                            phase: 'preflight',
+                            physicalAttemptIndex: 0,
+                            providerFingerprint: runtimeFingerprint(rawProvider.name),
+                            readiness: 'ready',
+                            admission: 'unknown',
+                            provenance: 'live',
+                        },
+                    },
+                });
             }
             try {
                 const requestStartedAt = Date.now();
-                emit({ kind: 'thinking', text: `Using ${spec.label} through the governed DQL agent.` });
+                emit({
+                    kind: 'thinking',
+                    text: providerPreflightRequired
+                        ? `Using ${spec.label} through the governed DQL agent.`
+                        : 'Executing the router-selected certified plan without an AI provider.',
+                });
                 const kgPath = defaultKgPath(req.projectRoot);
                 if (!existsSync(kgPath)) {
                     emit({ kind: 'thinking', text: 'Building the local agent knowledge graph from terms, business views, blocks, apps, dashboards, dbt, and semantic metadata.' });
@@ -527,6 +1264,9 @@ export function createDqlAgentProviderRunner(id, providerOverride) {
                     const conversationSnapshot = conversationSnapshotFromContext(req.conversationContext);
                     const rawFollowUp = followUpFromConversationContext(req, rawQuestion) ?? inferFollowUpContext(req, rawQuestion);
                     const followUp = applyTopicShiftGuard(rawFollowUp, conversationSnapshot);
+                    // This is a server-side decision recorded by the engine/trace. It
+                    // never comes from client JSON or an LLM response.
+                    req.conversationBinding = followUp?.binding ?? 'none';
                     // CTX-003: retrieval and planning operate on the user's current words.
                     // Prior SQL, DQL source, owners, and result metadata stay in the typed
                     // follow-up envelope rendered separately for the provider; concatenating
@@ -633,6 +1373,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)
@@ -655,8 +1452,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 } : {}),
                     }), {
@@ -667,11 +1464,22 @@ export function createDqlAgentProviderRunner(id, providerOverride) {
                     // 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 = {
+                    // Preserve the non-enumerable observer when the provider runner
+                    // projects the AgentRun request into the answer-loop input.  The
+                    // analyst loop receives this projected object, so dropping the
+                    // observer here would make actual text-protocol tool calls invisible
+                    // even though provider, router, and SQL evidence was recorded.
+                    const answerLoopInput = attachAskTraceObserverV1({
                         question,
                         ...(req.resolvedAnalyticalPlan
                             ? { resolvedAnalyticalPlan: req.resolvedAnalyticalPlan }
                             : {}),
+                        ...(req.selectedCascadeTier
+                            ? { selectedCascadeTier: req.selectedCascadeTier }
+                            : {}),
+                        ...(req.exploratoryCandidateIds?.length
+                            ? { exploratoryCandidateIds: [...req.exploratoryCandidateIds] }
+                            : {}),
                         ...(req.generatedProposalTargetFingerprint
                             ? { generatedProposalTargetFingerprint: req.generatedProposalTargetFingerprint }
                             : {}),
@@ -692,7 +1500,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
@@ -704,7 +1512,7 @@ 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
@@ -721,16 +1529,43 @@ export function createDqlAgentProviderRunner(id, providerOverride) {
                         ...(req.preferredEvidenceIds?.length ? { preferredEvidenceIds: req.preferredEvidenceIds } : {}),
                         ...(req.preferredExecutionId ? { preferredExecutionId: req.preferredExecutionId } : {}),
                         executeCertifiedBlock: req.executeCertifiedBlock
-                            ? async (...args) => { guardSnapshot(); sqlExecutions += 1; return req.executeCertifiedBlock(...args); }
+                            ? async (...args) => {
+                                guardSnapshot();
+                                return executeAtSqlBoundary(() => req.executeCertifiedBlock(...args));
+                            }
                             : undefined,
                         executeGeneratedSql: req.executeGeneratedSql
-                            ? async (...args) => { guardSnapshot(); sqlExecutions += 1; return req.executeGeneratedSql(...args); }
+                            ? async (...args) => {
+                                guardSnapshot();
+                                return executeAtSqlBoundary(() => 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);
+                                return executeAtSqlBoundary(() => req.executeAgenticGeneratedSql(capability, sql, artifact));
                             }
                             : undefined,
                         agenticExecutionScope: {
@@ -740,7 +1575,10 @@ export function createDqlAgentProviderRunner(id, providerOverride) {
                             targetFingerprint: req.generatedProposalTargetFingerprint,
                         },
                         executeDqlArtifact: req.executeDqlArtifact
-                            ? async (...args) => { guardSnapshot(); sqlExecutions += 1; return req.executeDqlArtifact(...args); }
+                            ? async (...args) => {
+                                guardSnapshot();
+                                return executeAtSqlBoundary(() => req.executeDqlArtifact(...args));
+                            }
                             : undefined,
                         expandGroundingContext: createGroundingContextExpander(req.projectRoot, req.probeNamedRelations),
                         answerLoopTools,
@@ -779,7 +1617,7 @@ 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).
-                    };
+                    }, askTrace);
                     const result = await answerAgentic(answerLoopInput, {
                         policy: resolveOrchestratorPolicy({
                             config: readOrchestratorConfig(req.projectRoot),
@@ -808,14 +1646,15 @@ export function createDqlAgentProviderRunner(id, providerOverride) {
                                         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.
+                                        // Keep the raw loop bounded by the same physical ceiling
+                                        // as the wrapper. The run-scoped ledger still admits only
+                                        // one ordinary generation/planning transport; a separate
+                                        // frozen-plan repair marker is required for the third send.
                                         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) ? {
+                                        ...(turnPlanningEnabled(req.projectRoot, req.orchestrationMode) ? {
                                             planTurn: async (question, toolNames) => {
                                                 const plan = await planAnalystTurn(loopInput.provider, question, toolNames, {
                                                     timeoutMs: Math.round(2_500 * deadlineScale()),
@@ -829,6 +1668,11 @@ export function createDqlAgentProviderRunner(id, providerOverride) {
                                                 return plan;
                                             },
                                         } : {}),
+                                        // Text-protocol tool loops execute tools outside the
+                                        // provider transport, so carry the same physical-boundary
+                                        // observer through the loop. The marker prevents the
+                                        // provider wrapper from duplicating native tool records.
+                                        onToolCall: createAskTraceToolCallback(askTraceObserverForV1(loopInput)),
                                         // 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
@@ -985,6 +1829,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,
+                    }),
                 });
             }
         },
@@ -1279,9 +2136,13 @@ function extractSelectedBlockHints(req) {
     }
 }
 function inferFollowUpContext(req, question) {
-    // Messages-only fallback (no structured conversationContext). Regexes classify the
-    // kind; a non-matching question still carries the prior turn as advisory 'contextual'.
-    const kind = isGenericFollowUp(question) ? 'generic' : isDrilldownFollowUp(question) ? 'drilldown' : 'contextual';
+    // Messages-only fallback (no structured conversationContext). A prior
+    // assistant turn is not permission to carry rows, measures, or a block into
+    // a complete new analytical question. Admit it only for an explicit
+    // prior-result reference/operation; otherwise this returns `undefined`.
+    const kind = isGenericFollowUp(question) ? 'generic' : isDrilldownFollowUp(question) ? 'drilldown' : undefined;
+    if (!kind)
+        return undefined;
     for (let i = req.messages.length - 1; i >= 0; i--) {
         const msg = req.messages[i];
         if (msg.role !== 'assistant')
@@ -1291,6 +2152,7 @@ function inferFollowUpContext(req, question) {
             continue;
         return {
             kind,
+            binding: 'prior_result',
             sourceBlockName,
             sourceAnswer: msg.content.slice(0, 1200),
             filters: kind === 'drilldown' ? extractDrilldownFilters(question) : undefined,
@@ -1328,17 +2190,11 @@ function conversationSnapshotFromContext(context) {
 function applyTopicShiftGuard(followUp, snapshot) {
     if (!followUp || snapshot?.topicRelation !== 'shift')
         return followUp;
-    if (followUp.kind !== 'drilldown')
-        return followUp;
-    return {
-        ...followUp,
-        kind: 'contextual',
-        filters: undefined,
-        dimensions: undefined,
-        priorResultValues: undefined,
-        priorMeasures: undefined,
-        priorLimit: undefined,
-    };
+    // A server-produced compound dependency is a direct child input, not an
+    // incidental thread carry. Every other result binding is dropped on a
+    // topic shift so a fresh analytical request cannot receive prior rows or
+    // measures merely because the thread has history.
+    return followUp.binding === 'task_dependency' ? followUp : undefined;
 }
 /**
  * Resolve the prior-turn context a follow-up may build on.
@@ -1365,6 +2221,7 @@ function resolveAgentFollowUpContextRaw(rawContext, question) {
     if (taskDependency) {
         return {
             kind: 'drilldown',
+            binding: 'task_dependency',
             sourceTurnId: `task:${taskDependency.sourceTaskId}`,
             filters: [taskDependency.value],
             dimensions: [taskDependency.canonicalColumn],
@@ -1418,22 +2275,24 @@ function resolveAgentFollowUpContextRaw(rawContext, question) {
     const hasUsefulContext = Boolean(sourceBlockName || priorResultColumns?.length || focusedPriorResultValues || priorDqlArtifact);
     if (!hasUsefulContext)
         return undefined;
+    // Prior-result material is execution-relevant context, not a friendly
+    // transcript hint. A complete new question therefore receives no carry at
+    // all. The only admission routes are a resolved typed reference, an
+    // explicit prior-result operation, or a deictic/generic follow-up.
     const inferredKind = resolvedReferences.memberBindings?.length
         ? 'drilldown'
         : isGenericFollowUp(question)
             ? 'generic'
             : isDrilldownFollowUp(question, priorShapeTerms(priorResultColumns, focusedPriorResultValues))
                 ? 'drilldown'
-                : null;
-    // Always-on carry: the regexes only CLASSIFY the follow-up kind — they no longer
-    // gate whether conversation context exists at all. A question that matches neither
-    // pattern still carries the prior turn as advisory 'contextual' state; the model
-    // (not a regex) decides whether it's relevant to the new question.
-    const kind = inferredKind
-        ?? (context.followupKind === 'generic' || context.followupKind === 'drilldown' ? context.followupKind : null)
-        ?? 'contextual';
+                : undefined;
+    if (!inferredKind)
+        return undefined;
+    const binding = 'prior_result';
+    const kind = inferredKind;
     return {
         kind,
+        binding,
         sourceTurnId: cleanOptionalString(activeTurn?.id) ?? cleanOptionalString(context.sourceAnswerId),
         // A relative comparison needs the named member from history, not the prior
         // block's result contract. Carrying a beverage-ranking block into "less tax
@@ -2088,6 +2947,8 @@ export const __test__ = {
     shouldSearchProjectFiles,
     renderProjectSourceSearch,
     researchDispatchPurposeForTool,
+    readAgentConfig,
+    providerBoundaryDiagnostic,
 };
 function researchDispatchPurposeForTool(toolName) {
     return toolName === 'execute_local_analysis' ? 'research_tool' : 'research_narration';
@@ -2126,7 +2987,7 @@ function isGenericFollowUp(question) {
  * Now it needs either a deictic reference to the prior result, or an explicit
  * drill verb that only makes sense relative to something already on screen.
  */
-function isDrilldownFollowUp(question, priorTerms = []) {
+function isDrilldownFollowUp(question, _priorTerms = []) {
     const lower = question.toLowerCase();
     const deicticDrilldown = /\b(?:this|that|these|those|same|above|previous|prior)\s+(?:amount|value|orders?|results?|rows?|customers?|products?|cat(?:egor|agor|ogor)(?:y|ies)|segments?|regions?)\b/.test(lower)
         || /\b(?:they|their|them|he|she|him|his|her|hers)\b/.test(lower);
@@ -2135,15 +2996,18 @@ function isDrilldownFollowUp(question, priorTerms = []) {
     // a short gap between them rather than adjacently.
     const explicitDrillVerb = /\b(drills?|breakdowns?|slices?|segments?|splits?|why|drivers?|root cause|variance)\b/.test(lower)
         || /\bbreak\b.{0,16}\bdown\b/.test(lower);
-    // Evidence, not vocabulary: a question that reuses the PRIOR RESULT's own
-    // column or dimension names is talking about that result, whatever words it
-    // uses to do it. This is what distinguishes "who are the customers by region"
-    // asked after a customers table (a drilldown) from the same phrasing asked on
-    // a brand-new topic (not one).
-    const reusesPriorShape = priorTerms.some((term) => term && lower.includes(term));
-    if (!deicticDrilldown && !explicitDrillVerb && !reusesPriorShape)
+    const hasDeicticReference = /\b(?:this|that|these|those|same|above|previous|prior|they|their|them|he|she|him|his|her|hers)\b/.test(lower);
+    const resultStateReference = /\b(?:decline|drop|change|increase|decrease|variance)\b/.test(lower);
+    // A shared word such as customer, revenue, or region is not a prior-result
+    // reference. It appears in many unrelated analytical questions and used to
+    // make a fresh request inherit the prior answer's filters and measures.
+    const explicitPriorResultOperation = /\b(?:top|bottom)\s+\d+\s+of\s+(?:these|those|them|the\s+(?:prior|previous)?\s*results?)\b/.test(lower)
+        || /\b(?:average|sum|total|compare)\s+(?:of|across)\s+(?:these|those|them|the\s+(?:prior|previous)?\s*results?)\b/.test(lower);
+    if (!deicticDrilldown && !explicitPriorResultOperation && !(explicitDrillVerb && (hasDeicticReference || resultStateReference)))
         return false;
-    return deicticDrilldown || !/\b(what is|what are|define|definition|meaning of)\b/.test(lower);
+    // Bare definitions should not inherit a prior result merely because they
+    // contain a pronoun. An explicit result operation remains authoritative.
+    return explicitPriorResultOperation || !/\b(what is|what are|define|definition|meaning of)\b/.test(lower);
 }
 /**
  * Lower-cased words from the prior result's columns and dimension keys, used to