@duckcodeailabs/dql-cli 1.8.1 → 1.8.3

package/dist/local-runtime.js

@@ -14,9 +14,12 @@ import { loadSemanticLayerFromDir, normalizeDqlArtifactReference, serializeMetri
 import { load as loadYaml } from 'js-yaml';
 import { listBlockTemplates } from './block-templates.js';
 import { getRunner as getLLMRunner } from './llm/index.js';
+import { rethrowIfCancelled } from './llm/cancellation.js';
+import { fetchLatestPublishedDqlVersion, resolveDqlRuntimeVersionStatus } from './version-status.js';
+import { resolveRetrievalHealthStatus } from './retrieval-health.js';
 import { createDqlAgentProviderRunner, resolveAgentFollowUpContext } from './llm/providers/dql-agent-provider.js';
 import { listRemoteMcpSettings, saveRemoteMcpSettings } from './llm/mcp-config.js';
-import { ClaudeProvider, ConversationStore, advanceThreadState, buildConversationSnapshot, recallRelevantTurns, GeminiProvider, MemoryStore, OllamaProvider, OpenAIProvider, buildBlockBusinessFingerprint, buildBlockSqlFingerprints, buildAnalysisQuestionPlan, buildLocalContextPack, toAgentRetrievalEvidence, defaultConversationPath, defaultMemoryPath, ensureDefaultMemoryFiles, ensureAgentProjectReady, isAgentProjectIndexReady, currentMetadataFingerprint, ensureMetadataCatalogFresh, readIndexedDomainKnowledge, readIndexedKnowledge360, propose, proposePlan, recordCorrectionTrace, emitCorrectionEvalCase, mineJoinPatterns, reviewHint, AgentRunEngine, FileAgentRunStore, defaultAgentRunGates, createLlmAgentRunPlanner, createHybridRouter, computeResultStats, buildDeterministicDashboardStory, synthesizeAnswer, streamOrGenerate, narrateResult, buildProposePreview, buildFromPrompt, defaultAgentRunStorePath, resolveLocalOwner, resolveProposeConfig, recordQueryRun, recordRuntimeSchemaSnapshot, latestRuntimeSchemaSnapshotForProject, loadSkills, migrateLegacySkills, configuredSkillsPath, skillsDir, draftDomainSkillBootstrap, buildDomainSkillBootstrapPrompt, mergeDomainSkillBootstrapEnrichment, writeSkill, deleteSkill, deriveGeneratedDraftSlug, reindexProject, invalidateAgentProjectState, recordAgentRuntimeVersion, resolveDomainContextEnvelope, defaultKgPath, planAppFromPrompt, KGStore, planResearch, loadSemanticMetrics, cascadeTraceToEvidenceRouteSteps, createCascadeAnswerResult, createCascadeTrace, routeReasoningEffort, routeForCascadeAnswerTier, clampReasoningEffort, bumpReasoningEffort, resolveThinkingMode, coerceThinkingMode, upsertGeneratedDqlArtifactDraft, } from '@duckcodeailabs/dql-agent';
+import { ClaudeProvider, ConversationStore, advanceThreadState, buildConversationSnapshot, recallRelevantTurns, GeminiProvider, MemoryStore, OllamaProvider, OpenAIProvider, buildBlockBusinessFingerprint, buildBlockSqlFingerprints, buildAnalysisQuestionPlan, buildLocalContextPack, toAgentRetrievalEvidence, defaultConversationPath, defaultMemoryPath, ensureDefaultMemoryFiles, ensureAgentProjectReady, isAgentProjectIndexReady, currentMetadataFingerprint, ensureMetadataCatalogFresh, readIndexedDomainKnowledge, readIndexedKnowledge360, propose, proposePlan, recordCorrectionTrace, emitCorrectionEvalCase, mineJoinPatterns, reviewHint, AgentRunEngine, SqliteAgentRunStore, defaultAgentRunGates, createLlmAgentRunPlanner, createHybridRouter, computeResultStats, buildDeterministicDashboardStory, synthesizeAnswer, streamOrGenerate, narrateResult, buildProposePreview, buildFromPrompt, defaultAgentRunStorePath, defaultAgentRunSqlitePath, resolveLocalOwner, resolveProposeConfig, recordQueryRun, recordRuntimeSchemaSnapshot, latestRuntimeSchemaSnapshotForProject, loadSkills, migrateLegacySkills, configuredSkillsPath, skillsDir, draftDomainSkillBootstrap, buildDomainSkillBootstrapPrompt, mergeDomainSkillBootstrapEnrichment, writeSkill, deleteSkill, deriveGeneratedDraftSlug, reindexProject, invalidateAgentProjectState, recordAgentRuntimeVersion, resolveDomainContextEnvelope, defaultKgPath, planAppFromPrompt, KGStore, planResearch, loadSemanticMetrics, cascadeTraceToEvidenceRouteSteps, createCascadeAnswerResult, createCascadeTrace, routeReasoningEffort, routeForCascadeAnswerTier, clampReasoningEffort, bumpReasoningEffort, resolveThinkingMode, coerceThinkingMode, upsertGeneratedDqlArtifactDraft, } from '@duckcodeailabs/dql-agent';
 import { gatherProposeEnrichment } from './propose-enrich.js';
 import { handleAppsApi, proposeAppAiBuild, recommendVisualization } from './apps-api.js';
 import { getActiveProvider, getEffectiveProviderConfig, isProviderSettingsId, listProviderSettings, saveProviderSettings, } from './settings/provider-settings.js';
@@ -145,6 +148,7 @@ export function parseAgentRunRequestBody(body) {
     return {
         request: {
             question,
+            selectedEvidenceId: agentRunString(record.selectedEvidenceId),
             requestedMode,
             audience,
             intent: agentRunString(record.intent),
@@ -163,17 +167,26 @@ export function parseAgentRunRequestBody(body) {
 }
 const AGENT_LOOKUP_DEADLINE_MS = 45_000;
 const AGENT_RESEARCH_DEADLINE_MS = 120_000;
+/** Env-tunable run deadline (e.g. slow subscription-CLI providers), clamped to sane bounds. */
+function resolveAgentDeadlineMs(envKey, fallback, env = process.env) {
+    const configured = Number(env[envKey]);
+    if (!Number.isFinite(configured) || configured <= 0)
+        return fallback;
+    return Math.max(15_000, Math.min(600_000, Math.floor(configured)));
+}
 /**
  * PERF-002: one wall-clock budget follows the request through routing, provider
  * calls, repair, and execution. Ordinary Ask never inherits Research's budget
  * merely because it spans two tables; explicit/deep investigation does.
  */
-export function agentRunDeadlineMs(request) {
+export function agentRunDeadlineMs(request, env = process.env) {
+    const lookupDeadline = resolveAgentDeadlineMs('DQL_AGENT_LOOKUP_DEADLINE_MS', AGENT_LOOKUP_DEADLINE_MS, env);
+    const researchDeadline = resolveAgentDeadlineMs('DQL_AGENT_RESEARCH_DEADLINE_MS', AGENT_RESEARCH_DEADLINE_MS, env);
     if (request.requestedMode === 'research' || request.analysisDepth === 'deep') {
-        return AGENT_RESEARCH_DEADLINE_MS;
+        return researchDeadline;
     }
     const plan = buildAnalysisQuestionPlan(request.question);
-    return plan.needsResearchWorkspace ? AGENT_RESEARCH_DEADLINE_MS : AGENT_LOOKUP_DEADLINE_MS;
+    return plan.needsResearchWorkspace ? researchDeadline : lookupDeadline;
 }
 export function shouldSynthesizeAgentRunAnswer(governedAnswer) {
     if (governedAnswer.kind === 'no_answer')
@@ -197,6 +210,10 @@ export function shouldSynthesizeAgentRunAnswer(governedAnswer) {
         return false;
     return true;
 }
+export function agentAnswerHasExecutionFailure(governedAnswer) {
+    return typeof governedAnswer.executionError === 'string'
+        && governedAnswer.executionError.trim().length > 0;
+}
 function businessNarrativeGaps(warnings) {
     const businessRelevant = (warnings ?? []).filter((warning) => !(/missing requested output column/i.test(warning)
         || /\bquery plan\b/i.test(warning)
@@ -210,7 +227,11 @@ function businessNarrativeGaps(warnings) {
 // source of prior turns (survives refresh); the client-built context remains
 // the fallback for embedders that never send a threadId.
 async function conversationContextFromThread(store, threadId, clientContext, question) {
-    const turns = store.recentTurns(threadId, 8).map((turn) => {
+    // Token-budget backstop: six verbatim turns with per-field caps. Older turns
+    // remain reachable through the rolling summary + semantic recall below —
+    // carrying more raw prose mostly slows every provider call on follow-ups.
+    const clampTurnText = (value) => value && value.length > 1_200 ? `${value.slice(0, 1_200)}…` : value;
+    const turns = store.recentTurns(threadId, 6).map((turn) => {
         const contract = turn.contract ?? {};
         const topN = contract.topN;
         const topNValue = typeof topN === 'number'
@@ -220,8 +241,8 @@ async function conversationContextFromThread(store, threadId, clientContext, que
                 : undefined;
         return compactConversationRecord({
             id: turn.id,
-            question: turn.question,
-            answerSummary: turn.answerSummary,
+            question: clampTurnText(turn.question),
+            answerSummary: clampTurnText(turn.answerSummary),
             sourceCertifiedBlock: turn.sourceCertifiedBlock,
             route: turn.route,
             trustLabel: turn.trustLabel,
@@ -280,16 +301,20 @@ function recordConversationTurn(store, threadId, run) {
         // Conversation persistence is additive; a failed write must not fail the run.
     }
 }
-function conversationTurnInputFromRun(run) {
+export function conversationTurnInputFromRun(run) {
     const artifact = run.artifacts.find((candidate) => candidate.kind === 'answer')
         ?? run.artifacts.find((candidate) => candidate.kind === 'research_run')
         ?? run.artifacts[0];
     const payload = agentRunRecord(artifact?.payload);
     const result = agentRunRecord(payload?.result);
     const columns = conversationResultColumns(result?.columns);
-    const rows = Array.isArray(result?.rows)
-        ? result.rows.filter((row) => Boolean(row && typeof row === 'object' && !Array.isArray(row))).slice(0, 8)
+    // The visual preview stays tiny, but member resolution needs a wider bounded
+    // value window. Deriving dimensions from only the eight preview rows caused a
+    // valid row 9/10 member to disappear before the next turn (AGT-012/E2E-010).
+    const memberRows = Array.isArray(result?.rows)
+        ? result.rows.filter((row) => Boolean(row && typeof row === 'object' && !Array.isArray(row))).slice(0, 24)
         : [];
+    const rows = memberRows.slice(0, 8);
     const rowsSample = rows.map((row) => columns.map((column) => row[column]));
     const contextPack = agentRunRecord(payload?.contextPack);
     const questionPlan = agentRunRecord(contextPack?.questionPlan);
@@ -313,7 +338,7 @@ function conversationTurnInputFromRun(run) {
             ? {
                 columns,
                 rowsSample,
-                dimensionValues: conversationDimensionValues(columns, rows),
+                dimensionValues: conversationDimensionValues(columns, memberRows),
                 measureColumns,
                 rowCount: typeof rowCountRaw === 'number' ? rowCountRaw : rows.length || undefined,
             }
@@ -416,6 +441,8 @@ export async function startLocalServer(opts) {
     const loopback = bindHost === '127.0.0.1' || bindHost === 'localhost' || bindHost === '::1';
     const authToken = opts.authToken ?? process.env.DQL_SERVER_TOKEN;
     const runtimeVersion = readDqlRuntimeVersion();
+    // Warm the latest-version cache in the background (2s cap, 24h cache; offline → unknown).
+    void fetchLatestPublishedDqlVersion();
     const allowedOrigins = new Set((opts.allowedOrigins ?? (process.env.DQL_ALLOWED_ORIGINS ?? '').split(','))
         .map((value) => value.trim().replace(/\/$/, ''))
         .filter(Boolean));
@@ -1084,7 +1111,12 @@ export async function startLocalServer(opts) {
         await runner.run({
             provider: resolvedProvider,
             messages: [
-                ...(request.history ?? []).map((message) => ({ role: message.role, content: message.text })),
+                // No-thread fallback path: bound the raw client history so follow-ups
+                // cannot inflate every provider call (8 turns × 4k chars).
+                ...(request.history ?? []).slice(-8).map((message) => ({
+                    role: message.role,
+                    content: message.text.length > 4_000 ? `${message.text.slice(0, 4_000)}…` : message.text,
+                })),
                 ...(isRepair
                     ? [{ role: 'assistant', content: `The prior attempt needs repair without changing the original question or requested output grain: ${repair?.repairHint}` }]
                     : []),
@@ -1420,6 +1452,9 @@ export async function startLocalServer(opts) {
             applySmartVisualization(governedAnswer, request.question);
         }
         catch (error) {
+            // Deadline/cancellation propagates to the engine, which renders the
+            // graceful "bounded execution deadline" outcome — never a provider error.
+            rethrowIfCancelled(error, request.signal);
             const message = formatAgentRunInfrastructureError(error, 'AI answer provider');
             return {
                 summary: message,
@@ -1445,8 +1480,9 @@ export async function startLocalServer(opts) {
             || governedAnswer.sourceCertifiedBlock
             || governedAnswer.dqlArtifact?.kind === 'certified_block'));
         const isExploratory = Boolean(governedAnswer.exploratoryCandidate);
+        const isExecutionFailure = agentAnswerHasExecutionFailure(governedAnswer);
         const isGroundingGap = governedAnswer.kind === 'no_answer'
-            && governedAnswer.refusalCode === 'grounding_gap'
+            && (governedAnswer.refusalCode === 'grounding_gap' || governedAnswer.refusalCode === 'modeling_gap')
             && !isExploratory;
         const isProviderError = governedAnswer.kind === 'no_answer' && governedAnswer.refusalCode === 'provider_error';
         // AGT-004: a rejected attribution/export/proof policy is a deliberate
@@ -1465,7 +1501,7 @@ export async function startLocalServer(opts) {
         const needsClarification = governedAnswer.kind === 'no_answer'
             && !isGroundingGap && !isProviderError && !isModelDeclined && !isPolicyBlocked;
         const sql = governedAnswer.proposedSql ?? governedAnswer.sql;
-        const runnableSql = governedAnswer.kind === 'no_answer' || (isExploratory && !governedAnswer.result)
+        const runnableSql = governedAnswer.kind === 'no_answer' || isExecutionFailure || (isExploratory && !governedAnswer.result)
             ? undefined
             : sql;
         // Render executed rows deterministically for ordinary lookups. A second LLM
@@ -1504,14 +1540,14 @@ export async function startLocalServer(opts) {
                 synthesizedAnswer = undefined;
             }
         }
-        const status = isProviderError
+        const status = isProviderError || isExecutionFailure
             ? 'blocked'
             : needsClarification
                 ? 'needs_clarification'
                 : isCertified || isSemantic
                     ? 'completed'
                     : 'needs_review';
-        const trustState = isProviderError
+        const trustState = isProviderError || isExecutionFailure
             ? 'blocked'
             : needsClarification
                 ? 'not_applicable'
@@ -1520,7 +1556,7 @@ export async function startLocalServer(opts) {
                     : isSemantic
                         ? 'governed'
                         : 'review_required';
-        const stopReason = isProviderError
+        const stopReason = isProviderError || isExecutionFailure
             ? 'blocked'
             : needsClarification
                 ? 'needs_clarification'
@@ -1531,33 +1567,41 @@ export async function startLocalServer(opts) {
                         : 'human_review_required';
         const nextActions = needsClarification
             ? [{ id: 'clarify', label: 'Clarify question', route: 'generated_answer' }]
-            : [
-                { id: 'create-block', label: governedAnswer.dqlArtifact ? 'Review DQL draft' : 'Create DQL draft', route: 'dql_block_draft', artifactKind: 'dql_block_draft' },
-                { id: 'research-gap', label: 'Research deeper', route: 'research' },
-                ...(runnableSql ? [{
-                        id: 'insert-sql',
-                        label: governedAnswer.dqlArtifact ? 'Insert as DQL cell' : 'Insert SQL preview',
-                        route: 'sql_cell',
-                        artifactKind: 'sql_cell',
-                    }] : []),
-            ];
+            : isExecutionFailure
+                ? [{ id: 'retry-after-connection', label: 'Retry after fixing the database connection', route: 'generated_answer' }]
+                : isGroundingGap
+                    ? [{ id: 'research-gap', label: 'Research missing metadata coverage', route: 'research', artifactKind: 'research_run' }]
+                    : [
+                        { id: 'create-block', label: governedAnswer.dqlArtifact ? 'Review DQL draft' : 'Create DQL draft', route: 'dql_block_draft', artifactKind: 'dql_block_draft' },
+                        { id: 'research-gap', label: 'Research deeper', route: 'research' },
+                        ...(runnableSql ? [{
+                                id: 'insert-sql',
+                                label: governedAnswer.dqlArtifact ? 'Insert as DQL cell' : 'Insert SQL preview',
+                                route: 'sql_cell',
+                                artifactKind: 'sql_cell',
+                            }] : []),
+                    ];
         return {
             resolvedRoute,
             answerRefusalCode: governedAnswer.kind === 'no_answer' ? governedAnswer.refusalCode : undefined,
             answerTier: governedAnswer.route?.tier,
-            summary: governedAnswer.route?.label ?? (isCertified ? 'Answered from certified DQL context.' : isExploratory ? 'Exploratory DBT-grounded analysis requires review.' : 'Answered with review-required generated analysis.'),
+            summary: isExecutionFailure
+                ? 'The governed query could not be executed.'
+                : governedAnswer.route?.label ?? (isCertified ? 'Answered from certified DQL context.' : isExploratory ? 'Exploratory DBT-grounded analysis requires review.' : 'Answered with review-required generated analysis.'),
             answer: synthesizedAnswer ?? governedAnswer.answer ?? governedAnswer.text,
             status,
             trustState,
             stopReason,
-            artifacts: governedAnswer.kind === 'no_answer'
-                // A refusal still keeps the DQL draft the answer loop produced (when any),
-                // so the "Review DQL draft" next-action isn't a dead link and the user can
-                // see the SQL that was about to run. Provider outages carry no draft.
-                ? (governedAnswer.dqlArtifact && !isProviderError
-                    ? [agentRunArtifact('dql_block_draft', 'DQL draft (review required)', governedAnswer.dqlArtifact, undefined, 'review_required')]
-                    : [])
-                : [agentRunArtifact('answer', isCertified ? 'Certified answer' : isSemantic ? 'Governed semantic answer' : isExploratory ? 'Exploratory DBT-grounded answer' : 'Review-required answer', governedAnswer, governedAnswer.sourceCertifiedBlock ?? governedAnswer.block?.name, isCertified ? 'certified' : isSemantic ? 'governed' : 'review_required')],
+            artifacts: isExecutionFailure
+                ? []
+                : governedAnswer.kind === 'no_answer'
+                    // A refusal still keeps the DQL draft the answer loop produced (when any),
+                    // so the "Review DQL draft" next-action isn't a dead link and the user can
+                    // see the SQL that was about to run. Provider outages carry no draft.
+                    ? (governedAnswer.dqlArtifact && !isProviderError && !isGroundingGap && !isModelDeclined && !isPolicyBlocked
+                        ? [agentRunArtifact('dql_block_draft', 'DQL draft (review required)', governedAnswer.dqlArtifact, undefined, 'review_required')]
+                        : [])
+                    : [agentRunArtifact('answer', isCertified ? 'Certified answer' : isSemantic ? 'Governed semantic answer' : isExploratory ? 'Exploratory DBT-grounded answer' : 'Review-required answer', governedAnswer, governedAnswer.sourceCertifiedBlock ?? governedAnswer.block?.name, isCertified ? 'certified' : isSemantic ? 'governed' : 'review_required')],
             evaluations: [
                 agentRunEvaluation('route-decision', 'Route decision', true, 'info', routeDecision?.reason ?? 'Routed request to governed answer.', {
                     plannedRoute: route,
@@ -1586,6 +1630,7 @@ export async function startLocalServer(opts) {
                                 : isExploratory
                                     ? 'The answer used bounded DBT/schema evidence because no certified modeled relationship path covered the request. It is review-required and was not certified.'
                                     : 'The answer is generated or semantic-layer backed and remains review-required.', governedAnswer.route),
+                ...(isExecutionFailure ? [agentRunEvaluation('query-execution', 'Query execution', false, 'blocking', `The governed query failed before it produced a result: ${governedAnswer.executionError}`)] : []),
                 ...(isGroundingGap ? [
                     {
                         ...agentRunEvaluation('grounding-gap', 'Metadata grounding', false, 'warning', 'The bounded lookup could not prove the required metadata grounding. No automatic retry or Research escalation was started.', {
@@ -1767,6 +1812,7 @@ export async function startLocalServer(opts) {
                     }
                 }
                 catch (error) {
+                    rethrowIfCancelled(error, request.signal);
                     researchWorkspaceError = formatNotebookResearchStorageError(error);
                 }
             }
@@ -2171,6 +2217,7 @@ export async function startLocalServer(opts) {
             : undefined;
         const task = buildLocalContextPack(projectRoot, {
             question: request.question,
+            focusObjectKey: request.selectedEvidenceId,
             followUp,
             priorContextPackId: agentRunString(request.conversationContext?.contextPackId),
             conversationTopicRelation: topicRelation === 'continuation'
@@ -2246,9 +2293,9 @@ export async function startLocalServer(opts) {
                     };
                 }
                 if ((candidate.kind === 'semantic_metric' || candidate.kind === 'semantic_member')
-                    && semanticEvidence.has(candidate.id)
-                    && pack.routeDecision.route !== 'clarify'
-                    && pack.routeDecision.route !== 'conflict') {
+                    && (semanticEvidence.has(candidate.id) || request.selectedEvidenceId === candidate.id)
+                    && (request.selectedEvidenceId === candidate.id
+                        || (pack.routeDecision.route !== 'clarify' && pack.routeDecision.route !== 'conflict'))) {
                     const requestedDimensions = pack.questionPlan.requestedShape.dimensions.map((dimension) => dimension.toLowerCase());
                     const availableDimensions = (candidate.dimensions ?? []).map((dimension) => dimension.toLowerCase());
                     const dimensionsFit = requestedDimensions.length === 0 || requestedDimensions.every((requested) => availableDimensions.some((available) => available === requested || available.endsWith(`.${requested}`)));
@@ -2335,7 +2382,13 @@ export async function startLocalServer(opts) {
         getEvidence: buildAgentRunEvidence,
         getCatalogContext: buildRankedAgentRunCatalogContext,
     });
-    const agentRunStore = new FileAgentRunStore({ path: defaultAgentRunStorePath(projectRoot) });
+    // P0: one row per run with retention + old-run compaction. The legacy JSON
+    // store rewrote the entire file (123 MB observed) twice per answered question;
+    // existing history is imported once and the JSON renamed to *.migrated.
+    const agentRunStore = new SqliteAgentRunStore({
+        path: defaultAgentRunSqlitePath(projectRoot),
+        legacyJsonPath: defaultAgentRunStorePath(projectRoot),
+    });
     // A run may outlive its streaming browser connection, so cancellation is
     // server-owned and keyed by run id rather than relying on fetch abort alone.
     const activeAgentRunControllers = new Map();
@@ -2557,7 +2610,7 @@ export async function startLocalServer(opts) {
         const preflight = repairExploratorySqlBeforeExecution(candidate.sql, schemaContext, question);
         const boundedSql = applyRequestedTopNToExploratorySql(preflight.sql, requestedTopN);
         const repairs = boundedSql === preflight.sql
-            ? preflight.repairs
+            ? [...preflight.repairs]
             : [...preflight.repairs, `Applied the requested overall top-${requestedTopN} bound before exploratory execution.`];
         if (preflight.blockedReason) {
             return {
@@ -2571,19 +2624,62 @@ export async function startLocalServer(opts) {
         if (!analysis.parsed) {
             return { proofs: [], sql: boundedSql, repairs, error: 'DQL could not parse the exploratory SQL to validate its join predicates.' };
         }
+        const probeableJoins = probeableExploratoryJoins(analysis.joins, analysis.ctes);
         // A normal customer → order → order-item → product question needs three
         // joins. Keep the lane bounded, but do not reject this common dbt-star path
-        // solely because the old two-join demo limit was too small.
-        if (analysis.joins.length > 4) {
+        // solely because the old two-join demo limit was too small. CTE-internal
+        // joins are counted physically (they appear in analysis.joins with their
+        // physical endpoints); joins ON a CTE are restructuring, not new paths.
+        if (probeableJoins.length > 4) {
             return { proofs: [], sql: boundedSql, repairs, error: 'This exploratory query has more than four joins and requires an analyst to review the relationship path.' };
         }
-        if (analysis.joins.some((join) => !join.leftRelation || !join.rightRelation)) {
+        if (probeableJoins.some((join) => !join.leftRelation || !join.rightRelation)) {
             return { proofs: [], sql: boundedSql, repairs, error: 'This exploratory query has a join endpoint DQL could not resolve for bounded validation.' };
         }
+        // Structural binding: when the candidate carries a declared draft join path,
+        // every SQL join must ride one of its edges on the declared key pair. A join
+        // outside the declared path (or on different keys) is not executed — it is a
+        // review-required modeling question, not a runtime guess.
+        const declaredEdges = candidate.exploratoryPath?.edges ?? [];
+        const joinEdges = new Map();
+        if (declaredEdges.length > 0) {
+            for (const [index, join] of probeableJoins.entries()) {
+                const edge = declaredEdges.find((value) => declaredExploratoryRelationMatches(join.leftRelation, value.fromRelation) && declaredExploratoryRelationMatches(join.rightRelation, value.toRelation)
+                    || declaredExploratoryRelationMatches(join.leftRelation, value.toRelation) && declaredExploratoryRelationMatches(join.rightRelation, value.fromRelation));
+                if (!edge) {
+                    return {
+                        proofs: [],
+                        sql: boundedSql,
+                        repairs,
+                        error: `The join between ${join.leftRelation} and ${join.rightRelation} is not part of the declared relationship path, so DQL did not execute it. Declare the relationship in the DQL model to enable it.`,
+                    };
+                }
+                const keyMatches = edge.keys.some((key) => exploratoryColumnsMatch(join.leftColumn, key.from) && exploratoryColumnsMatch(join.rightColumn, key.to)
+                    || exploratoryColumnsMatch(join.leftColumn, key.to) && exploratoryColumnsMatch(join.rightColumn, key.from));
+                if (!keyMatches) {
+                    return {
+                        proofs: [],
+                        sql: boundedSql,
+                        repairs,
+                        error: `The join ${join.leftColumn} = ${join.rightColumn} uses different keys than relationship "${edge.relationshipId}" declares (${edge.keys.map((key) => `${key.from}=${key.to}`).join(', ')}). Review the declared keys before executing.`,
+                    };
+                }
+                joinEdges.set(index, edge);
+            }
+            const exercised = new Set([...joinEdges.values()].map((edge) => edge.relationshipId));
+            for (const edge of declaredEdges) {
+                if (!exercised.has(edge.relationshipId)) {
+                    repairs.push(`Declared relationship "${edge.relationshipId}" was not exercised by this query.`);
+                }
+            }
+        }
+        if (probeableJoins.length < analysis.joins.length) {
+            repairs.push(`Skipped join probes for ${analysis.joins.length - probeableJoins.length} join(s) on derived (CTE) relations; the final query execution validates them.`);
+        }
         const activeConnection = requireActiveConnection();
         const proofs = [];
         try {
-            for (const join of analysis.joins) {
+            for (const [index, join] of probeableJoins.entries()) {
                 const proofSql = buildExploratoryJoinProbeSql({
                     leftRelation: join.leftRelation,
                     leftColumn: join.leftColumn,
@@ -2593,6 +2689,14 @@ export async function startLocalServer(opts) {
                 const prepared = prepareLocalExecution(proofSql, activeConnection, projectRoot, projectConfig);
                 const raw = await executor.executeQuery(prepared.sql, [], runtimeVariables({}), prepared.connection);
                 proofs.push({ summary: summarizeExploratoryJoinProbe(raw.rows, join.leftRelation, join.leftColumn, join.rightRelation, join.rightColumn) });
+                // Gating (not observational): a structural contradiction between the
+                // UNFILTERED key overlap and the declared relationship stops automatic
+                // execution. A legitimately empty *filtered* business result is still an
+                // answer — these gates only inspect the raw key samples.
+                const contradiction = exploratoryProbeContradiction(raw.rows, join, joinEdges.get(index));
+                if (contradiction) {
+                    return { proofs, sql: boundedSql, repairs, error: contradiction };
+                }
             }
             const result = await executeGeneratedSqlForAgent(boundedSql);
             return { result, proofs, sql: boundedSql, repairs };
@@ -3713,8 +3817,19 @@ export async function startLocalServer(opts) {
             }
         }
         if (req.method === 'GET' && path === '/api/health') {
+            // REL-002: expose runtime/build identity so a server started before a
+            // rebuild or running a different version than the project pin is visibly
+            // stale. Uses only the cached latest-version lookup — never blocks.
+            const versionStatus = resolveDqlRuntimeVersionStatus({ projectRoot, runningVersion: runtimeVersion });
+            void fetchLatestPublishedDqlVersion();
+            const healthValueGrounding = resolveAgentRuntimeValueGrounding(projectConfig);
+            const retrievalHealth = resolveRetrievalHealthStatus({
+                projectRoot,
+                valueGroundingMode: healthValueGrounding.mode,
+                searchSafeColumnCount: healthValueGrounding.searchSafeColumns.size,
+            });
             res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
-            res.end(serializeJSON({ status: 'ok', version: runtimeVersion }));
+            res.end(serializeJSON({ status: 'ok', version: runtimeVersion, versionStatus, retrievalHealth }));
             return;
         }
         if (req.method === 'GET' && path === '/api/onboarding/launch') {
@@ -4523,6 +4638,11 @@ export async function startLocalServer(opts) {
                 const conversationStore = parsed.request.threadId ? getConversationStore() : null;
                 if (conversationStore && parsed.request.threadId && conversationStore.getThread(parsed.request.threadId)) {
                     parsed.request.conversationContext = await conversationContextFromThread(conversationStore, parsed.request.threadId, parsed.request.conversationContext, parsed.request.question);
+                    // The persisted thread is authoritative for prior turns. Raw client
+                    // history would duplicate the same conversation into the prompt a
+                    // second time — dropping it keeps follow-up prompts bounded.
+                    if (parsed.request.history?.length)
+                        parsed.request.history = [];
                 }
                 const wantsStream = url.searchParams.get('stream') === '1' || url.searchParams.get('stream') === 'true';
                 const runId = parsed.request.runId;
@@ -8722,6 +8842,12 @@ export async function startLocalServer(opts) {
                 }));
                 return;
             }
+            const provider = semanticConfig?.provider ?? semanticDetectedProvider ?? 'dql';
+            const dbtManifestReady = provider === 'dbt'
+                ? hasDbtSemanticManifest(projectRoot, semanticConfig?.projectPath)
+                : false;
+            const metricFlowReady = provider === 'dbt' ? hasMetricFlowCli() : false;
+            const dbtExecutionReady = dbtManifestReady && metricFlowReady;
             const metrics = semanticLayer.listMetrics().map((m) => ({
                 name: m.name,
                 label: m.label,
@@ -8736,6 +8862,7 @@ export async function startLocalServer(opts) {
                 typeParams: m.typeParams ?? null,
                 filter: m.filter ?? null,
                 source: m.source ?? null,
+                execution: semanticMetricExecutionCapability(m.name, semanticLayer, provider, metricFlowReady, connection?.driver),
             }));
             const measures = semanticLayer.listMeasures().map((m) => ({
                 name: m.name,
@@ -8833,12 +8960,6 @@ export async function startLocalServer(opts) {
                 owner: q.owner ?? null,
                 source: q.source ?? null,
             }));
-            const provider = semanticConfig?.provider ?? semanticDetectedProvider ?? 'dql';
-            const dbtManifestReady = provider === 'dbt'
-                ? hasDbtSemanticManifest(projectRoot, semanticConfig?.projectPath)
-                : false;
-            const metricFlowReady = provider === 'dbt' ? hasMetricFlowCli() : false;
-            const dbtExecutionReady = dbtManifestReady && metricFlowReady;
             const dbtExecutionSetup = dbtExecutionReady
                 ? null
                 : !dbtManifestReady && !metricFlowReady
@@ -9753,8 +9874,20 @@ export async function startLocalServer(opts) {
                     tableMapping,
                 });
                 if (!composed) {
+                    const provider = semanticConfig?.provider ?? semanticDetectedProvider ?? 'dql';
+                    const metricFlowReady = provider === 'dbt' && hasMetricFlowCli();
+                    const blocked = metrics.map((metricName) => ({
+                        metric: metricName,
+                        ...semanticMetricExecutionCapability(metricName, semanticLayer, provider, metricFlowReady, driver),
+                    })).filter((capability) => capability.status !== 'ready');
                     res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
-                    res.end(serializeJSON({ error: `Could not compose query for metrics: [${metrics.join(', ')}]` }));
+                    res.end(serializeJSON({
+                        error: blocked.length > 0
+                            ? blocked.map((capability) => `${capability.metric}: ${capability.reason}`).join(' ')
+                            : 'The selected dimensions do not share a governed join path with every selected metric.',
+                        code: blocked.length > 0 ? 'SEMANTIC_RUNTIME_REQUIRED' : 'SEMANTIC_FIELDS_INCOMPATIBLE',
+                        details: { metrics, dimensions, blocked },
+                    }));
                     return;
                 }
                 // Execute the composed SQL against the resolved connection
@@ -9839,8 +9972,20 @@ export async function startLocalServer(opts) {
                     tableMapping,
                 });
                 if (!composed) {
+                    const provider = semanticConfig?.provider ?? semanticDetectedProvider ?? 'dql';
+                    const metricFlowReady = provider === 'dbt' && hasMetricFlowCli();
+                    const blocked = metrics.map((metricName) => ({
+                        metric: metricName,
+                        ...semanticMetricExecutionCapability(metricName, semanticLayer, provider, metricFlowReady, driver),
+                    })).filter((capability) => capability.status !== 'ready');
                     res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
-                    res.end(serializeJSON({ error: 'Could not compose semantic block preview SQL.' }));
+                    res.end(serializeJSON({
+                        error: blocked.length > 0
+                            ? blocked.map((capability) => `${capability.metric}: ${capability.reason}`).join(' ')
+                            : 'The selected dimensions do not share a governed join path with every selected metric.',
+                        code: blocked.length > 0 ? 'SEMANTIC_RUNTIME_REQUIRED' : 'SEMANTIC_FIELDS_INCOMPATIBLE',
+                        details: { metrics, dimensions, blocked },
+                    }));
                     return;
                 }
                 const prepared = prepareLocalExecution(composed.sql, targetConnection, projectRoot, projectConfig);
@@ -13063,6 +13208,16 @@ export function buildExploratoryJoinProbeSql(input) {
     SELECT right_key, COUNT(*) AS match_count
     FROM matches
     GROUP BY right_key
+  ),
+  left_key_counts AS (
+    SELECT join_key, COUNT(*) AS key_count
+    FROM left_sample
+    GROUP BY join_key
+  ),
+  right_key_counts AS (
+    SELECT join_key, COUNT(*) AS key_count
+    FROM right_sample
+    GROUP BY join_key
   )
 SELECT
   (SELECT COUNT(*) FROM left_sample) AS left_sample_rows,
@@ -13071,7 +13226,87 @@ SELECT
   (SELECT COUNT(*) FROM left_sample AS l WHERE NOT EXISTS (SELECT 1 FROM right_sample AS r WHERE r.join_key = l.join_key)) AS unmatched_left_sample_rows,
   (SELECT COUNT(*) FROM right_sample AS r WHERE NOT EXISTS (SELECT 1 FROM left_sample AS l WHERE l.join_key = r.join_key)) AS unmatched_right_sample_rows,
   (SELECT COALESCE(MAX(match_count), 0) FROM left_counts) AS max_matches_per_left_key,
-  (SELECT COALESCE(MAX(match_count), 0) FROM right_counts) AS max_matches_per_right_key`;
+  (SELECT COALESCE(MAX(match_count), 0) FROM right_counts) AS max_matches_per_right_key,
+  (SELECT COALESCE(MAX(key_count), 0) FROM left_key_counts) AS max_left_rows_per_key,
+  (SELECT COALESCE(MAX(key_count), 0) FROM right_key_counts) AS max_right_rows_per_key`;
+}
+/**
+ * CTE names are query-internal derived relations, not warehouse tables. A join
+ * whose endpoint is a CTE (e.g. `WITH joy_items AS (…) … JOIN joy_items`) must
+ * be excluded from declared-path enforcement and from join probes — probing
+ * `FROM "joy_items"` throws a DuckDB catalog error for a table that was never
+ * supposed to exist. The physical joins INSIDE the CTE are still present in
+ * the parsed join list and get validated/probed on their own.
+ */
+export function probeableExploratoryJoins(joins, ctes) {
+    const cteNames = new Set(ctes.map((name) => name.split('.').at(-1)?.toLowerCase() ?? name.toLowerCase()));
+    if (cteNames.size === 0)
+        return joins;
+    return joins.filter((join) => ![join.leftRelation, join.rightRelation].some((relation) => {
+        const bare = relation?.replace(/["`\[\]]/g, '').split('.').at(-1)?.toLowerCase();
+        return Boolean(bare && cteNames.has(bare));
+    }));
+}
+function declaredExploratoryRelationMatches(sqlRelation, declaredRelation) {
+    if (!declaredRelation)
+        return false;
+    const normalize = (value) => value.replace(/["`\[\]]/g, '').trim();
+    return exploratoryRelationsMatch(normalize(sqlRelation), normalize(declaredRelation));
+}
+function exploratoryColumnsMatch(sqlColumn, declaredColumn) {
+    const normalize = (value) => value.replace(/["`\[\]]/g, '').split('.').at(-1)?.trim().toLowerCase() ?? value.toLowerCase();
+    return normalize(sqlColumn) === normalize(declaredColumn);
+}
+/**
+ * Gate a join probe against the declared relationship. Returns an error string
+ * when the UNFILTERED key samples structurally contradict the declaration:
+ * - zero key overlap while both sides have rows (wrong/mistyped key), or
+ * - duplicate keys on the declared "one" side of a *_to_one / one_to_* edge.
+ * Sampling caveat: gates only fire on definitive contradictions, never on low
+ * match rates, so a sparse but real relationship still executes.
+ */
+export function exploratoryProbeContradiction(rows, join, edge) {
+    const row = Array.isArray(rows) && rows[0] && typeof rows[0] === 'object'
+        ? rows[0]
+        : {};
+    const number = (key) => {
+        const value = Number(row[key]);
+        return Number.isFinite(value) ? value : 0;
+    };
+    const leftRows = number('left_sample_rows');
+    const rightRows = number('right_sample_rows');
+    const joined = number('joined_rows');
+    if (leftRows > 0 && rightRows > 0 && joined === 0) {
+        return `The join key ${join.leftColumn} = ${join.rightColumn} produced no matching rows between ${join.leftRelation} and ${join.rightRelation} (unfiltered sample). The declared key pair is likely wrong — review the relationship before executing this analysis.`;
+    }
+    if (!edge)
+        return undefined;
+    // Orient the declared cardinality onto the parsed join: which physical side is
+    // the declared "one" side? Duplicated keys there contradict the declaration.
+    const leftIsFrom = Boolean(join.leftRelation && declaredExploratoryRelationMatches(join.leftRelation, edge.fromRelation));
+    const rightIsFrom = Boolean(join.rightRelation && declaredExploratoryRelationMatches(join.rightRelation, edge.fromRelation));
+    if (leftIsFrom === rightIsFrom)
+        return undefined; // orientation unresolved — do not guess
+    const oneSide = edge.cardinality === 'many_to_one' ? 'to' : edge.cardinality === 'one_to_many' ? 'from' : edge.cardinality === 'one_to_one' ? 'both' : undefined;
+    if (!oneSide)
+        return undefined;
+    // Per-side key duplication measured WITHIN each sample (max rows sharing one
+    // key value). Duplicates inside a sample are definitive — a subset of a table
+    // cannot show duplicates the full table does not have. The pairwise
+    // max_matches_* columns are NOT used here: they inflate whenever the
+    // legitimate "many" side repeats a key value.
+    const leftDuplicated = number('max_left_rows_per_key') > 1;
+    const rightDuplicated = number('max_right_rows_per_key') > 1;
+    const fromSideIsLeft = leftIsFrom;
+    const duplicatedSides = [
+        ...(leftDuplicated ? [fromSideIsLeft ? 'from' : 'to'] : []),
+        ...(rightDuplicated ? [fromSideIsLeft ? 'to' : 'from'] : []),
+    ];
+    const violated = oneSide === 'both' ? duplicatedSides.length > 0 : duplicatedSides.includes(oneSide);
+    if (violated) {
+        return `Relationship "${edge.relationshipId}" declares ${edge.cardinality}, but the sampled join keys show duplicates on the declared unique side. Executing would duplicate rows — validate and correct the relationship first.`;
+    }
+    return undefined;
 }
 function summarizeExploratoryJoinProbe(rows, leftRelation, leftColumn, rightRelation, rightColumn) {
     const row = Array.isArray(rows) && rows[0] && typeof rows[0] === 'object'
@@ -13671,6 +13906,28 @@ export function openBlockStudioDocument(projectRoot, relativePath, semanticLayer
         validation: validateBlockStudioSource(source, semanticLayer),
     };
 }
+function semanticMetricExecutionCapability(metricName, semanticLayer, provider, metricFlowReady, driver) {
+    if (provider === 'dbt' && metricFlowReady) {
+        return { status: 'ready', engine: 'metricflow', reason: null };
+    }
+    const native = semanticLayer.composeQuery({ metrics: [metricName], dimensions: [], driver });
+    if (native)
+        return { status: 'ready', engine: 'native', reason: null };
+    const metric = semanticLayer.getMetric(metricName);
+    if (provider === 'dbt') {
+        const kind = metric?.metricType || metric?.aggregation || metric?.type || 'metric';
+        return {
+            status: 'requires_setup',
+            engine: null,
+            reason: `${kind} metric requires MetricFlow execution. Install/configure the MetricFlow CLI, then refresh the semantic layer.`,
+        };
+    }
+    return {
+        status: 'unsupported',
+        engine: null,
+        reason: 'The metric does not have enough composable measure and relation metadata.',
+    };
+}
 function parseBlockStudioArrayField(source, key) {
     const match = source.match(new RegExp(`\\b${key}\\s*=\\s*\\[([\\s\\S]*?)\\]`, 'i'));
     if (!match)
@@ -13905,10 +14162,18 @@ function composeSemanticBlockSql(source, semanticLayer, options) {
         return { sql: null, diagnostics, semanticRefs };
     }
     if (!composed) {
+        const provider = options?.projectConfig && isDbtSemanticRuntime(options.projectConfig, options.detectedProvider, semanticLayer) ? 'dbt' : (options?.detectedProvider ?? 'dql');
+        const metricFlowReady = provider === 'dbt' && hasMetricFlowCli();
+        const reasons = metrics.map((metricName) => {
+            const capability = semanticMetricExecutionCapability(metricName, semanticLayer, provider, metricFlowReady, options?.driver);
+            return capability.status === 'ready' ? null : `${metricName}: ${capability.reason}`;
+        }).filter((reason) => Boolean(reason));
         diagnostics.push({
             severity: 'error',
             code: 'semantic_compose_failed',
-            message: `Could not compose SQL for semantic block metrics: [${metrics.join(', ')}].`,
+            message: reasons.length > 0
+                ? `Could not compose SQL for semantic block metrics. ${reasons.join(' ')}`
+                : `Could not compose SQL for semantic block metrics: [${metrics.join(', ')}]. Check that the selected dimensions share a governed join path.`,
         });
         return { sql: null, diagnostics, semanticRefs };
     }