@duckcodeailabs/dql-cli 1.8.0 → 1.8.2

package/dist/local-runtime.js

@@ -16,7 +16,7 @@ import { listBlockTemplates } from './block-templates.js';
 import { getRunner as getLLMRunner } from './llm/index.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, 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, 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 { gatherProposeEnrichment } from './propose-enrich.js';
 import { handleAppsApi, proposeAppAiBuild, recommendVisualization } from './apps-api.js';
 import { getActiveProvider, getEffectiveProviderConfig, isProviderSettingsId, listProviderSettings, saveProviderSettings, } from './settings/provider-settings.js';
@@ -36,18 +36,26 @@ const NOTEBOOK_FAVICON_SVG = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0
 export function resolveProjectSemanticConfig(projectConfig, projectRoot) {
     const configured = projectConfig.semanticLayer;
     const dbtProjectDir = projectConfig.dbt?.projectDir;
+    const dbtManifestPath = projectConfig.dbt?.manifestPath;
+    if (configured?.provider === 'dbt') {
+        return {
+            ...configured,
+            projectPath: configured.projectPath ?? dbtProjectDir,
+            manifestPath: configured.manifestPath ?? dbtManifestPath,
+        };
+    }
     if (dbtProjectDir
         && (!configured || configured.provider === 'dql')
-        && hasDbtSemanticArtifacts(projectRoot, dbtProjectDir)) {
-        return { provider: 'dbt', projectPath: dbtProjectDir };
+        && hasDbtSemanticArtifacts(projectRoot, dbtProjectDir, dbtManifestPath)) {
+        return { provider: 'dbt', projectPath: dbtProjectDir, manifestPath: dbtManifestPath };
     }
     return configured;
 }
-function hasDbtSemanticArtifacts(projectRoot, dbtProjectDir) {
+function hasDbtSemanticArtifacts(projectRoot, dbtProjectDir, configuredManifestPath) {
     const dbtRoot = resolve(projectRoot, dbtProjectDir);
-    if (existsSync(join(dbtRoot, 'target', 'semantic_manifest.json')))
+    const manifestPath = resolve(dbtRoot, configuredManifestPath ?? 'target/manifest.json');
+    if (existsSync(join(dirname(manifestPath), 'semantic_manifest.json')))
         return true;
-    const manifestPath = join(dbtRoot, 'target', 'manifest.json');
     if (!existsSync(manifestPath))
         return false;
     try {
@@ -137,6 +145,7 @@ export function parseAgentRunRequestBody(body) {
     return {
         request: {
             question,
+            selectedEvidenceId: agentRunString(record.selectedEvidenceId),
             requestedMode,
             audience,
             intent: agentRunString(record.intent),
@@ -189,6 +198,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)
@@ -272,16 +285,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);
@@ -305,7 +322,7 @@ function conversationTurnInputFromRun(run) {
             ? {
                 columns,
                 rowsSample,
-                dimensionValues: conversationDimensionValues(columns, rows),
+                dimensionValues: conversationDimensionValues(columns, memberRows),
                 measureColumns,
                 rowCount: typeof rowCountRaw === 'number' ? rowCountRaw : rows.length || undefined,
             }
@@ -421,6 +438,7 @@ export async function startLocalServer(opts) {
     if (gitRoot)
         ensureLocalRuntimeGitignore(projectRoot);
     let projectConfig = loadProjectConfig(projectRoot);
+    recordAgentRuntimeVersion(projectRoot, runtimeVersion);
     const configuredConnection = rawConnection
         ? normalizeProjectConnection(rawConnection, projectRoot)
         : projectConfig.defaultConnection
@@ -499,6 +517,8 @@ export async function startLocalServer(opts) {
                     const prepared = await ensureAgentProjectReady(projectRoot, {
                         kgPath: defaultKgPath(projectRoot),
                         manifest: input.manifest,
+                        forceKgIndex: input.forceRebuild,
+                        forceMetadataCatalog: input.forceRebuild,
                     });
                     const current = onboardingJobs.get(id);
                     if (!current || current.status === 'cancelled')
@@ -660,18 +680,25 @@ export async function startLocalServer(opts) {
     const semanticLayerDir = join(projectRoot, 'semantic-layer');
     let semanticImportManifest = loadSemanticImportManifest(projectRoot);
     const userPrefsPath = join(projectRoot, '.dql-user-prefs.json');
-    const semanticConfig = resolveProjectSemanticConfig(projectConfig, projectRoot);
+    let semanticConfig = resolveProjectSemanticConfig(projectConfig, projectRoot);
     let semanticLastSyncTime = null;
-    {
+    const reloadSemanticLayer = async () => {
+        semanticConfig = resolveProjectSemanticConfig(projectConfig, projectRoot);
         const semanticConnection = connection;
         const executeQuery = semanticConfig?.provider === 'snowflake' && semanticConnection
             ? async (sql) => { const r = await executor.executeQuery(sql, [], {}, semanticConnection); return { rows: r.rows }; }
             : undefined;
         const result = await resolveSemanticLayerAsync(semanticConfig, projectRoot, executeQuery);
-        semanticLayer = result.layer;
         semanticLayerErrors = result.errors;
         semanticDetectedProvider = result.detectedProvider;
-        semanticLastSyncTime = result.layer ? new Date().toISOString() : null;
+        if (result.layer) {
+            semanticLayer = result.layer;
+            semanticLastSyncTime = new Date().toISOString();
+        }
+        else if (result.errors.length === 0) {
+            semanticLayer = undefined;
+            semanticLastSyncTime = null;
+        }
         semanticImportManifest = loadSemanticImportManifest(projectRoot);
         // Legacy fallback if provider system returned nothing and no errors
         if (!semanticLayer && semanticLayerErrors.length === 0 && existsSync(semanticLayerDir)) {
@@ -681,8 +708,28 @@ export async function startLocalServer(opts) {
             }
             catch { /* continue without */ }
         }
-    }
+        return result;
+    };
+    await reloadSemanticLayer();
     await refreshLocalMetadataCatalog(projectRoot);
+    const startupDbtManifestPath = resolveDbtManifestPath(projectRoot, projectConfig);
+    if (startupDbtManifestPath && !isAgentProjectIndexReady(projectRoot)) {
+        try {
+            const startupSnapshot = projectSnapshot();
+            startDbtPreparationJob({
+                kind: 'dbt_prepare',
+                snapshotId: startupSnapshot.snapshotId,
+                manifest: startupSnapshot.manifest,
+                validationDurationMs: 0,
+                compileDurationMs: 0,
+                forceRebuild: true,
+            });
+        }
+        catch {
+            // Startup remains available with the last valid cache; Setup exposes the
+            // compile error and the next explicit refresh retries preparation.
+        }
+    }
     const recordDatasetMetadataSnapshot = (datasets = datasetWorkspace.list()) => {
         if (datasets.length === 0)
             return;
@@ -1407,6 +1454,7 @@ 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'
             && !isExploratory;
@@ -1427,7 +1475,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
@@ -1466,14 +1514,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'
@@ -1482,7 +1530,7 @@ export async function startLocalServer(opts) {
                     : isSemantic
                         ? 'governed'
                         : 'review_required';
-        const stopReason = isProviderError
+        const stopReason = isProviderError || isExecutionFailure
             ? 'blocked'
             : needsClarification
                 ? 'needs_clarification'
@@ -1493,33 +1541,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,
@@ -1548,6 +1604,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.', {
@@ -2133,6 +2190,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'
@@ -2208,9 +2266,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}`)));
@@ -3293,20 +3351,7 @@ export async function startLocalServer(opts) {
                     }
                     // Hot-reload semantic layer on change and notify frontend
                     if (dir === 'semantic-layer') {
-                        const semanticConnection = connection;
-                        const executeQuery = semanticConfig?.provider === 'snowflake' && semanticConnection
-                            ? async (sql) => { const r = await executor.executeQuery(sql, [], {}, semanticConnection); return { rows: r.rows }; }
-                            : undefined;
-                        resolveSemanticLayerAsync(semanticConfig, projectRoot, executeQuery).then((refreshed) => {
-                            if (refreshed.layer) {
-                                semanticLayer = refreshed.layer;
-                                semanticLayerErrors = refreshed.errors;
-                                semanticLastSyncTime = new Date().toISOString();
-                                semanticImportManifest = loadSemanticImportManifest(projectRoot);
-                            }
-                            else if (refreshed.errors.length > 0) {
-                                semanticLayerErrors = refreshed.errors;
-                            }
+                        reloadSemanticLayer().then(() => {
                             // Notify all connected notebook clients to re-fetch the semantic layer
                             const reloadPayload = JSON.stringify({ type: 'semantic-reload' });
                             for (const client of sseClients) {
@@ -3323,7 +3368,7 @@ export async function startLocalServer(opts) {
             }
             catch { /* dir not watchable */ }
         }
-        const configuredDbtManifest = resolveDbtManifestPath(projectRoot);
+        const configuredDbtManifest = resolveDbtManifestPath(projectRoot, projectConfig);
         if (configuredDbtManifest && existsSync(dirname(configuredDbtManifest))) {
             try {
                 watch(dirname(configuredDbtManifest), { persistent: false }, (_eventType, filename) => {
@@ -3344,6 +3389,17 @@ export async function startLocalServer(opts) {
                             sseClients.delete(client);
                         }
                     }
+                    void reloadSemanticLayer().then(() => {
+                        const reloadPayload = JSON.stringify({ type: 'semantic-reload' });
+                        for (const client of sseClients) {
+                            try {
+                                client.write(`event: change\ndata: ${reloadPayload}\n\n`);
+                            }
+                            catch {
+                                sseClients.delete(client);
+                            }
+                        }
+                    }).catch(() => { });
                 });
             }
             catch { /* dbt artifact directory not watchable */ }
@@ -3866,6 +3922,10 @@ export async function startLocalServer(opts) {
                 let snapshotManifest;
                 const compileStartedAt = Date.now();
                 try {
+                    const semanticReload = await reloadSemanticLayer();
+                    if (semanticReload.errors.length > 0) {
+                        throw new Error(`dbt semantic artifacts could not be loaded: ${semanticReload.errors.join('; ')}`);
+                    }
                     const snapshot = projectSnapshot();
                     snapshotId = snapshot.snapshotId;
                     snapshotManifest = snapshot.manifest;
@@ -3878,6 +3938,7 @@ export async function startLocalServer(opts) {
                     connection = previousConnection;
                     projectSnapshots.invalidate();
                     invalidateAgentProjectState(projectRoot);
+                    await reloadSemanticLayer();
                     throw Object.assign(new Error(`dbt-first configuration did not compile and was rolled back: ${error instanceof Error ? error.message : String(error)}`), { code: 'SNAPSHOT_BUILD_FAILED' });
                 }
                 const preparation = startDbtPreparationJob({
@@ -3918,6 +3979,7 @@ export async function startLocalServer(opts) {
                 const validationDurationMs = Date.now() - refreshStartedAt;
                 const compileStartedAt = Date.now();
                 projectSnapshots.invalidate();
+                await reloadSemanticLayer();
                 const snapshot = projectSnapshot();
                 invalidateAgentProjectState(projectRoot);
                 const job = startDbtPreparationJob({
@@ -8143,16 +8205,7 @@ export async function startLocalServer(opts) {
         }
         if (req.method === 'POST' && path === '/api/semantic-layer/reload') {
             try {
-                const semanticConnection = connection;
-                const executeQuery = semanticConfig?.provider === 'snowflake' && semanticConnection
-                    ? async (sql) => { const r = await executor.executeQuery(sql, [], {}, semanticConnection); return { rows: r.rows }; }
-                    : undefined;
-                const refreshed = await resolveSemanticLayerAsync(semanticConfig, projectRoot, executeQuery);
-                semanticLayer = refreshed.layer;
-                semanticLayerErrors = refreshed.errors;
-                semanticDetectedProvider = refreshed.detectedProvider;
-                semanticLastSyncTime = refreshed.layer ? new Date().toISOString() : null;
-                semanticImportManifest = loadSemanticImportManifest(projectRoot);
+                await reloadSemanticLayer();
                 const diagnostics = buildSemanticLayerDiagnostics(projectRoot, projectConfig, {
                     semanticLayer,
                     semanticErrors: semanticLayerErrors,
@@ -8162,7 +8215,7 @@ export async function startLocalServer(opts) {
                 });
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({
-                    ok: Boolean(refreshed.layer),
+                    ok: Boolean(semanticLayer),
                     ...diagnostics,
                 }));
             }
@@ -8689,6 +8742,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,
@@ -8703,6 +8762,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,
@@ -8800,12 +8860,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
@@ -9720,8 +9774,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
@@ -9806,8 +9872,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);
@@ -13638,6 +13716,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)
@@ -13872,10 +13972,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 };
     }