@duckcodeailabs/dql-cli 1.6.31 → 1.6.32

package/dist/local-runtime.js

@@ -1,4 +1,5 @@
 import { execFileSync, execSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { createServer } from 'node:http';
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, watch, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
@@ -7,19 +8,19 @@ import { dirname, extname, join, normalize, relative, resolve } from 'node:path'
 import Anthropic from '@anthropic-ai/sdk';
 import OpenAI from 'openai';
 import { buildExecutionPlan, createWelcomeNotebook, deserializeNotebook, getConnectorFormSchemas, hasSemanticRefs, resolveSemanticRefs, } from '@duckcodeailabs/dql-notebook';
-import { loadSemanticLayerFromDir, resolveSemanticLayerAsync, getDialect, Parser, buildLineageGraph, buildManifest, findAppDocuments, findDashboardsForApp, isBlockIdRef, loadAppDocument, loadDashboardDocument, analyzeImpact, buildTrustChain, detectDomainFlows, getDomainTrustOverview, queryLineage, queryBusiness360, queryCompleteLineagePaths, LineageGraph, canonicalize, canonicalizeNotebook, diffDQL, diffNotebook, writeDomainDeclaration, deleteDomainDeclaration, domainFolderSlug, } from '@duckcodeailabs/dql-core';
+import { loadSemanticLayerFromDir, normalizeDqlArtifactReference, serializeMetricDefinitionToYaml, resolveSemanticLayerAsync, getDialect, Parser, buildLineageGraph, buildManifest, findAppDocuments, findDashboardsForApp, isBlockIdRef, loadAppDocument, loadDashboardDocument, analyzeImpact, buildTrustChain, detectDomainFlows, getDomainTrustOverview, queryLineage, queryBusiness360, queryCompleteLineagePaths, LineageGraph, canonicalize, canonicalizeNotebook, diffDQL, diffNotebook, writeDomainDeclaration, deleteDomainDeclaration, domainFolderSlug, } from '@duckcodeailabs/dql-core';
 import { load as loadYaml } from 'js-yaml';
 import { listBlockTemplates } from './block-templates.js';
 import { getRunner as getLLMRunner } from './llm/index.js';
 import { createDqlAgentProviderRunner } from './llm/providers/dql-agent-provider.js';
 import { listRemoteMcpSettings, saveRemoteMcpSettings } from './llm/mcp-config.js';
-import { ClaudeProvider, GeminiProvider, MemoryStore, OllamaProvider, OpenAIProvider, buildBlockBusinessFingerprint, buildBlockSqlFingerprints, buildLocalContextPack, defaultMemoryPath, ensureDefaultMemoryFiles, ensureMetadataCatalogFresh, propose, proposePlan, recordCorrectionTrace, reviewHint, AgentRunEngine, FileAgentRunStore, defaultAgentRunGates, createLlmAgentRunPlanner, createHybridRouter, synthesizeAnswer, streamOrGenerate, narrateResult, normalizeAnthropicBaseUrl, buildProposePreview, buildFromPrompt, defaultAgentRunStorePath, resolveLocalOwner, resolveProposeConfig, recordQueryRun, recordRuntimeSchemaSnapshot, loadSkills, writeSkill, deleteSkill, reindexProject, defaultKgPath, planApp, planResearch, loadSemanticMetrics, routeReasoningEffort, clampReasoningEffort, bumpReasoningEffort, } from '@duckcodeailabs/dql-agent';
+import { ClaudeProvider, ConversationStore, advanceThreadState, buildConversationSnapshot, recallRelevantTurns, GeminiProvider, MemoryStore, OllamaProvider, OpenAIProvider, buildBlockBusinessFingerprint, buildBlockSqlFingerprints, buildLocalContextPack, defaultConversationPath, defaultMemoryPath, ensureDefaultMemoryFiles, ensureMetadataCatalogFresh, propose, proposePlan, recordCorrectionTrace, reviewHint, AgentRunEngine, FileAgentRunStore, defaultAgentRunGates, createLlmAgentRunPlanner, createHybridRouter, computeResultStats, synthesizeAnswer, streamOrGenerate, narrateResult, normalizeAnthropicBaseUrl, buildProposePreview, buildFromPrompt, defaultAgentRunStorePath, resolveLocalOwner, resolveProposeConfig, recordQueryRun, recordRuntimeSchemaSnapshot, loadSkills, writeSkill, deleteSkill, deriveGeneratedDraftSlug, reindexProject, defaultKgPath, planApp, planResearch, loadSemanticMetrics, routeReasoningEffort, routeForCascadeAnswerTier, clampReasoningEffort, bumpReasoningEffort, upsertGeneratedDqlArtifactDraft, } from '@duckcodeailabs/dql-agent';
 import { gatherProposeEnrichment } from './propose-enrich.js';
 import { handleAppsApi, proposeAppAiBuild, recommendVisualization } from './apps-api.js';
-import { getActiveProvider, getEffectiveProviderConfig, listProviderSettings, saveProviderSettings, } from './settings/provider-settings.js';
+import { getActiveProvider, getEffectiveProviderConfig, isProviderSettingsId, listProviderSettings, saveProviderSettings, } from './settings/provider-settings.js';
 import { ClaudeCodeCliProvider, CodexCliProvider } from './providers/subscription-cli.js';
-import { ClaudeOAuthManager, claudeOAuthConnected, CLAUDE_OAUTH_MODELS, CLAUDE_OAUTH_DEFAULT_MODEL, } from './providers/oauth/claude-oauth.js';
-import { CodexOAuthManager, codexOAuthConnected, CODEX_OAUTH_MODELS, CODEX_OAUTH_DEFAULT_MODEL, } from './providers/oauth/codex-oauth.js';
+import { ClaudeOAuthManager, ClaudeOAuthProvider, claudeOAuthConnected, CLAUDE_OAUTH_MODELS, CLAUDE_OAUTH_DEFAULT_MODEL, } from './providers/oauth/claude-oauth.js';
+import { CodexOAuthManager, CodexOAuthProvider, codexOAuthConnected, CODEX_OAUTH_MODELS, CODEX_OAUTH_DEFAULT_MODEL, } from './providers/oauth/codex-oauth.js';
 import { DQLAccessDeniedError, activePersonaAppId, assertAppAccess, loadRuntimeApp, runtimeVariables, } from './governance-runtime.js';
 import { LocalAppStorage, LocalNotebookResearchStorage, defaultLocalAppsDbPath, defaultNotebookResearchDbPath } from '@duckcodeailabs/dql-project';
 import { Certifier, ENTERPRISE_RULES, evaluateInvariants, hasInvariantViolation, } from '@duckcodeailabs/dql-governance';
@@ -78,6 +79,16 @@ function parseAgentRunRequestedMode(value) {
         ? value
         : undefined;
 }
+function parseAgentRunReasoningEffort(value) {
+    return value === 'low' || value === 'medium' || value === 'high'
+        ? value
+        : undefined;
+}
+function parseAgentRunAnalysisDepth(value) {
+    return value === 'quick' || value === 'deep'
+        ? value
+        : undefined;
+}
 function parseAgentRunSelectedObject(value) {
     const record = agentRunRecord(value);
     if (!record)
@@ -105,7 +116,7 @@ function parseAgentRunHistory(value) {
     });
     return history.length > 0 ? history.slice(-20) : undefined;
 }
-function parseAgentRunRequestBody(body) {
+export function parseAgentRunRequestBody(body) {
     const record = agentRunRecord(body);
     if (!record)
         return { error: 'Invalid JSON body.' };
@@ -128,11 +139,181 @@ function parseAgentRunRequestBody(body) {
             signals: signals,
             selectedObject,
             workspaceContext,
+            conversationContext: agentRunRecord(record.conversationContext),
             history: parseAgentRunHistory(record.history),
+            threadId: agentRunString(record.threadId),
             runId: agentRunString(record.runId),
+            reasoningEffort: parseAgentRunReasoningEffort(record.reasoningEffort),
+            analysisDepth: parseAgentRunAnalysisDepth(record.analysisDepth) ?? parseAgentRunAnalysisDepth(record.depth),
         },
     };
 }
+export function shouldSynthesizeAgentRunAnswer(governedAnswer) {
+    if (governedAnswer.kind === 'no_answer')
+        return false;
+    if (governedAnswer.kind === 'certified' || governedAnswer.certification === 'certified')
+        return false;
+    const finalText = (governedAnswer.answer ?? governedAnswer.text ?? '').trim();
+    if (governedAnswer.dqlArtifact && finalText)
+        return false;
+    return true;
+}
+// ── Server-side conversation threads ────────────────────────────────────────
+// When a run carries a threadId, the persisted thread is the authoritative
+// 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) => {
+        const contract = turn.contract ?? {};
+        const topN = contract.topN;
+        const topNValue = typeof topN === 'number'
+            ? topN
+            : topN && typeof topN === 'object' && typeof topN.n === 'number'
+                ? topN.n
+                : undefined;
+        return compactConversationRecord({
+            id: turn.id,
+            question: turn.question,
+            answerSummary: turn.answerSummary,
+            sourceCertifiedBlock: turn.sourceCertifiedBlock,
+            route: turn.route,
+            trustLabel: turn.trustLabel,
+            certification: turn.certification,
+            contextPackId: turn.contextPackId,
+            dqlArtifact: turn.dqlArtifact,
+            cascade: turn.cascade,
+            sourceSql: turn.sql,
+            requestedFilters: conversationStringArray(contract.filters),
+            requestedDimensions: conversationStringArray(contract.dimensions),
+            requestedMeasures: conversationStringArray(contract.measures),
+            topN: topNValue,
+            result: turn.result
+                ? compactConversationRecord({
+                    columns: turn.result.columns,
+                    rowsSample: turn.result.rowsSample,
+                    dimensionValues: turn.result.dimensionValues,
+                    measureColumns: turn.result.measureColumns,
+                    rowCount: turn.result.rowCount,
+                })
+                : undefined,
+        });
+    }).filter((turn) => Boolean(turn));
+    const thread = store.getThread(threadId);
+    // Bounded structured snapshot (working state + rolling summary + topic relation)
+    // for the answer loop's conversation-state prompt section.
+    const serverSnapshot = buildConversationSnapshot(store, threadId, { question });
+    if (serverSnapshot && question) {
+        // Semantic recall over OLDER turns (the recent window is already verbatim).
+        serverSnapshot.recalledTurns = await recallRelevantTurns(store, threadId, question, {
+            limit: 3,
+            excludeTurnIds: serverSnapshot.recentTurns.map((turn) => turn.id),
+        });
+    }
+    return {
+        ...(clientContext ?? {}),
+        conversationStateVersion: 1,
+        threadId,
+        ...(serverSnapshot ? { serverSnapshot } : {}),
+        ...(thread?.rollingSummary ? { conversationSummary: thread.rollingSummary } : {}),
+        ...(turns.length > 0 ? { turns, activeTurnId: turns[turns.length - 1].id } : {}),
+    };
+}
+/** Best-effort: persist a completed run as a conversation turn (never throws). */
+function recordConversationTurn(store, threadId, run) {
+    if (!store || !threadId)
+        return;
+    try {
+        if (!store.getThread(threadId))
+            return;
+        const turn = store.appendTurn(threadId, conversationTurnInputFromRun(run));
+        // Fold the turn into the thread's working state + rolling summary (incremental).
+        advanceThreadState(store, threadId, turn);
+    }
+    catch {
+        // Conversation persistence is additive; a failed write must not fail the run.
+    }
+}
+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)
+        : [];
+    const rowsSample = rows.map((row) => columns.map((column) => row[column]));
+    const contextPack = agentRunRecord(payload?.contextPack);
+    const questionPlan = agentRunRecord(contextPack?.questionPlan);
+    const requestedShape = agentRunRecord(questionPlan?.requestedShape);
+    const rowCountRaw = result?.rowCount;
+    const measureColumns = conversationMeasureColumns(columns, requestedShape, rows);
+    return {
+        question: run.question,
+        answerSummary: run.answer ?? run.summary,
+        route: run.route,
+        trustLabel: agentRunString(payload?.trustLabel) ?? run.trustState,
+        certification: agentRunString(payload?.certification),
+        sourceCertifiedBlock: agentRunString(payload?.sourceCertifiedBlock)
+            ?? (artifact?.kind === 'answer' ? agentRunString(artifact.ref) : undefined),
+        contextPackId: agentRunString(payload?.contextPackId),
+        sql: agentRunString(payload?.proposedSql) ?? agentRunString(payload?.sql),
+        dqlArtifact: agentRunRecord(payload?.dqlArtifact),
+        cascade: agentRunRecord(payload?.cascade),
+        result: columns.length > 0 || rows.length > 0
+            ? {
+                columns,
+                rowsSample,
+                dimensionValues: conversationDimensionValues(columns, rows),
+                measureColumns,
+                rowCount: typeof rowCountRaw === 'number' ? rowCountRaw : rows.length || undefined,
+            }
+            : undefined,
+        contract: requestedShape,
+    };
+}
+function conversationResultColumns(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((column) => typeof column === 'string'
+        ? column
+        : agentRunString(column?.name) ?? '')
+        .filter(Boolean)
+        .slice(0, 24);
+}
+function conversationMeasureColumns(columns, requestedShape, rows) {
+    const requested = conversationStringArray(requestedShape?.measures) ?? [];
+    const numericColumns = columns.filter((column) => rows.some((row) => typeof row[column] === 'number' && Number.isFinite(row[column])));
+    const metricNamedColumns = columns.filter((column) => /\b(revenue|sales|amount|total|count|average|avg|sum|spend|cost|margin|profit|value|points?|score|quantity|units?|rate|volume)\b/i.test(column.replace(/_/g, ' ')));
+    const unique = Array.from(new Set([...requested, ...numericColumns, ...metricNamedColumns]
+        .map((value) => value.trim())
+        .filter(Boolean)));
+    return unique.length > 0 ? unique.slice(0, 24) : undefined;
+}
+/** Distinct string values per low-cardinality column — the deictic-resolution fuel. */
+function conversationDimensionValues(columns, rows) {
+    if (columns.length === 0 || rows.length === 0)
+        return undefined;
+    const out = {};
+    for (const column of columns.slice(0, 8)) {
+        const values = Array.from(new Set(rows.map((row) => row[column]).filter((value) => typeof value === 'string' && value.trim().length > 0))).slice(0, 24);
+        if (values.length > 0 && values.length <= 24)
+            out[column] = values;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+function conversationStringArray(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const values = value.filter((item) => typeof item === 'string' && item.trim().length > 0);
+    return values.length > 0 ? values : undefined;
+}
+function compactConversationRecord(record) {
+    const entries = Object.entries(record).filter(([, value]) => value !== undefined && value !== null);
+    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
 export async function startLocalServer(opts) {
     const { rootDir, executor, connection: rawConnection, preferredPort, projectRoot = process.cwd() } = opts;
     const bindHost = opts.host ?? process.env.DQL_HOST ?? '127.0.0.1';
@@ -378,7 +559,10 @@ export async function startLocalServer(opts) {
         let governedAnswer;
         let providerError;
         const isRepair = (repair?.attempt ?? 0) > 0 && Boolean(repair?.repairHint);
-        const reasoningEffort = resolveRunReasoningEffort(projectRoot, resolvedProvider, route, isRepair);
+        const reasoningEffort = request.reasoningEffort
+            ? resolveRequestedRunReasoningEffort(projectRoot, resolvedProvider, request.reasoningEffort, isRepair)
+            : resolveRunReasoningEffort(projectRoot, resolvedProvider, route, isRepair);
+        const analysisDepth = request.analysisDepth ?? (route === 'research' ? 'deep' : undefined);
         const contextEnvelope = {
             mode: 'agent_run',
             selectedObject: request.selectedObject,
@@ -386,24 +570,37 @@ export async function startLocalServer(opts) {
             instruction: [
                 'Route through the governed DQL answer loop.',
                 'Prefer certified DQL blocks when they exactly cover the question.',
-                'Generated SQL remains review-required and must use the bounded preview executor.',
+                'Generated DQL artifacts remain review-required; SQL is only the bounded preview/compiled evidence.',
                 'If the question needs investigation, return the clearest answer and next review action without certifying generated work.',
                 ...(isRepair ? [`This is a repair attempt — fix the previous failure: ${repair?.repairHint}`] : []),
             ].join(' '),
         };
         const controller = new AbortController();
+        // Best-effort active warehouse dialect so Lane-2 semantic compiles emit
+        // dialect-correct SQL (e.g. DATE_TRUNC / identifier quoting). Absent when no
+        // connection is configured — the compiler then uses its default dialect.
+        let semanticDriver;
+        try {
+            semanticDriver = requireActiveConnection().driver;
+        }
+        catch {
+            semanticDriver = undefined;
+        }
         await runner.run({
             provider: resolvedProvider,
             messages: [
                 ...(request.history ?? []).map((message) => ({ role: message.role, content: message.text })),
                 { role: 'user', content: isRepair ? `${request.question}\n\nFix the previous attempt: ${repair?.repairHint}` : request.question },
             ],
+            conversationContext: request.conversationContext,
             upstream: {
                 cellId: `agent-run:${request.selectedObject?.kind ?? 'workspace'}:${request.selectedObject?.id ?? request.runId ?? 'auto'}`,
                 sql: JSON.stringify(contextEnvelope, null, 2),
             },
             reasoningEffort,
+            ...(analysisDepth ? { analysisDepth } : {}),
             projectRoot,
+            ...(semanticDriver ? { semanticDriver } : {}),
             executeCertifiedBlock: executeCertifiedBlockForAgent,
             executeGeneratedSql: executeGeneratedSqlForAgent,
             getSchemaContext: getSchemaContextForAgent,
@@ -420,6 +617,22 @@ export async function startLocalServer(opts) {
         }
         return governedAnswer;
     }
+    function resolvedRunRouteFromAnswer(governedAnswer) {
+        return routeForCascadeAnswerTier(governedAnswer.route?.tier);
+    }
+    function groundingGapRepairHint(governedAnswer) {
+        const details = governedAnswer.refusalDetails;
+        if (!details)
+            return governedAnswer.text;
+        const offending = details.offending;
+        const tokens = [
+            details.code ? `code=${details.code}` : undefined,
+            offending?.relation ? `relation=${offending.relation}` : undefined,
+            offending?.column ? `column=${offending.column}` : undefined,
+            details.message ? `message=${details.message}` : undefined,
+        ].filter((token) => Boolean(token));
+        return tokens.length > 0 ? tokens.join('; ') : governedAnswer.text;
+    }
     const answerRunExecutor = async ({ request, route, routeDecision, attempt, repairHint, emitAnswerDelta }) => {
         let governedAnswer;
         try {
@@ -447,14 +660,20 @@ export async function startLocalServer(opts) {
                 ],
             };
         }
+        const resolvedRoute = resolvedRunRouteFromAnswer(governedAnswer) ?? route;
         const isCertified = governedAnswer.certification === 'certified' || governedAnswer.kind === 'certified';
-        const needsClarification = governedAnswer.kind === 'no_answer';
+        const isGroundingGap = governedAnswer.kind === 'no_answer' && governedAnswer.refusalCode === 'grounding_gap';
+        const isProviderError = governedAnswer.kind === 'no_answer' && governedAnswer.refusalCode === 'provider_error';
+        const groundingRepairHint = isGroundingGap ? groundingGapRepairHint(governedAnswer) : undefined;
+        // A provider outage is a retryable infrastructure failure, not a question the
+        // user needs to clarify — surface it as blocked so the UI offers a retry.
+        const needsClarification = governedAnswer.kind === 'no_answer' && !isGroundingGap && !isProviderError;
         const sql = governedAnswer.proposedSql ?? governedAnswer.sql;
-        // Synthesis: for a genuinely generated (non-certified) answer, compose an
-        // adaptive, well-formatted reply over the executed rows — streamed — instead of
-        // the loop's raw draft. Certified answers keep their fast path (no extra call).
+        const runnableSql = governedAnswer.kind === 'no_answer' ? undefined : sql;
+        // Synthesis is a legacy polish pass. Certified/no-answer paths and lanes
+        // that already produced DQL-first final prose keep the fast path.
         let synthesizedAnswer;
-        if (!needsClarification && !isCertified) {
+        if (shouldSynthesizeAgentRunAnswer(governedAnswer)) {
             try {
                 const provider = await createBlockStudioAssistProvider(projectRoot);
                 if (provider) {
@@ -481,32 +700,55 @@ export async function startLocalServer(opts) {
                 synthesizedAnswer = undefined;
             }
         }
-        const status = needsClarification ? 'needs_clarification' : isCertified ? 'completed' : 'needs_review';
-        const trustState = needsClarification ? 'not_applicable' : isCertified ? 'certified' : 'review_required';
-        const stopReason = needsClarification ? 'needs_clarification' : isCertified ? 'certified_answer_found' : 'human_review_required';
+        const status = isProviderError ? 'blocked' : needsClarification ? 'needs_clarification' : isCertified ? 'completed' : 'needs_review';
+        const trustState = isProviderError ? 'blocked' : needsClarification ? 'not_applicable' : isCertified ? 'certified' : 'review_required';
+        const stopReason = isProviderError ? 'blocked' : needsClarification ? 'needs_clarification' : isCertified ? 'certified_answer_found' : 'human_review_required';
         const nextActions = needsClarification
             ? [{ id: 'clarify', label: 'Clarify question', route: 'generated_answer' }]
             : [
-                ...(sql ? [{ id: 'insert-sql', label: 'Insert SQL cell', route: 'sql_cell', artifactKind: 'sql_cell' }] : []),
+                { 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' },
-                { id: 'create-block', label: 'Create DQL draft', route: 'dql_block_draft', artifactKind: 'dql_block_draft' },
+                ...(runnableSql ? [{ id: 'insert-sql', label: 'Insert SQL preview', route: 'sql_cell', artifactKind: 'sql_cell' }] : []),
             ];
         return {
+            resolvedRoute,
+            answerTier: governedAnswer.route?.tier,
             summary: governedAnswer.route?.label ?? (isCertified ? 'Answered from certified DQL context.' : 'Answered with review-required generated analysis.'),
             answer: synthesizedAnswer ?? governedAnswer.answer ?? governedAnswer.text,
             status,
             trustState,
             stopReason,
-            artifacts: needsClarification
-                ? []
+            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' : 'Review-required answer', governedAnswer, governedAnswer.sourceCertifiedBlock ?? governedAnswer.block?.name, isCertified ? 'certified' : 'review_required')],
             evaluations: [
-                agentRunEvaluation('route-decision', 'Route decision', true, 'info', routeDecision?.reason ?? 'Routed request to governed answer.'),
+                agentRunEvaluation('route-decision', 'Route decision', true, 'info', routeDecision?.reason ?? 'Routed request to governed answer.', {
+                    plannedRoute: route,
+                    resolvedRoute,
+                    aiRoute: governedAnswer.route,
+                }),
                 agentRunEvaluation('trust-boundary', 'Trust boundary', isCertified, isCertified ? 'info' : 'warning', isCertified
                     ? 'The answer came from certified DQL context.'
                     : needsClarification
                         ? 'The answer loop needs more context before producing a governed answer.'
                         : 'The answer is generated or semantic-layer backed and remains review-required.', governedAnswer.route),
+                ...(isGroundingGap ? [
+                    {
+                        ...agentRunEvaluation('grounding-gap', 'Metadata grounding', false, 'warning', 'The answer loop found a metadata grounding gap that can be retried with wider context.', {
+                            refusalCode: governedAnswer.refusalCode,
+                            refusalDetails: governedAnswer.refusalDetails,
+                            validationWarnings: governedAnswer.validationWarnings,
+                            route: governedAnswer.route,
+                        }),
+                        suggestedRepair: groundingRepairHint,
+                        repairAction: { kind: 'retry', hint: groundingRepairHint },
+                    },
+                ] : []),
                 ...(governedAnswer.executionError ? [
                     agentRunEvaluation('execution-error', 'Execution error', false, 'warning', governedAnswer.executionError),
                 ] : []),
@@ -529,8 +771,10 @@ export async function startLocalServer(opts) {
             const provider = await createBlockStudioAssistProvider(projectRoot);
             if (provider) {
                 const system = buildConversationSystemPrompt(kind, isGeneralKnowledge, catalogContext, request.audience ?? 'analyst');
+                const conversationMemory = renderConversationMemoryForPrompt(request.conversationContext);
                 const messages = [
                     { role: 'system', content: system },
+                    ...(conversationMemory ? [{ role: 'system', content: conversationMemory }] : []),
                     ...(request.history ?? []).slice(-6).map((message) => ({ role: message.role, content: message.text })),
                     { role: 'user', content: request.question },
                 ];
@@ -545,7 +789,8 @@ export async function startLocalServer(opts) {
             text = undefined;
         }
         if (!text) {
-            text = buildConversationalFallback(kind, isGeneralKnowledge, request.question, suggestions);
+            text = buildConversationContextRecap(request.conversationContext)
+                ?? buildConversationalFallback(kind, isGeneralKnowledge, request.question, suggestions);
             emitAnswerDelta?.(text);
         }
         return {
@@ -564,7 +809,8 @@ export async function startLocalServer(opts) {
         conversation: conversationRunExecutor,
         certified_answer: answerRunExecutor,
         generated_answer: answerRunExecutor,
-        research: async ({ runId, request, routeDecision, emit }) => {
+        research: async (researchContext) => {
+            const { runId, request, routeDecision, emit } = researchContext;
             const metrics = loadSemanticMetrics(projectRoot);
             let blocks = collectPlanBlocks(projectRoot, { certifiedOnly: true });
             const usedCertifiedOnly = blocks.length > 0;
@@ -585,6 +831,13 @@ export async function startLocalServer(opts) {
                 // When the user explicitly picked research, investigate — don't collapse to one step.
                 forceInvestigate: request.requestedMode === 'research',
             });
+            // Direct governed answer ("the metric answers this directly"): don't wrap it in
+            // a review-required research dossier — run the query through the answer loop and
+            // return the executed result table + DQL artifact. A dossier is only for genuine
+            // multi-step investigation (plan.done === false) or explicit research mode.
+            if (plan.done && !plan.followUp && request.requestedMode !== 'research') {
+                return answerRunExecutor(researchContext);
+            }
             const needsClarification = Boolean(plan.followUp);
             const notebookPath = agentRunNotebookPath(request, runId);
             const researchIntent = agentRunResearchIntent(request);
@@ -650,9 +903,15 @@ export async function startLocalServer(opts) {
                     researchWorkspaceError = formatNotebookResearchStorageError(error);
                 }
             }
-            const researchResultData = coerceNarrateResultData(researchRun?.resultPreview);
-            // Executed cleanly against real data (rows present, no workspace/exec error) → grounded, not review-required.
-            const researchExecutedCleanly = Boolean(researchResultData) && !researchWorkspaceError && researchRun?.status !== 'error';
+            const researchResultPreview = researchRun?.resultPreview;
+            const researchResultData = coerceNarrateResultData(researchResultPreview);
+            const researchResultRecord = agentRunRecord(researchResultPreview);
+            // A query that ran and matched 0 rows STILL executed — treat it as a clean,
+            // grounded execution (not "no result"), so an empty answer is surfaced as
+            // "0 rows matched" rather than silently downgraded to review-required.
+            const researchDidExecute = Boolean(researchResultData) || Boolean(researchResultRecord && Array.isArray(researchResultRecord.rows));
+            const researchZeroRows = !researchResultData && researchDidExecute;
+            const researchExecutedCleanly = researchDidExecute && !researchWorkspaceError && researchRun?.status !== 'error';
             const narration = !needsClarification && researchResultData
                 ? await narrateForAgentRun({
                     question: request.question,
@@ -665,18 +924,22 @@ export async function startLocalServer(opts) {
             const summary = needsClarification
                 ? 'Needs clarification before running deeper research.'
                 : narration?.summary
-                    ?? (researchRun?.status === 'ready'
-                        ? 'Saved a grounded research dossier with context evidence and next review actions.'
-                        : researchRun?.status === 'error'
-                            ? 'Saved a research dossier, but the preview needs review before promotion.'
-                            : researchWorkspaceError
-                                ? 'Prepared a grounded research plan; durable research storage is unavailable in this runtime.'
-                                : plan.done
-                                    ? 'Prepared a direct grounded-answer plan.'
-                                    : 'Prepared a grounded research plan over real DQL assets.');
+                    ?? (researchZeroRows
+                        ? 'The query executed cleanly against real data and matched 0 rows.'
+                        : researchRun?.status === 'ready'
+                            ? 'Saved a grounded research dossier with context evidence and next review actions.'
+                            : researchRun?.status === 'error'
+                                ? 'Saved a research dossier, but the preview needs review before promotion.'
+                                : researchWorkspaceError
+                                    ? 'Prepared a grounded research plan; durable research storage is unavailable in this runtime.'
+                                    : plan.done
+                                        ? 'Prepared a direct grounded-answer plan.'
+                                        : 'Prepared a grounded research plan over real DQL assets.');
             return {
                 summary,
-                answer: plan.followUp?.question ?? narration?.summary ?? researchRun?.summary,
+                answer: plan.followUp?.question ?? narration?.summary
+                    ?? (researchZeroRows ? 'The query executed cleanly and matched 0 rows.' : undefined)
+                    ?? researchRun?.summary,
                 status: needsClarification ? 'needs_clarification' : 'needs_review',
                 trustState: needsClarification ? 'not_applicable' : (researchExecutedCleanly ? 'grounded' : 'review_required'),
                 stopReason: needsClarification ? 'needs_clarification' : 'human_review_required',
@@ -706,15 +969,17 @@ export async function startLocalServer(opts) {
                             ? 'Research workspace storage is unavailable; the plan remains available in this agent run.'
                             : 'No durable research record was created because the run needs clarification first.', { notebookPath, researchRunId: researchRun?.id, error: researchWorkspaceError }),
                     agentRunEvaluation('result-executed', 'Executed against data', researchExecutedCleanly, researchExecutedCleanly ? 'info' : 'warning', researchExecutedCleanly
-                        ? 'The query executed cleanly against real data and returned rows.'
-                        : 'No executed result rows were available; the output stays exploratory pending review.', { rowCount: researchResultData && typeof researchResultData === 'object' && Array.isArray(researchResultData.rows) ? researchResultData.rows.length : 0 }),
+                        ? (researchZeroRows
+                            ? 'The query executed cleanly against real data and matched 0 rows.'
+                            : 'The query executed cleanly against real data and returned rows.')
+                        : 'No executed result was available; the output stays exploratory pending review.', { rowCount: Array.isArray(researchResultRecord?.rows) ? researchResultRecord.rows.length : 0 }),
                 ],
                 nextActions: needsClarification
                     ? [{ id: 'answer-follow-up', label: 'Answer follow-up', route: 'research' }]
                     : [
                         ...(researchRun?.id ? [{ id: 'open-research', label: 'Open research dossier', artifactKind: 'research_run' }] : []),
-                        ...(researchRun?.generatedSql || researchRun?.reviewedSql ? [{ id: 'insert-sql', label: 'Insert SQL cell', route: 'sql_cell', artifactKind: 'sql_cell' }] : []),
-                        { id: 'create-block', label: 'Create DQL draft', route: 'dql_block_draft', artifactKind: 'dql_block_draft' },
+                        { id: 'create-block', label: 'Review DQL draft', route: 'dql_block_draft', artifactKind: 'dql_block_draft' },
+                        ...(researchRun?.generatedSql || researchRun?.reviewedSql ? [{ id: 'insert-sql', label: 'Insert SQL preview', route: 'sql_cell', artifactKind: 'sql_cell' }] : []),
                     ],
             };
         },
@@ -729,12 +994,67 @@ export async function startLocalServer(opts) {
                     agentRunEvaluation('review-boundary', 'Review boundary', true, 'warning', 'Generated SQL must be reviewed before it becomes certified analytics.'),
                 ],
                 nextActions: [
-                    { id: 'insert-sql', label: 'Insert SQL cell', artifactKind: 'sql_cell' },
-                    { id: 'create-block', label: 'Promote to DQL draft', route: 'dql_block_draft', artifactKind: 'dql_block_draft' },
+                    { id: 'insert-sql', label: 'Insert SQL preview', artifactKind: 'sql_cell' },
+                    { id: 'create-block', label: 'Review as DQL draft', route: 'dql_block_draft', artifactKind: 'dql_block_draft' },
                 ],
             };
         },
         dql_block_draft: async ({ request, routeDecision, attempt, repairHint }) => {
+            const contextRecord = agentRunRecord(request.conversationContext);
+            const carriedDqlArtifact = normalizeDqlArtifactReference(contextRecord?.dqlArtifact)
+                ?? normalizeDqlArtifactReference(request.workspaceContext?.dqlArtifact);
+            if (carriedDqlArtifact && (attempt ?? 0) === 0) {
+                const sourceQuestion = agentRunString(contextRecord?.sourceQuestion) ?? request.question;
+                const session = await createDqlArtifactGenerationSessionForProject(projectRoot, {
+                    question: sourceQuestion,
+                    dqlArtifact: carriedDqlArtifact,
+                    inputMode: 'upload',
+                    inputPath: carriedDqlArtifact.sourcePath,
+                    domain: agentRunWorkspaceValue(request, 'domain'),
+                    owner: agentRunWorkspaceValue(request, 'owner'),
+                    tags: ['agent-run', 'review-required'],
+                    contextPackId: agentRunString(contextRecord?.contextPackId),
+                    routeIntent: agentRunString(contextRecord?.route),
+                    sourceBlock: carriedDqlArtifact.sourcePath,
+                }, semanticLayer);
+                const candidate = session.candidates[0];
+                const validation = candidate?.validation && typeof candidate.validation === 'object'
+                    ? candidate.validation
+                    : undefined;
+                const ready = validation?.valid !== false;
+                const payload = {
+                    target: 'block',
+                    name: candidate?.name ?? carriedDqlArtifact.name ?? 'DQL block draft',
+                    path: candidate?.draftSave?.path ?? candidate?.savedPath,
+                    importId: session.id,
+                    candidateId: candidate?.id,
+                    source: candidate?.dqlSource,
+                    dqlSource: candidate?.dqlSource,
+                    dqlArtifact: carriedDqlArtifact,
+                    certifierVerdict: {
+                        ready,
+                        diagnostics: validation?.diagnostics ?? [],
+                    },
+                    generation: session.generation,
+                };
+                return {
+                    summary: ready
+                        ? 'Saved the generated DQL artifact as a review-required block draft.'
+                        : 'Saved the generated DQL artifact as a block draft with review blockers or warnings.',
+                    artifacts: [agentRunArtifact('dql_block_draft', payload.name, payload, payload.path)],
+                    evaluations: [
+                        agentRunEvaluation('route-decision', 'Route decision', true, 'info', routeDecision?.reason ?? 'Routed request to DQL block draft generation.'),
+                        agentRunEvaluation('dql-artifact-reuse', 'Used generated DQL artifact', true, 'info', 'Persisted the existing DQL artifact without regenerating it from SQL.', { importId: session.id, path: payload.path }),
+                        agentRunEvaluation('certification-boundary', 'Certification boundary', ready, 'warning', ready
+                            ? 'The draft has no automatic validation blockers, but certification still requires human review.'
+                            : 'The draft has validation blockers that must be resolved before certification review.', payload),
+                    ],
+                    nextActions: [
+                        { id: 'open-review', label: 'Open review checklist', artifactKind: 'dql_block_draft' },
+                        { id: 'build-app', label: 'Build app from block', route: 'app_build', artifactKind: 'app_draft' },
+                    ],
+                };
+            }
             const result = await buildAgentPromptArtifact(request, 'block', { attempt, repairHint });
             const ready = result.target === 'block' ? result.certifierVerdict.ready : false;
             return {
@@ -902,9 +1222,27 @@ export async function startLocalServer(opts) {
         getCatalogContext: () => buildAgentRunCatalogContext(),
     });
     const agentRunStore = new FileAgentRunStore({ path: defaultAgentRunStorePath(projectRoot) });
+    // Server-side conversation threads: persisted multi-turn state (survives refresh).
+    // Lazy so a failed native-sqlite load never blocks the runtime; conversation
+    // persistence degrades to the per-request context instead.
+    let conversationStoreInstance;
+    const getConversationStore = () => {
+        if (conversationStoreInstance !== undefined)
+            return conversationStoreInstance;
+        try {
+            conversationStoreInstance = new ConversationStore(defaultConversationPath(projectRoot));
+        }
+        catch {
+            conversationStoreInstance = null;
+        }
+        return conversationStoreInstance;
+    };
     const agentRunEngine = new AgentRunEngine({
         store: agentRunStore,
-        executors: agentRunExecutors,
+        executors: {
+            ...agentRunExecutors,
+            ...(opts.agentRunExecutors ?? {}),
+        },
         gates: defaultAgentRunGates,
         planner: agentRunPlanner,
         router: agentRunRouter,
@@ -1063,25 +1401,42 @@ export async function startLocalServer(opts) {
         };
     };
     const getSchemaContextForAgent = async (question) => {
+        const scanRuntimeSchema = async () => {
+            if (!connection)
+                return { ranked: [], snapshot: [] };
+            const result = await executor.executeQuery(`SELECT table_schema, table_name, column_name, data_type
+         FROM information_schema.columns
+         WHERE table_schema NOT IN ('information_schema', 'pg_catalog')
+         ORDER BY table_schema, table_name, ordinal_position
+         LIMIT 2000`, [], runtimeVariables({}), connection);
+            return {
+                ranked: buildAgentSchemaContext(question, result.rows),
+                snapshot: buildAgentSchemaContext(question, result.rows, { includeUnscored: true, limit: 500 }),
+            };
+        };
         const catalogContext = await buildAgentSchemaContextFromCatalog(projectRoot, question).catch(() => []);
         if (catalogContext.length > 0) {
             if (!connection)
                 return catalogContext;
-            const enriched = await enrichAgentSchemaContextWithValueMatches(question, catalogContext, executor, connection);
-            recordAgentRuntimeSchemaSnapshot(projectRoot, enriched, 'catalog enriched runtime schema');
+            const runtimeScan = shouldAugmentAgentRuntimeSchema(question)
+                ? await scanRuntimeSchema().catch(() => undefined)
+                : undefined;
+            const runtimeContext = runtimeScan?.ranked ?? [];
+            const merged = mergeAgentSchemaContexts(catalogContext, runtimeContext);
+            const enriched = await enrichAgentSchemaContextWithValueMatches(question, merged, executor, connection);
+            recordAgentRuntimeSchemaSnapshot(projectRoot, !runtimeScan?.snapshot.length
+                ? enriched
+                : mergeAgentSchemaSampleValues(runtimeScan.snapshot, enriched), runtimeContext.length > 0
+                ? 'full information_schema runtime scan for composite Ask AI question'
+                : 'catalog enriched runtime schema');
             return enriched;
         }
         if (!connection)
             return [];
         try {
-            const result = await executor.executeQuery(`SELECT table_schema, table_name, column_name, data_type
-         FROM information_schema.columns
-         WHERE table_schema NOT IN ('information_schema', 'pg_catalog')
-         ORDER BY table_schema, table_name, ordinal_position
-         LIMIT 2000`, [], runtimeVariables({}), connection);
-            const schemaContext = buildAgentSchemaContext(question, result.rows);
-            const enriched = await enrichAgentSchemaContextWithValueMatches(question, schemaContext, executor, connection);
-            recordAgentRuntimeSchemaSnapshot(projectRoot, enriched, 'information_schema runtime scan');
+            const schemaContext = await scanRuntimeSchema();
+            const enriched = await enrichAgentSchemaContextWithValueMatches(question, schemaContext.ranked, executor, connection);
+            recordAgentRuntimeSchemaSnapshot(projectRoot, schemaContext.snapshot, 'full information_schema runtime scan');
             return enriched;
         }
         catch {
@@ -1147,6 +1502,7 @@ export async function startLocalServer(opts) {
                 sql: JSON.stringify(contextEnvelope, null, 2),
             },
             reasoningEffort,
+            analysisDepth: 'deep',
             projectRoot,
             executeCertifiedBlock: executeCertifiedBlockForAgent,
             executeGeneratedSql: executeGeneratedSqlForAgent,
@@ -1223,6 +1579,21 @@ export async function startLocalServer(opts) {
             intents: 0,
             notebooks: 0,
         },
+        reviewMetrics: {
+            totalReviewCount: 0,
+            openReviewCount: 0,
+            terminalReviewCount: 0,
+            draftCreatedCount: 0,
+            certifiedCount: 0,
+            completedCount: 0,
+            rejectedCount: 0,
+            draftCreationRate: null,
+            certifyConversionRate: null,
+            medianOpenReviewAgeMs: null,
+            medianTimeToDraftMs: null,
+            medianTimeToCertificationMs: null,
+            medianTimeToTerminalMs: null,
+        },
         limit: input.limit,
         offset: input.offset ?? 0,
     });
@@ -1265,6 +1636,7 @@ export async function startLocalServer(opts) {
         const context = input.context === undefined ? run.context : input.context;
         let generatedSql = notebookResearchString(input.generatedSql) ?? run.generatedSql;
         let reviewedSql = notebookResearchString(input.reviewedSql) ?? run.reviewedSql;
+        let dqlArtifact = normalizeDqlArtifactReference(input.dqlArtifact) ?? run.dqlArtifact;
         const startedAt = new Date().toISOString();
         storage.updateRun(run.id, {
             domain,
@@ -1275,6 +1647,7 @@ export async function startLocalServer(opts) {
             context,
             generatedSql,
             reviewedSql,
+            dqlArtifact,
             status: 'running',
             reviewStatus: 'needs_review',
             error: '',
@@ -1291,8 +1664,8 @@ export async function startLocalServer(opts) {
                     intent,
                     researchPattern: notebookResearchIntentPattern(intent),
                 },
-                strictness: 'balanced',
-                limit: 100,
+                strictness: 'exploratory',
+                limit: 160,
             }).catch((error) => {
                 const message = error instanceof Error ? error.message : String(error);
                 return {
@@ -1334,6 +1707,7 @@ export async function startLocalServer(opts) {
                                 }, null, 2),
                             },
                             reasoningEffort: resolveRunReasoningEffort(projectRoot, resolvedProvider, 'research', false),
+                            analysisDepth: 'deep',
                             projectRoot,
                             executeCertifiedBlock: executeCertifiedBlockForAgent,
                             executeGeneratedSql: executeGeneratedSqlForAgent,
@@ -1353,8 +1727,9 @@ export async function startLocalServer(opts) {
                         generationWarnings.push(`AI SQL generation did not return a governed answer. Metadata context was saved for review.${providerError ? ` ${providerError}` : ''}`);
                     }
                     else {
+                        dqlArtifact = normalizeDqlArtifactReference(governedAnswer.dqlArtifact) ?? dqlArtifact;
                         generatedSql = notebookResearchString(governedAnswer.proposedSql) ?? notebookResearchString(governedAnswer.sql);
-                        if (!generatedSql) {
+                        if (!generatedSql && !dqlArtifact) {
                             generationWarnings.push('AI returned a governed answer without SQL. Metadata context was saved; add reviewed SQL before DQL promotion.');
                         }
                     }
@@ -1416,7 +1791,7 @@ export async function startLocalServer(opts) {
             const evidence = {
                 trustStatus: {
                     label: governedAnswer?.trustLabel
-                        ?? (reviewedSql ? 'Reviewed notebook SQL' : generatedSql ? 'AI-generated research SQL' : 'Metadata-grounded research plan'),
+                        ?? (reviewedSql ? 'Reviewed notebook SQL' : generatedSql ? 'AI-generated research SQL' : dqlArtifact ? 'AI-generated DQL artifact' : 'Metadata-grounded research plan'),
                     reviewRequired: true,
                 },
                 contextPackId: contextPack.id,
@@ -1455,9 +1830,11 @@ export async function startLocalServer(opts) {
                 ?? notebookResearchSummary(question, resultPreview, previewError);
             const recommendation = previewError
                 ? 'Review the SQL, selected metadata, and connection context before rerunning.'
-                : sqlForPreview
-                    ? 'Review the SQL, parameter choices, grain, and evidence before promoting this research into a DQL draft block.'
-                    : 'Review the selected metadata context, then paste reviewed SQL or configure an AI provider before DQL draft promotion.';
+                : dqlArtifact && !reviewedSql
+                    ? 'Review the DQL artifact, parameter choices, grain, and evidence before promoting this research into a DQL draft block.'
+                    : sqlForPreview
+                        ? 'Review the SQL, parameter choices, grain, and evidence before promoting this research into a DQL draft block.'
+                        : 'Review the selected metadata context, then paste reviewed SQL or configure an AI provider before DQL draft promotion.';
             const researchPlan = buildNotebookResearchPlan({
                 run,
                 evidence,
@@ -1465,6 +1842,7 @@ export async function startLocalServer(opts) {
                 previewError,
                 generatedSql,
                 reviewedSql,
+                dqlArtifact,
                 routeDecision,
             });
             return storage.updateRun(run.id, {
@@ -1482,6 +1860,7 @@ export async function startLocalServer(opts) {
                 researchPlan,
                 generatedSql,
                 reviewedSql,
+                dqlArtifact,
                 display: display && display.ok ? display.display : undefined,
                 contextPackId: contextPack.id,
                 routeDecision,
@@ -1508,10 +1887,48 @@ export async function startLocalServer(opts) {
         }
     };
     const promoteNotebookResearchToDql = async (storage, run, input = {}) => {
-        const sql = notebookResearchString(run.reviewedSql) ?? notebookResearchString(run.generatedSql);
-        if (!sql)
-            throw new Error('Notebook research needs generated or reviewed SQL before DQL draft promotion.');
+        const reviewedSql = notebookResearchString(run.reviewedSql);
+        const dqlArtifact = normalizeDqlArtifactReference(run.dqlArtifact);
+        const sql = reviewedSql ?? notebookResearchString(run.generatedSql);
         const sourcePath = `${run.notebookPath}${run.sourceCellId ? `#${run.sourceCellId}` : ''}`;
+        if (!reviewedSql && dqlArtifact) {
+            const session = await createDqlArtifactGenerationSessionForProject(projectRoot, {
+                question: run.question,
+                dqlArtifact,
+                inputMode: 'upload',
+                inputPath: dqlArtifact.sourcePath ?? sourcePath,
+                domain: notebookResearchString(input.domain) ?? run.domain,
+                owner: notebookResearchString(input.owner) ?? run.owner,
+                tags: ['notebook-research', 'review-required', ...(Array.isArray(input.tags) ? input.tags : [])],
+                generatedSql: notebookResearchString(run.generatedSql),
+                contextPackId: run.contextPackId,
+                routeIntent: run.intent,
+                sourceBlock: dqlArtifact.sourcePath,
+            }, semanticLayer);
+            const draftPath = session.candidates.find((candidate) => candidate.draftSave?.path)?.draftSave?.path
+                ?? session.candidates.find((candidate) => candidate.savedPath)?.savedPath;
+            const promotion = buildNotebookDqlPromotionSummary(session, draftPath);
+            const updated = storage.markPromoted(run.id, {
+                draftBlockPath: draftPath,
+                dqlImportId: session.id,
+                dqlCandidateIds: session.candidates.map((candidate) => candidate.id),
+                dqlPromotion: promotion,
+            }) ?? run;
+            const planned = storage.updateRun(updated.id, {
+                researchPlan: buildNotebookResearchPlan({
+                    run: updated,
+                    evidence: updated.evidence,
+                    resultPreview: updated.resultPreview,
+                    generatedSql: updated.generatedSql,
+                    reviewedSql: updated.reviewedSql,
+                    dqlArtifact: updated.dqlArtifact,
+                    routeDecision: updated.routeDecision,
+                }),
+            }) ?? updated;
+            return { run: planned, session };
+        }
+        if (!sql)
+            throw new Error('Notebook research needs reviewed SQL, generated SQL, or a DQL artifact before DQL draft promotion.');
         const session = await createDqlGenerationSessionForProject(projectRoot, {
             inputMode: 'upload',
             sources: [{ path: sourcePath.endsWith('.sql') ? sourcePath : `${sourcePath}.sql`, content: sql }],
@@ -1537,6 +1954,7 @@ export async function startLocalServer(opts) {
                 resultPreview: updated.resultPreview,
                 generatedSql: updated.generatedSql,
                 reviewedSql: updated.reviewedSql,
+                dqlArtifact: updated.dqlArtifact,
                 routeDecision: updated.routeDecision,
             }),
         }) ?? updated;
@@ -2061,10 +2479,14 @@ export async function startLocalServer(opts) {
                     res.end(serializeJSON({ error: parsed.error ?? 'Invalid agent run request.' }));
                     return;
                 }
-                // The UI does not send retrieval signals; probe the local catalog so the
-                // router can short-circuit obvious governed matches without an LLM call.
-                if (!parsed.request.signals && !parsed.request.requestedMode) {
-                    parsed.request.signals = computeAgentRunSignals(projectRoot, parsed.request.question);
+                // The answer-loop cascade now proves certified/semantic/generated tiers
+                // after retrieval and execution. Avoid pre-routing ordinary Ask runs from
+                // token-overlap signals; explicit callers may still provide signals.
+                // Thread-scoped runs: the persisted thread supplies prior turns (server
+                // state wins; the client-built context stays the no-threadId fallback).
+                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);
                 }
                 const wantsStream = url.searchParams.get('stream') === '1' || url.searchParams.get('stream') === 'true';
                 if (wantsStream) {
@@ -2079,11 +2501,13 @@ export async function startLocalServer(opts) {
                     }, (delta) => {
                         writeAgentRunSse(res, 'agent-run-answer-delta', { runId: parsed.request.runId, delta });
                     });
+                    recordConversationTurn(conversationStore, parsed.request.threadId, run);
                     writeAgentRunSse(res, 'agent-run-complete', run);
                     res.end();
                     return;
                 }
                 const run = await agentRunEngine.run(parsed.request);
+                recordConversationTurn(conversationStore, parsed.request.threadId, run);
                 res.writeHead(201, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({ run }));
             }
@@ -2115,6 +2539,7 @@ export async function startLocalServer(opts) {
                 const notebookPath = (record && agentRunString(record.notebookPath))
                     ?? `notebooks/certification-requests/${Date.now()}.dqlnb`;
                 const generatedSql = record ? agentRunString(record.generatedSql) : undefined;
+                const dqlArtifact = record ? normalizeDqlArtifactReference(record.dqlArtifact) : undefined;
                 try {
                     const storage = openNotebookResearchStorage();
                     try {
@@ -2126,9 +2551,11 @@ export async function startLocalServer(opts) {
                             domain: record ? agentRunString(record.domain) : undefined,
                             owner: record ? agentRunString(record.owner) : undefined,
                             generatedSql,
+                            dqlArtifact,
                             context: {
                                 surface: 'stakeholder_request_certification',
                                 requestedContext: agentRunRecord(record?.context) ?? null,
+                                dqlArtifact: dqlArtifact ?? null,
                             },
                         });
                         res.writeHead(201, { 'Content-Type': 'application/json; charset=utf-8' });
@@ -2166,6 +2593,23 @@ export async function startLocalServer(opts) {
         // DRAFT proposals (each with its stored Certifier verdict) so the notebook
         // "Get Started" surface can route them into human review. dryRun preview —
         // nothing is written or certified by this call.
+        if (req.method === 'GET' && path === '/api/agent-runs/tier-distribution') {
+            try {
+                const store = getConversationStore();
+                const limitParam = Number(url.searchParams.get('limit'));
+                const limit = Number.isFinite(limitParam) && limitParam > 0 ? limitParam : undefined;
+                const distribution = store
+                    ? store.tierDistribution({ ...(limit ? { limit } : {}) })
+                    : { total: 0, byRouteTier: {}, byTerminalLane: {} };
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(JSON.stringify(distribution));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
         if ((req.method === 'GET' || req.method === 'POST') && path === '/api/propose') {
             try {
                 let owner;
@@ -2196,6 +2640,69 @@ export async function startLocalServer(opts) {
             }
             return;
         }
+        // Composting preview: mine certified block clusters for semantic metric
+        // candidates. Read-only; returns draft YAML + PR body text for review.
+        if ((req.method === 'GET' || req.method === 'POST') && path === '/api/propose/composting') {
+            try {
+                let owner;
+                let limit;
+                let minSupport;
+                if (req.method === 'POST') {
+                    const body = await readJSON(req).catch(() => ({}));
+                    if (typeof body?.owner === 'string')
+                        owner = body.owner;
+                    if (typeof body?.limit === 'number' && Number.isFinite(body.limit) && body.limit > 0)
+                        limit = body.limit;
+                    if (typeof body?.minSupport === 'number' && Number.isFinite(body.minSupport) && body.minSupport > 1)
+                        minSupport = body.minSupport;
+                }
+                else {
+                    const ownerParam = url.searchParams.get('owner');
+                    if (ownerParam)
+                        owner = ownerParam;
+                    const limitParam = Number(url.searchParams.get('limit'));
+                    if (Number.isFinite(limitParam) && limitParam > 0)
+                        limit = limitParam;
+                    const minSupportParam = Number(url.searchParams.get('minSupport'));
+                    if (Number.isFinite(minSupportParam) && minSupportParam > 1)
+                        minSupport = minSupportParam;
+                }
+                const changeset = buildSemanticCompostingChangeset(projectRoot, { owner, limit, minSupport });
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(changeset));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        // Composting generation: writes only approved metric candidate ids under
+        // semantic-layer/metrics/_drafts plus a PR-body artifact. Nothing certified.
+        if (req.method === 'POST' && path === '/api/propose/composting/generate') {
+            try {
+                const body = (await readJSON(req).catch(() => ({})));
+                const ids = Array.isArray(body?.ids)
+                    ? body.ids.filter((id) => typeof id === 'string' && id.trim().length > 0)
+                    : [];
+                if (ids.length === 0) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Provide non-empty { ids } to generate semantic composting drafts.' }));
+                    return;
+                }
+                const owner = typeof body?.owner === 'string' ? body.owner : undefined;
+                const limit = typeof body?.limit === 'number' && Number.isFinite(body.limit) && body.limit > 0 ? body.limit : undefined;
+                const minSupport = typeof body?.minSupport === 'number' && Number.isFinite(body.minSupport) && body.minSupport > 1 ? body.minSupport : undefined;
+                const result = generateSemanticCompostingDrafts(projectRoot, ids, { owner, limit, minSupport });
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(result));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
         // Deterministic PLAN only (classify → plan). Writes NOTHING. Same data the
         // readiness endpoint embeds, exposed standalone for the approve gate.
         if (req.method === 'POST' && path === '/api/propose/plan') {
@@ -2724,6 +3231,117 @@ export async function startLocalServer(opts) {
             }
             return;
         }
+        // ── Conversation threads (server-side session persistence) ────────────
+        if (path === '/api/agent/threads' || path.startsWith('/api/agent/threads/')) {
+            const store = getConversationStore();
+            if (!store) {
+                res.writeHead(503, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: 'Conversation store is unavailable.' }));
+                return;
+            }
+            try {
+                if (req.method === 'GET' && path === '/api/agent/threads') {
+                    const limit = Number(url.searchParams.get('limit') ?? '50');
+                    const includeArchived = url.searchParams.get('archived') === '1';
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ threads: store.listThreads({ limit: Number.isFinite(limit) ? limit : 50, includeArchived }) }));
+                    return;
+                }
+                if (req.method === 'POST' && path === '/api/agent/threads') {
+                    const body = await readJSON(req).catch(() => null);
+                    const record = agentRunRecord(body) ?? {};
+                    const thread = store.createThread({
+                        surface: agentRunString(record.surface),
+                        title: agentRunString(record.title),
+                        notebookPath: agentRunString(record.notebookPath),
+                    });
+                    res.writeHead(201, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ thread }));
+                    return;
+                }
+                // Cross-thread turn search ("search conversations") — must precede :id.
+                if (req.method === 'GET' && path === '/api/agent/threads/search') {
+                    const query = url.searchParams.get('q') ?? '';
+                    const limit = Number(url.searchParams.get('limit') ?? '10');
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({
+                        turns: query.trim()
+                            ? store.searchTurns({ query, limit: Number.isFinite(limit) ? limit : 10 })
+                            : [],
+                    }));
+                    return;
+                }
+                const threadMatch = path.match(/^\/api\/agent\/threads\/([^/]+)(?:\/(archive|promote))?$/);
+                if (threadMatch) {
+                    const threadId = decodeURIComponent(threadMatch[1]);
+                    const action = threadMatch[2];
+                    const thread = store.getThread(threadId);
+                    if (!thread) {
+                        res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({ error: 'Unknown thread id.' }));
+                        return;
+                    }
+                    if (req.method === 'POST' && action === 'archive') {
+                        store.archiveThread(threadId);
+                        res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({ ok: true }));
+                        return;
+                    }
+                    // Explicit promotion — the ONLY path from conversation into durable
+                    // memory ("remember this"). Deliberate user act, tagged for audit.
+                    if (req.method === 'POST' && action === 'promote') {
+                        const body = await readJSON(req).catch(() => null);
+                        const record = agentRunRecord(body) ?? {};
+                        const turnId = agentRunString(record.turnId);
+                        const turn = turnId
+                            ? store.recentTurns(threadId, 200).find((candidate) => candidate.id === turnId)
+                            : undefined;
+                        if (!turn) {
+                            res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                            res.end(serializeJSON({ error: 'turnId is required and must belong to this thread.' }));
+                            return;
+                        }
+                        const scopeRaw = agentRunString(record.scope);
+                        const scope = scopeRaw === 'notebook' || scopeRaw === 'project' || scopeRaw === 'user' ? scopeRaw : 'project';
+                        const memory = new MemoryStore(defaultMemoryPath(projectRoot));
+                        try {
+                            const saved = memory.upsert({
+                                scope,
+                                title: agentRunString(record.title) ?? turn.question.slice(0, 120),
+                                content: `Q: ${turn.question}\nA: ${turn.answerSummary ?? turn.answerText ?? '(no answer summary)'}`,
+                                tags: ['conversation', threadId],
+                                source: 'conversation',
+                                confidence: 0.6,
+                                importance: 0.5,
+                                enabled: true,
+                            });
+                            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                            res.end(serializeJSON({ ok: true, memory: saved }));
+                        }
+                        finally {
+                            memory.close();
+                        }
+                        return;
+                    }
+                    if (req.method === 'GET' && !action) {
+                        const limit = Number(url.searchParams.get('limit') ?? '50');
+                        res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({
+                            thread,
+                            turns: store.recentTurns(threadId, Number.isFinite(limit) ? limit : 50),
+                        }));
+                        return;
+                    }
+                }
+                res.writeHead(405, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: 'Method not allowed' }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
         if (req.method === 'GET' && path === '/api/agent/memory') {
             const memory = new MemoryStore(defaultMemoryPath(projectRoot));
             try {
@@ -3247,6 +3865,7 @@ export async function startLocalServer(opts) {
                 const sourceCellId = notebookResearchString(body.sourceCellId) ?? notebookResearchSourceCellId(sourceCell);
                 const sourceCellName = notebookResearchString(body.sourceCellName) ?? notebookResearchSourceCellName(sourceCell);
                 const sourceCellFingerprint = notebookResearchString(body.sourceCellFingerprint) ?? notebookResearchSourceCellFingerprint(sourceCell);
+                const dqlArtifact = normalizeDqlArtifactReference(body.dqlArtifact);
                 if (!notebookPath || !question) {
                     res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({ error: 'notebookPath and question are required.' }));
@@ -3266,6 +3885,7 @@ export async function startLocalServer(opts) {
                     context: body.context,
                     generatedSql: notebookResearchString(body.generatedSql),
                     reviewedSql: notebookResearchString(body.reviewedSql),
+                    dqlArtifact,
                 });
                 const run = body.run === true
                     ? await runNotebookResearch(storage, created, {
@@ -3276,6 +3896,7 @@ export async function startLocalServer(opts) {
                         context: body.context,
                         generatedSql: notebookResearchString(body.generatedSql),
                         reviewedSql: notebookResearchString(body.reviewedSql),
+                        dqlArtifact,
                     })
                     : created;
                 res.writeHead(201, { 'Content-Type': 'application/json; charset=utf-8' });
@@ -3318,8 +3939,8 @@ export async function startLocalServer(opts) {
                         intent,
                         researchPattern: notebookResearchIntentPattern(intent),
                     },
-                    strictness: 'balanced',
-                    limit: 100,
+                    strictness: 'exploratory',
+                    limit: 160,
                 });
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON(notebookResearchContextPreview(contextPack)));
@@ -3543,6 +4164,7 @@ export async function startLocalServer(opts) {
                         routeDecision: body.routeDecision,
                         generatedSql: notebookResearchString(body.generatedSql),
                         reviewedSql: notebookResearchString(body.reviewedSql),
+                        dqlArtifact: normalizeDqlArtifactReference(body.dqlArtifact),
                         warnings: Array.isArray(body.warnings) ? body.warnings.filter((item) => typeof item === 'string') : undefined,
                         reviewStatus: notebookResearchReviewStatus(body.reviewStatus),
                         dqlPromotionAction: notebookResearchPromotionAction(body.dqlPromotionAction),
@@ -3555,6 +4177,7 @@ export async function startLocalServer(opts) {
                             previewError: updated.error,
                             generatedSql: updated.generatedSql,
                             reviewedSql: updated.reviewedSql,
+                            dqlArtifact: updated.dqlArtifact,
                             routeDecision: updated.routeDecision,
                         }),
                     }) ?? updated;
@@ -3574,6 +4197,7 @@ export async function startLocalServer(opts) {
                         context: body.context,
                         generatedSql: notebookResearchString(body.generatedSql),
                         reviewedSql: notebookResearchString(body.reviewedSql),
+                        dqlArtifact: normalizeDqlArtifactReference(body.dqlArtifact),
                     });
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({ run: withNotebookResearchChecklist(updated) }));
@@ -6729,16 +7353,27 @@ export function resolveDefaultLLMProvider(projectRoot) {
  * answer-loop runner — never the MCP `claudeCodeRunner`, which doesn't emit a governed
  * answer envelope. Everything else uses the Settings-resolved default runner.
  */
-function resolveGovernedAnswerRunner(projectRoot) {
+export function resolveGovernedAnswerRunner(projectRoot) {
     const active = getActiveProvider(projectRoot);
-    if (active === 'claude-code' || active === 'codex') {
+    if (isGovernedAnswerProviderId(active)) {
         return { provider: active, runner: createDqlAgentProviderRunner(active) };
     }
     const resolved = resolveDefaultLLMProvider(projectRoot);
     if (!resolved)
         return null;
-    const runner = getLLMRunner(resolved);
-    return runner ? { provider: resolved, runner } : null;
+    if (isGovernedAnswerProviderId(resolved)) {
+        return { provider: resolved, runner: createDqlAgentProviderRunner(resolved) };
+    }
+    return null;
+}
+function isGovernedAnswerProviderId(value) {
+    return value === 'anthropic'
+        || value === 'openai'
+        || value === 'gemini'
+        || value === 'ollama'
+        || value === 'custom-openai'
+        || value === 'claude-code'
+        || value === 'codex';
 }
 /** Map a runner provider id to the settings id whose reasoning ceiling applies. */
 function reasoningSettingsIdFor(provider) {
@@ -6783,6 +7418,11 @@ function resolveRunReasoningEffort(projectRoot, provider, route, isRepair) {
         desired = bumpReasoningEffort(desired);
     return ceiling ? clampReasoningEffort(desired, ceiling) : desired;
 }
+function resolveRequestedRunReasoningEffort(projectRoot, provider, requested, isRepair) {
+    const ceiling = getEffectiveProviderConfig(projectRoot, reasoningSettingsIdFor(provider)).reasoningEffort;
+    const desired = isRepair ? bumpReasoningEffort(requested) : requested;
+    return ceiling ? clampReasoningEffort(desired, ceiling) : desired;
+}
 function loadAppDashboard(projectRoot, appId, dashboardId) {
     for (const p of findAppDocuments(projectRoot)) {
         const { document: app } = loadAppDocument(p);
@@ -7107,6 +7747,11 @@ export function buildProposeReadiness(projectRoot, projectConfig = loadProjectCo
         if (proposal.certification.errors.length === 0)
             readyForReview += 1;
     }
+    const reviewableProposals = buildReviewableProposals(projectRoot, manifestPath, projectConfig, summary.proposals, options.owner);
+    const reviewAges = reviewableProposals
+        .map((proposal) => proposal.review.reviewAgeHours)
+        .filter((value) => typeof value === 'number' && Number.isFinite(value));
+    const estimatedReviewMinutes = reviewableProposals.reduce((sum, proposal) => sum + proposal.review.estimatedReviewMinutes, 0);
     return {
         ready: true,
         summary: {
@@ -7121,11 +7766,595 @@ export function buildProposeReadiness(projectRoot, projectConfig = loadProjectCo
             readyForReview,
             blockingTotal,
             warningTotal,
+            reviewTelemetry: {
+                existingDrafts: reviewableProposals.filter((proposal) => proposal.review.draftExists).length,
+                medianReviewAgeHours: median(reviewAges),
+                readyForReviewRate: ratio(readyForReview, summary.proposalsRanked),
+                estimatedReviewMinutes,
+            },
         },
         plan,
-        proposals: summary.proposals,
+        proposals: reviewableProposals,
+    };
+}
+function buildReviewableProposals(projectRoot, dbtManifestPath, projectConfig, proposals, owner) {
+    const manifest = safeBuildProjectManifest(projectRoot);
+    return proposals.map((proposal, index) => {
+        const preview = buildProposePreview(projectRoot, dbtManifestPath, proposal.slug, {
+            config: projectConfig.propose,
+            owner,
+        });
+        const draftPath = proposal.path ?? resolveProposeDraftPath(projectRoot, proposal.domain, proposal.slug);
+        const draftFile = join(projectRoot, draftPath);
+        const draftExists = existsSync(draftFile);
+        const stats = draftExists ? statSync(draftFile) : undefined;
+        const firstSeenAt = stats ? stableFsTime(stats.birthtimeMs, stats.ctimeMs) : undefined;
+        const lastUpdatedAt = stats ? stableFsTime(stats.mtimeMs, stats.ctimeMs) : undefined;
+        const reviewAgeHours = firstSeenAt ? hoursSince(firstSeenAt) : undefined;
+        const blockingCount = proposal.certification.errors.length;
+        const warningCount = proposal.certification.warnings.length;
+        const outputs = preview?.outputs ?? proposal.inference.declaredOutputs;
+        const status = blockingCount === 0
+            ? 'ready_for_review'
+            : draftExists
+                ? 'draft_exists'
+                : 'new';
+        return {
+            ...proposal,
+            review: {
+                queueRank: index + 1,
+                status,
+                priorityScore: proposal.ranking.score,
+                blockingCount,
+                warningCount,
+                estimatedReviewMinutes: estimateProposalReviewMinutes(blockingCount, warningCount, Boolean(preview?.sqlPreview)),
+                draftPath,
+                draftExists,
+                firstSeenAt,
+                lastUpdatedAt,
+                reviewAgeHours,
+                certifyCommand: `dql certify --from-draft ${quoteCliArg(draftPath)} --owner you@example.com`,
+                payload: {
+                    question: preview?.examples?.[0] ?? proposal.inference.examples[0]?.question ?? `Review ${proposal.slug}`,
+                    model: proposal.model,
+                    domain: proposal.domain,
+                    sqlPreview: preview?.sqlPreview,
+                    outputs,
+                    grain: preview?.grain ?? proposal.inference.grain,
+                    pattern: preview?.pattern ?? proposal.inference.pattern,
+                    evidence: proposal.evidence,
+                    resultSample: { status: 'not_run', rows: [] },
+                    nearestCertifiedBlock: findNearestCertifiedBlock(manifest, proposal, outputs),
+                },
+            },
+        };
+    });
+}
+function safeBuildProjectManifest(projectRoot) {
+    try {
+        return buildManifest({ projectRoot });
+    }
+    catch {
+        return { blocks: {} };
+    }
+}
+function resolveProposeDraftPath(projectRoot, domain, slug) {
+    const safeDomain = domain
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9/_-]+/g, '-')
+        .replace(/^[-/]+|[-/]+$/g, '');
+    return safeDomain && existsSync(join(projectRoot, 'domains', safeDomain))
+        ? `domains/${safeDomain}/blocks/_drafts/${slug}.dql`
+        : `blocks/_drafts/${slug}.dql`;
+}
+function findNearestCertifiedBlock(manifest, proposal, outputs) {
+    const outputSet = new Set(outputs.map((output) => output.toLowerCase()));
+    let best;
+    for (const block of Object.values(manifest.blocks ?? {})) {
+        if (String(block.status ?? '').toLowerCase() !== 'certified')
+            continue;
+        const blockOutputs = (block.declaredOutputs ?? []).map((output) => output.toLowerCase());
+        const sharedOutputs = blockOutputs.filter((output) => outputSet.has(output));
+        const sameDomain = block.domain === proposal.domain;
+        const overlapScore = sharedOutputs.length * 10 + (sameDomain ? 5 : 0);
+        if (overlapScore <= 0)
+            continue;
+        if (!best || overlapScore > best.overlapScore) {
+            best = {
+                name: block.name,
+                path: block.filePath,
+                domain: block.domain,
+                overlapScore,
+                sharedOutputs,
+            };
+        }
+    }
+    return best;
+}
+function estimateProposalReviewMinutes(blockingCount, warningCount, hasSqlPreview) {
+    const base = hasSqlPreview ? 12 : 18;
+    return base + blockingCount * 8 + warningCount * 4;
+}
+function stableFsTime(primaryMs, fallbackMs) {
+    const ms = Number.isFinite(primaryMs) && primaryMs > 0 ? primaryMs : fallbackMs;
+    return Number.isFinite(ms) && ms > 0 ? new Date(ms).toISOString() : undefined;
+}
+function hoursSince(iso) {
+    const ts = Date.parse(iso);
+    if (!Number.isFinite(ts))
+        return 0;
+    return Number(Math.max(0, (Date.now() - ts) / 3_600_000).toFixed(2));
+}
+function median(values) {
+    if (values.length === 0)
+        return null;
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    const value = sorted.length % 2 === 1
+        ? sorted[mid]
+        : (sorted[mid - 1] + sorted[mid]) / 2;
+    return Number(value.toFixed(2));
+}
+function ratio(numerator, denominator) {
+    if (denominator === 0)
+        return null;
+    return Number((numerator / denominator).toFixed(4));
+}
+function quoteCliArg(value) {
+    if (/^[A-Za-z0-9_./:-]+$/.test(value))
+        return value;
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+/**
+ * Mine certified block clusters for recurring metric definitions and render a
+ * reviewable semantic-layer changeset. This is read-only: callers must confirm
+ * candidate ids through generateSemanticCompostingDrafts before files are written.
+ */
+export function buildSemanticCompostingChangeset(projectRoot, options = {}) {
+    let manifest;
+    try {
+        manifest = buildManifest({ projectRoot });
+    }
+    catch (error) {
+        return {
+            ready: false,
+            reason: error instanceof Error ? error.message : String(error),
+            summary: {
+                certifiedBlocksScanned: 0,
+                eligibleMetricClusters: 0,
+                candidatesRanked: 0,
+                existingDrafts: 0,
+                donorBlocksUsed: 0,
+                minSupport: Math.max(2, Math.floor(options.minSupport ?? 2)),
+            },
+            candidates: [],
+            prBody: '',
+        };
+    }
+    const minSupport = Math.max(2, Math.floor(options.minSupport ?? 2));
+    const limit = Number.isFinite(options.limit) && Number(options.limit) > 0 ? Math.floor(Number(options.limit)) : 10;
+    const owner = options.owner?.trim() || resolveLocalOwner(projectRoot, { persist: false });
+    const existingMetricNames = new Set(Object.entries(manifest.metrics ?? {})
+        .filter(([, metric]) => !isSemanticDraftMetricPath(metric.filePath))
+        .map(([name]) => name.toLowerCase()));
+    const certifiedBlocks = Object.values(manifest.blocks ?? {})
+        .filter((block) => String(block.status ?? '').toLowerCase() === 'certified');
+    const groups = new Map();
+    for (const block of certifiedBlocks) {
+        const table = singleTableDependency(block);
+        if (!table)
+            continue;
+        const where = extractCompostingWhereClause(block.sql);
+        const normalizedFilter = where ? normalizeCompostingSql(where) : undefined;
+        const metrics = extractCompostingAggregateMetrics(block.sql);
+        if (metrics.length === 0)
+            continue;
+        const donor = {
+            name: block.name,
+            path: block.filePath,
+            domain: block.domain,
+            outputs: blockOutputNames(block),
+            filters: where ? splitCompostingFilters(where) : [],
+        };
+        for (const metric of metrics) {
+            const normalizedExpression = normalizeCompostingSql(metric.expression);
+            const domain = block.domain?.trim() || 'misc';
+            const key = [
+                domain.toLowerCase(),
+                table.toLowerCase(),
+                metric.type,
+                normalizedExpression,
+                normalizedFilter ?? '',
+            ].join('\0');
+            const existing = groups.get(key);
+            if (existing) {
+                existing.aliases.push(metric.alias ?? '');
+                existing.donors.set(block.filePath, donor);
+            }
+            else {
+                groups.set(key, {
+                    domain,
+                    table,
+                    type: metric.type,
+                    expression: metric.expression,
+                    normalizedExpression,
+                    filter: where,
+                    normalizedFilter,
+                    aliases: [metric.alias ?? ''],
+                    donors: new Map([[block.filePath, donor]]),
+                });
+            }
+        }
+    }
+    const usedNames = new Set(existingMetricNames);
+    const candidates = Array.from(groups.values())
+        .filter((group) => group.donors.size >= minSupport)
+        .sort((a, b) => b.donors.size - a.donors.size || a.normalizedExpression.localeCompare(b.normalizedExpression))
+        .map((group) => buildCompostingMetricCandidate(projectRoot, group, owner, usedNames))
+        .filter((candidate) => Boolean(candidate))
+        .slice(0, limit);
+    const donorBlocksUsed = new Set(candidates.flatMap((candidate) => candidate.donorBlocks.map((donor) => donor.path))).size;
+    return {
+        ready: true,
+        summary: {
+            certifiedBlocksScanned: certifiedBlocks.length,
+            eligibleMetricClusters: Array.from(groups.values()).filter((group) => group.donors.size >= minSupport).length,
+            candidatesRanked: candidates.length,
+            existingDrafts: candidates.filter((candidate) => candidate.draftExists).length,
+            donorBlocksUsed,
+            minSupport,
+        },
+        candidates,
+        prBody: renderCompostingPrBody(candidates),
+    };
+}
+export function generateSemanticCompostingDrafts(projectRoot, candidateIds, options = {}) {
+    const changeset = buildSemanticCompostingChangeset(projectRoot, options);
+    if (!changeset.ready) {
+        return {
+            ready: false,
+            reason: changeset.reason,
+            draftsWritten: 0,
+            draftsSkipped: 0,
+            candidates: [],
+            paths: [],
+            prBody: '',
+        };
+    }
+    const wanted = candidateIds && candidateIds.length > 0 ? new Set(candidateIds) : undefined;
+    const selected = wanted ? changeset.candidates.filter((candidate) => wanted.has(candidate.id)) : changeset.candidates;
+    const paths = [];
+    let draftsWritten = 0;
+    let draftsSkipped = 0;
+    for (const candidate of selected) {
+        const absolutePath = join(projectRoot, candidate.draftPath);
+        if (existsSync(absolutePath)) {
+            draftsSkipped += 1;
+        }
+        else {
+            mkdirSync(dirname(absolutePath), { recursive: true });
+            writeFileSync(absolutePath, candidate.yaml, 'utf-8');
+            draftsWritten += 1;
+        }
+        paths.push(candidate.draftPath);
+    }
+    let prBodyPath;
+    const prBody = renderCompostingPrBody(selected);
+    if (selected.length > 0) {
+        prBodyPath = 'semantic-layer/metrics/_drafts/PR_BODY.md';
+        const absolutePrBodyPath = join(projectRoot, prBodyPath);
+        mkdirSync(dirname(absolutePrBodyPath), { recursive: true });
+        writeFileSync(absolutePrBodyPath, prBody, 'utf-8');
+    }
+    return {
+        ready: true,
+        draftsWritten,
+        draftsSkipped,
+        candidates: selected,
+        paths,
+        prBody,
+        prBodyPath,
+    };
+}
+function buildCompostingMetricCandidate(projectRoot, group, owner, usedNames) {
+    const baseName = preferredCompostingMetricName(group);
+    const name = dedupeCompostingName(baseName, usedNames);
+    if (!name)
+        return undefined;
+    usedNames.add(name.toLowerCase());
+    const label = titleFromSlug(name);
+    const donors = Array.from(group.donors.values()).sort((a, b) => a.path.localeCompare(b.path));
+    const support = donors.length;
+    const domainSlug = slugForPath(group.domain);
+    const draftPath = `semantic-layer/metrics/_drafts/${domainSlug}/${name}.yaml`;
+    const recurringFilters = group.filter ? splitCompostingFilters(group.filter) : [];
+    const metric = {
+        name,
+        label,
+        description: `Draft metric composted from ${support} certified DQL blocks. Review the expression, filter, grain, and owner before certification.`,
+        domain: group.domain,
+        status: 'draft',
+        sql: group.expression,
+        type: group.type,
+        table: group.table,
+        filter: group.filter,
+        tags: ['composted', 'human-review'],
+        owner,
+        source: {
+            provider: 'dql',
+            objectType: 'composted_metric',
+            objectId: `composted:${name}`,
+            objectName: label,
+            importedAt: new Date().toISOString(),
+            extra: {
+                support,
+                donorBlocks: donors.map((donor) => donor.name),
+                donorPaths: donors.map((donor) => donor.path),
+                normalizedExpression: group.normalizedExpression,
+                normalizedFilter: group.normalizedFilter,
+            },
+        },
+    };
+    return {
+        id: `metric:${name}:${stableShortHash(`${group.domain}|${group.table}|${group.normalizedExpression}|${group.normalizedFilter ?? ''}`)}`,
+        kind: 'metric',
+        name,
+        label,
+        description: metric.description,
+        domain: group.domain,
+        table: group.table,
+        type: group.type,
+        sql: group.expression,
+        filter: group.filter,
+        status: 'draft',
+        support,
+        donorBlocks: donors,
+        draftPath,
+        draftExists: existsSync(join(projectRoot, draftPath)),
+        yaml: serializeMetricDefinitionToYaml(metric),
+        provenance: {
+            normalizedExpression: group.normalizedExpression,
+            normalizedFilter: group.normalizedFilter,
+            recurringFilters,
+        },
+        review: {
+            priorityScore: support * 10 + recurringFilters.length * 2,
+            rationale: `Recurring ${group.type} metric found in ${support} certified blocks${group.filter ? ' with the same filter' : ''}.`,
+        },
+    };
+}
+function singleTableDependency(block) {
+    const dependencies = Array.from(new Set((block.tableDependencies ?? []).filter((table) => table && !table.startsWith('ref:'))));
+    if (dependencies.length === 1)
+        return dependencies[0];
+    const rawRefs = Array.from(new Set((block.rawTableRefs ?? []).filter(Boolean)));
+    return rawRefs.length === 1 ? rawRefs[0] : undefined;
+}
+function blockOutputNames(block) {
+    if (Array.isArray(block.declaredOutputs) && block.declaredOutputs.length > 0)
+        return block.declaredOutputs;
+    if (Array.isArray(block.outputContract) && block.outputContract.length > 0)
+        return block.outputContract.map((output) => output.name);
+    if (Array.isArray(block.outputs) && block.outputs.length > 0)
+        return block.outputs.map((output) => output.name);
+    return [];
+}
+function isSemanticDraftMetricPath(filePath) {
+    return Boolean(filePath?.replaceAll('\\', '/').includes('semantic-layer/metrics/_drafts/'));
+}
+function extractCompostingAggregateMetrics(sql) {
+    const select = extractCompostingSelectClause(sql);
+    if (!select)
+        return [];
+    return splitCompostingTopLevel(select, ',').flatMap((item) => {
+        const parsed = parseCompostingSelectItem(item);
+        if (!parsed)
+            return [];
+        return [parsed];
+    });
+}
+function extractCompostingSelectClause(sql) {
+    const source = stripSqlTerminator(sql);
+    const selectMatch = /\bselect\b/i.exec(source);
+    if (!selectMatch)
+        return undefined;
+    const fromIndex = findTopLevelKeyword(source, 'from', selectMatch.index + selectMatch[0].length);
+    if (fromIndex < 0)
+        return undefined;
+    return source.slice(selectMatch.index + selectMatch[0].length, fromIndex).trim();
+}
+function parseCompostingSelectItem(item) {
+    const { expression, alias } = splitCompostingAlias(item.trim());
+    const normalizedExpression = expression.trim();
+    const distinctCount = normalizedExpression.match(/^count\s*\(\s*distinct\s+[\s\S]+\)$/i);
+    if (distinctCount) {
+        return { expression: normalizedExpression, alias, type: 'count_distinct' };
+    }
+    const count = normalizedExpression.match(/^count\s*\([\s\S]*\)$/i);
+    if (count)
+        return { expression: normalizedExpression, alias, type: 'count' };
+    const aggregate = normalizedExpression.match(/^(sum|avg|min|max)\s*\([\s\S]+\)$/i);
+    if (!aggregate)
+        return undefined;
+    return {
+        expression: normalizedExpression,
+        alias,
+        type: aggregate[1].toLowerCase(),
     };
 }
+function splitCompostingAlias(item) {
+    const asMatch = item.match(/^([\s\S]+?)\s+as\s+("[^"]+"|`[^`]+`|\[[^\]]+\]|[A-Za-z_][A-Za-z0-9_$]*)$/i);
+    if (asMatch)
+        return { expression: asMatch[1].trim(), alias: stripIdentifierQuotes(asMatch[2]) };
+    return { expression: item.trim() };
+}
+function extractCompostingWhereClause(sql) {
+    const source = stripSqlTerminator(sql);
+    const whereIndex = findTopLevelKeyword(source, 'where', 0);
+    if (whereIndex < 0)
+        return undefined;
+    const start = whereIndex + 'where'.length;
+    const endCandidates = ['group by', 'having', 'order by', 'limit', 'qualify']
+        .map((keyword) => findTopLevelKeyword(source, keyword, start))
+        .filter((index) => index >= 0);
+    const end = endCandidates.length > 0 ? Math.min(...endCandidates) : source.length;
+    const where = source.slice(start, end).trim();
+    return where || undefined;
+}
+function splitCompostingFilters(where) {
+    return splitCompostingTopLevel(where, 'and')
+        .map((part) => part.trim())
+        .filter(Boolean);
+}
+function splitCompostingTopLevel(input, delimiter) {
+    const out = [];
+    let start = 0;
+    let depth = 0;
+    let quote;
+    for (let i = 0; i < input.length; i += 1) {
+        const char = input[i];
+        if (quote) {
+            if (char === quote && input[i - 1] !== '\\')
+                quote = undefined;
+            continue;
+        }
+        if (char === '"' || char === "'" || char === '`') {
+            quote = char;
+            continue;
+        }
+        if (char === '(')
+            depth += 1;
+        else if (char === ')')
+            depth = Math.max(0, depth - 1);
+        if (depth !== 0)
+            continue;
+        if (delimiter === ',' && char === ',') {
+            out.push(input.slice(start, i).trim());
+            start = i + 1;
+        }
+        else if (delimiter === 'and'
+            && input.slice(i, i + 3).toLowerCase() === 'and'
+            && !/[A-Za-z0-9_]/.test(input[i - 1] ?? '')
+            && !/[A-Za-z0-9_]/.test(input[i + 3] ?? '')) {
+            out.push(input.slice(start, i).trim());
+            start = i + 3;
+            i += 2;
+        }
+    }
+    out.push(input.slice(start).trim());
+    return out.filter(Boolean);
+}
+function findTopLevelKeyword(input, keyword, fromIndex) {
+    const lower = input.toLowerCase();
+    const target = keyword.toLowerCase();
+    let depth = 0;
+    let quote;
+    for (let i = Math.max(0, fromIndex); i <= input.length - target.length; i += 1) {
+        const char = input[i];
+        if (quote) {
+            if (char === quote && input[i - 1] !== '\\')
+                quote = undefined;
+            continue;
+        }
+        if (char === '"' || char === "'" || char === '`') {
+            quote = char;
+            continue;
+        }
+        if (char === '(') {
+            depth += 1;
+            continue;
+        }
+        if (char === ')') {
+            depth = Math.max(0, depth - 1);
+            continue;
+        }
+        if (depth !== 0)
+            continue;
+        if (lower.slice(i, i + target.length) === target
+            && !/[A-Za-z0-9_]/.test(input[i - 1] ?? '')
+            && !/[A-Za-z0-9_]/.test(input[i + target.length] ?? '')) {
+            return i;
+        }
+    }
+    return -1;
+}
+function preferredCompostingMetricName(group) {
+    const aliases = group.aliases.map((alias) => slugForIdentifier(alias)).filter(Boolean);
+    const counts = new Map();
+    for (const alias of aliases)
+        counts.set(alias, (counts.get(alias) ?? 0) + 1);
+    const preferredAlias = Array.from(counts.entries()).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))[0]?.[0];
+    if (preferredAlias)
+        return preferredAlias;
+    const expressionName = slugForIdentifier(group.expression.replace(/\b(sum|avg|min|max|count|distinct)\b/gi, ''));
+    return expressionName ? `${expressionName}_${group.type}` : `${group.type}_metric`;
+}
+function dedupeCompostingName(baseName, usedNames) {
+    const base = slugForIdentifier(baseName).slice(0, 72).replace(/_+$/g, '');
+    if (!base)
+        return undefined;
+    if (!usedNames.has(base.toLowerCase()))
+        return base;
+    let index = 2;
+    while (usedNames.has(`${base}_${index}`.toLowerCase()))
+        index += 1;
+    return `${base}_${index}`;
+}
+function normalizeCompostingSql(value) {
+    return value
+        .replace(/["`]/g, '')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .toLowerCase();
+}
+function slugForIdentifier(value) {
+    return value
+        .trim()
+        .replace(/["`[\]]/g, '')
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '');
+}
+function slugForPath(value) {
+    return slugForIdentifier(value) || 'misc';
+}
+function stripIdentifierQuotes(value) {
+    return value.replace(/^["`\[]|["`\]]$/g, '').trim();
+}
+function titleFromSlug(value) {
+    return value.split('_').filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(' ');
+}
+function stableShortHash(value) {
+    return createHash('sha1').update(value).digest('hex').slice(0, 10);
+}
+function renderCompostingPrBody(candidates) {
+    const lines = [
+        '# Semantic Composting Changeset',
+        '',
+        'This changeset proposes draft semantic metrics mined from recurring logic in certified DQL blocks.',
+        'Review each metric expression, filter, owner, grain compatibility, and downstream impact before marking it certified.',
+        '',
+    ];
+    if (candidates.length === 0) {
+        lines.push('No recurring certified-block metric clusters met the current support threshold.');
+        return `${lines.join('\n')}\n`;
+    }
+    for (const candidate of candidates) {
+        lines.push(`## ${candidate.label}`);
+        lines.push('');
+        lines.push(`- Draft path: \`${candidate.draftPath}\``);
+        lines.push(`- Domain/table: \`${candidate.domain}\` / \`${candidate.table}\``);
+        lines.push(`- Expression: \`${candidate.sql}\``);
+        if (candidate.filter)
+            lines.push(`- Filter: \`${candidate.filter}\``);
+        lines.push(`- Support: ${candidate.support} certified block(s)`);
+        lines.push(`- Donors: ${candidate.donorBlocks.map((donor) => `\`${donor.path}\``).join(', ')}`);
+        lines.push('');
+    }
+    return `${lines.join('\n')}\n`;
+}
 export async function generateProposeDrafts(projectRoot, slugs, projectConfig = loadProjectConfig(projectRoot), options = {}) {
     const manifestPath = resolveDbtManifestPath(projectRoot, projectConfig);
     if (!manifestPath) {
@@ -8259,6 +9488,20 @@ function parseBlockStudioArrayField(source, key) {
 function parseBlockStudioStringField(source, key) {
     return source.match(new RegExp(`\\b${key}\\s*=\\s*"([^"]*)"`, 'i'))?.[1] ?? undefined;
 }
+function parseSemanticRequestedFilters(source) {
+    return parseBlockStudioArrayField(source, 'requested_filters')
+        .map((entry) => {
+        const match = entry.match(/^([^=<>!]+)\s*=\s*(.+)$/);
+        if (!match)
+            return undefined;
+        const dimension = match[1]?.trim();
+        const value = match[2]?.trim();
+        if (!dimension || !value)
+            return undefined;
+        return { dimension, operator: 'equals', values: [value] };
+    })
+        .filter((filter) => Boolean(filter));
+}
 function parseSemanticBlockConfig(source) {
     const blockType = (parseBlockStudioStringField(source, 'type') ?? 'custom').toLowerCase() === 'semantic'
         ? 'semantic'
@@ -8266,6 +9509,7 @@ function parseSemanticBlockConfig(source) {
     const metric = parseBlockStudioStringField(source, 'metric');
     const metrics = parseBlockStudioArrayField(source, 'metrics');
     const dimensions = parseBlockStudioArrayField(source, 'dimensions');
+    const filters = parseSemanticRequestedFilters(source);
     const timeDimension = parseBlockStudioStringField(source, 'time_dimension');
     const granularity = parseBlockStudioStringField(source, 'granularity');
     const limitMatch = source.match(/\blimit\s*=\s*(\d+)/i);
@@ -8274,6 +9518,7 @@ function parseSemanticBlockConfig(source) {
         metric,
         metrics,
         dimensions,
+        filters,
         timeDimension,
         granularity,
         limit: limitMatch ? Number.parseInt(limitMatch[1], 10) : undefined,
@@ -8419,6 +9664,7 @@ function composeSemanticBlockSql(source, semanticLayer, options) {
             ? composeRuntimeSemanticQuery({
                 metrics,
                 dimensions: config.dimensions,
+                filters: config.filters,
                 timeDimension: config.timeDimension && config.granularity
                     ? { name: config.timeDimension, granularity: config.granularity }
                     : undefined,
@@ -8433,6 +9679,7 @@ function composeSemanticBlockSql(source, semanticLayer, options) {
             : semanticLayer.composeQuery({
                 metrics,
                 dimensions: config.dimensions,
+                filters: config.filters,
                 timeDimension: config.timeDimension && config.granularity
                     ? { name: config.timeDimension, granularity: config.granularity }
                     : undefined,
@@ -8599,6 +9846,101 @@ export function validateBlockStudioSource(source, semanticLayer) {
         executableSql,
     };
 }
+export async function createDqlArtifactGenerationSessionForProject(projectRoot, options, semanticLayer) {
+    const dqlArtifact = normalizeDqlArtifactReference(options.dqlArtifact);
+    if (!dqlArtifact)
+        throw new Error('A DQL artifact with source is required for DQL draft promotion.');
+    const question = notebookResearchString(options.question) ?? dqlArtifact.name ?? 'Generated DQL artifact';
+    const slug = deriveGeneratedDraftSlug(dqlArtifact.name ?? question);
+    const domain = notebookResearchString(options.domain) ?? 'misc';
+    const owner = notebookResearchString(options.owner) ?? '';
+    const tags = Array.from(new Set(['notebook-research', 'review-required', 'dql-artifact', ...(Array.isArray(options.tags) ? options.tags : [])]
+        .map((tag) => notebookResearchString(tag))
+        .filter((tag) => Boolean(tag))));
+    const proposedContractId = `${domain}.Unknown.${slug}`;
+    const draft = upsertGeneratedDqlArtifactDraft(projectRoot, {
+        slug,
+        question,
+        proposedContractId,
+        owner,
+        proposedDomain: domain,
+        dqlArtifact,
+        sourceQuestion: question,
+        sourceBlock: options.sourceBlock,
+        contextPackId: options.contextPackId,
+        routeIntent: options.routeIntent,
+        outputs: Array.from(new Set([...(dqlArtifact.dimensions ?? []), ...(dqlArtifact.metrics ?? [])])),
+    });
+    const now = new Date().toISOString();
+    const uniqueSuffix = createHash('sha1').update(`${now}:${draft.path}:${dqlArtifact.source}`).digest('hex').slice(0, 12);
+    const importId = `imp_dql_artifact_${uniqueSuffix}`;
+    const candidateId = `cand_${slug.replace(/[^a-z0-9_]+/g, '_').replace(/^_+|_+$/g, '') || 'dql_artifact'}_${uniqueSuffix.slice(0, 6)}`;
+    const sourcePath = dqlArtifact.sourcePath ?? options.inputPath ?? draft.path;
+    const savedSource = readFileSync(join(projectRoot, draft.path), 'utf-8');
+    const candidate = {
+        id: candidateId,
+        sourceKind: 'raw-sql-file',
+        sourcePath,
+        name: dqlArtifact.name ?? slug,
+        domain,
+        description: question,
+        owner,
+        tags,
+        grain: dqlArtifact.timeDimension ? `${dqlArtifact.timeDimension.name}.${dqlArtifact.timeDimension.granularity}` : undefined,
+        outputs: Array.from(new Set([...(dqlArtifact.dimensions ?? []), ...(dqlArtifact.metrics ?? [])])),
+        dimensions: dqlArtifact.dimensions,
+        allowedFilters: dqlArtifact.filters?.map((filter) => filter.dimension),
+        parameterPolicy: dqlArtifact.filters?.map((filter) => ({ name: filter.dimension, policy: 'dynamic' })),
+        sql: notebookResearchString(options.generatedSql) ?? '',
+        dqlSource: savedSource,
+        validation: validateBlockStudioSource(savedSource, semanticLayer),
+        preview: null,
+        lineage: {
+            sourceTables: [],
+            parameters: [],
+            warnings: [],
+            statementIndex: 1,
+            totalStatements: 1,
+        },
+        confidence: 0.95,
+        splitStrategy: 'manual',
+        warnings: [],
+        conversionNotes: ['Persisted the DQL artifact returned by the governed answer; no SQL-to-DQL regeneration was required.'],
+        aiAssistance: [],
+        reviewStatus: 'draft',
+        savedPath: draft.path,
+        generationMode: 'deterministic',
+        generationProvider: 'dql-artifact',
+        llmContext: `Persisted generated DQL artifact for: ${question}`,
+        evidence: [],
+        draftSave: { status: 'saved', path: draft.path, savedAt: now },
+        recommendedAction: 'create_new',
+        similarityMatches: [],
+    };
+    const session = {
+        id: importId,
+        sourceKind: 'raw-sql-file',
+        inputPath: sourcePath,
+        inputMode: options.inputMode ?? 'upload',
+        sourceFiles: [sourcePath],
+        createdAt: now,
+        updatedAt: now,
+        defaults: { domain, owner, tags },
+        candidateIds: [candidate.id],
+        mode: 'ai-import',
+        generation: {
+            provider: 'dql-artifact',
+            aiEnabled: false,
+            contextObjectCount: 0,
+            createdDrafts: 1,
+            warnings: [],
+        },
+        candidates: [candidate],
+    };
+    writeBlockStudioImportSession(projectRoot, session);
+    await refreshLocalMetadataCatalog(projectRoot);
+    return session;
+}
 export async function createDqlGenerationSessionForProject(projectRoot, options, semanticLayer) {
     const deterministicOnly = isDeterministicDqlGenerationProvider(options.provider);
     const requestedProvider = !deterministicOnly && isProviderSettingsId(options.provider) ? options.provider : undefined;
@@ -9597,7 +10939,13 @@ function inferDqlGenerationPattern(sql) {
         return 'trend';
     if (groupFields.length === 1 && /_id$|_key$/i.test(groupFields[0]))
         return 'entity_rollup';
-    if (!/\b(sum|count|avg|min|max|median|percentile|rank)\s*\(/i.test(sql) && /\b(dim|profile|customer|account|player|product|user|entity)\b/i.test(sql)) {
+    // Entity profile = a non-aggregated, un-grouped row lookup filtered by an
+    // identifier (…WHERE <something>_id = / IN …). Structural + domain-agnostic —
+    // no hard-coded entity vocabulary.
+    const hasAggregate = /\b(sum|count|avg|min|max|median|percentile|rank)\s*\(/i.test(sql);
+    const hasGroupBy = /\bgroup\s+by\b/i.test(sql);
+    const filtersByIdentifier = /\bwhere\b[\s\S]*?\b[A-Za-z_][A-Za-z0-9_]*(?:_id|_key|id)\b\s*(?:=|in\b)/i.test(sql);
+    if (!hasAggregate && !hasGroupBy && filtersByIdentifier) {
         return 'entity_profile';
     }
     return 'custom';
@@ -10195,10 +11543,15 @@ async function createBlockStudioAssistProvider(projectRoot, requestedProvider) {
             provider = new OpenAIProvider({ apiKey: config.apiKey, baseUrl: config.baseUrl, model: config.model, allowNoApiKey: true });
             break;
         case 'claude-code':
-            provider = new ClaudeCodeCliProvider({ model: config.model });
+            // OAuth-first: use the browser-login token when connected; fall back to the CLI passthrough.
+            provider = claudeOAuthConnected(projectRoot)
+                ? new ClaudeOAuthProvider({ projectRoot, model: config.model })
+                : new ClaudeCodeCliProvider({ model: config.model });
             break;
         case 'codex':
-            provider = new CodexCliProvider({ model: config.model });
+            provider = codexOAuthConnected(projectRoot)
+                ? new CodexOAuthProvider({ projectRoot, model: config.model })
+                : new CodexCliProvider({ model: config.model });
             break;
         default:
             return null;
@@ -10212,8 +11565,7 @@ function agentResultToSynthesisPreview(result) {
     const columns = Array.isArray(result.columns)
         ? result.columns.map((col) => typeof col === 'string' ? col : col?.name ?? String(col))
         : [];
-    const rawRows = Array.isArray(result.rows) ? result.rows.slice(0, 20) : [];
-    const rows = rawRows.map((row) => {
+    const normalizeRow = (row) => {
         if (row && typeof row === 'object' && !Array.isArray(row))
             return row;
         // Array-shaped rows → zip with column names.
@@ -10223,69 +11575,20 @@ function agentResultToSynthesisPreview(result) {
             return obj;
         }
         return { value: row };
-    });
+    };
+    // Normalize ALL rows so verified statistics cover the full result — the
+    // narrator sees only a 20-row sample, and sample-derived aggregate claims
+    // ("spend ranges from X to Y") were the last hallucination surface.
+    const allRows = Array.isArray(result.rows) ? result.rows.map(normalizeRow) : [];
+    const rows = allRows.slice(0, 20);
+    const resolvedColumns = columns.length > 0 ? columns : Object.keys(rows[0] ?? {});
     return {
-        columns: columns.length > 0 ? columns : Object.keys(rows[0] ?? {}),
+        columns: resolvedColumns,
         rows,
-        rowCount: typeof result.rowCount === 'number' ? result.rowCount : rows.length,
+        rowCount: typeof result.rowCount === 'number' ? result.rowCount : allRows.length,
+        stats: computeResultStats(resolvedColumns, allRows),
     };
 }
-const SIGNAL_STOPWORDS = new Set([
-    'the', 'a', 'an', 'of', 'for', 'to', 'by', 'in', 'on', 'and', 'or', 'is', 'are', 'was', 'were',
-    'what', 'which', 'how', 'show', 'me', 'my', 'our', 'this', 'that', 'top', 'give', 'get', 'list',
-]);
-function signalTokens(text) {
-    return new Set(text.toLowerCase().replace(/[^a-z0-9\s]/g, ' ').split(/\s+/)
-        .filter((token) => token.length > 2 && !SIGNAL_STOPWORDS.has(token)));
-}
-/** Best token-overlap ratio between the question and any candidate name/description. */
-function bestOverlap(questionTokens, candidates) {
-    if (questionTokens.size === 0)
-        return 0;
-    let best = 0;
-    for (const candidate of candidates) {
-        const candTokens = signalTokens(candidate);
-        if (candTokens.size === 0)
-            continue;
-        let hits = 0;
-        for (const token of candTokens)
-            if (questionTokens.has(token))
-                hits += 1;
-        if (hits === 0)
-            continue;
-        // Ratio of the candidate's tokens the question covers — rewards a tight match.
-        const ratio = hits / Math.min(candTokens.size, questionTokens.size);
-        if (ratio > best)
-            best = ratio;
-    }
-    return Math.min(1, best);
-}
-/**
- * Cheap, offline retrieval-signal probe. Fills certifiedScore/metricScore/hasRetrieval
- * from local catalog name/description overlap so the deterministic router can reach
- * confidence (and skip the LLM) on obvious governed matches. Best-effort — any failure
- * yields empty signals and the router simply leans on its LLM classification.
- */
-function computeAgentRunSignals(projectRoot, question) {
-    try {
-        const tokens = signalTokens(question);
-        if (tokens.size === 0)
-            return { certifiedScore: 0, metricScore: 0, hasRetrieval: false };
-        const certifiedBlocks = collectPlanBlocks(projectRoot, { certifiedOnly: true });
-        const blockStrings = certifiedBlocks.flatMap((block) => [block.name, block.description ?? ''].filter(Boolean));
-        const metrics = loadSemanticMetrics(projectRoot);
-        const metricStrings = metrics.map((metric) => {
-            const node = metric;
-            return node.name ?? node.label ?? node.id ?? '';
-        }).filter(Boolean);
-        const certifiedScore = bestOverlap(tokens, blockStrings);
-        const metricScore = bestOverlap(tokens, metricStrings);
-        return { certifiedScore, metricScore, hasRetrieval: certifiedScore > 0 || metricScore > 0 };
-    }
-    catch {
-        return { certifiedScore: 0, metricScore: 0, hasRetrieval: false };
-    }
-}
 /** Up to three example questions built from real catalog blocks (falls back to generic asks). */
 function buildConversationSuggestions(projectRoot, kind) {
     if (kind === 'gratitude')
@@ -10340,6 +11643,141 @@ function buildConversationSystemPrompt(kind, isGeneralKnowledge, catalogContext,
     }
     return lines.join('\n');
 }
+function renderConversationMemoryForPrompt(context) {
+    const recap = buildConversationContextRecap(context);
+    if (!recap)
+        return undefined;
+    return [
+        'Current conversation context:',
+        recap,
+        'If the user asks what this conversation is about, summarize this context directly. Do not query data or invent values.',
+    ].join('\n');
+}
+function buildConversationContextRecap(context) {
+    if (!context)
+        return undefined;
+    const turnRecap = buildConversationTurnsRecap(context);
+    if (turnRecap)
+        return turnRecap;
+    const sourceQuestion = agentRunString(context.sourceQuestion);
+    const sourceAnswerSummary = agentRunString(context.sourceAnswerSummary);
+    const columns = agentRunStringArray(context.resultColumns ?? context.outputColumns).slice(0, 8);
+    const values = agentRunRecord(context.resultDimensionValues);
+    const rows = Array.isArray(context.resultRowsSample)
+        ? context.resultRowsSample.map(agentRunRecord).filter((row) => Boolean(row)).slice(0, 1)
+        : [];
+    const firstRow = rows[0];
+    const leadParts = buildPriorValueLeadParts(values);
+    const rowFacts = firstRow
+        ? columns
+            .slice(0, 5)
+            .map((column) => {
+            const value = firstRow[column];
+            return value === undefined || value === null || typeof value === 'object' ? '' : `${column}=${String(value)}`;
+        })
+            .filter(Boolean)
+        : [];
+    const contextBits = [
+        sourceQuestion ? `the question "${sourceQuestion}"` : '',
+        sourceAnswerSummary ? `the latest answer summary: ${sourceAnswerSummary}` : '',
+        columns.length ? `result columns: ${columns.join(', ')}` : '',
+        leadParts.length ? `notable prior values: ${leadParts.join(', ')}` : '',
+        rowFacts.length ? `first result row: ${rowFacts.join(', ')}` : '',
+    ].filter(Boolean);
+    if (contextBits.length === 0)
+        return undefined;
+    return `We were talking about ${contextBits.join('. ')}.`;
+}
+function buildConversationTurnsRecap(context) {
+    const turns = Array.isArray(context.turns)
+        ? context.turns.map(agentRunRecord).filter((turn) => Boolean(turn)).slice(-3)
+        : [];
+    if (turns.length === 0)
+        return undefined;
+    const activeTurnId = agentRunString(context.activeTurnId);
+    const active = activeTurnId
+        ? turns.find((turn) => agentRunString(turn.id) === activeTurnId)
+        : undefined;
+    const selected = active ?? turns[turns.length - 1];
+    if (!selected)
+        return undefined;
+    const result = agentRunRecord(selected.result);
+    const values = agentRunRecord(result?.dimensionValues);
+    const columns = agentRunStringArray(result?.columns).slice(0, 8);
+    const rows = Array.isArray(result?.rowsSample)
+        ? result.rowsSample.map(agentRunRecord).filter((row) => Boolean(row)).slice(0, 1)
+        : [];
+    const firstRow = rows[0];
+    const leadParts = buildPriorValueLeadParts(values);
+    const rowFacts = firstRow
+        ? columns
+            .slice(0, 5)
+            .map((column) => {
+            const value = firstRow[column];
+            return value === undefined || value === null || typeof value === 'object' ? '' : `${column}=${String(value)}`;
+        })
+            .filter(Boolean)
+        : [];
+    const previous = turns
+        .filter((turn) => turn !== selected)
+        .map((turn) => agentRunString(turn.question))
+        .filter((value) => Boolean(value))
+        .slice(-2);
+    const bits = [
+        agentRunString(selected.question) ? `the latest question "${agentRunString(selected.question)}"` : '',
+        agentRunString(selected.answerSummary) ? `latest answer summary: ${agentRunString(selected.answerSummary)}` : '',
+        columns.length ? `result columns: ${columns.join(', ')}` : '',
+        leadParts.length ? `notable prior values: ${leadParts.join(', ')}` : '',
+        rowFacts.length ? `first result row: ${rowFacts.join(', ')}` : '',
+        previous.length ? `earlier in this thread: ${previous.join(' / ')}` : '',
+    ].filter(Boolean);
+    return bits.length > 0 ? `We were talking about ${bits.join('. ')}.` : undefined;
+}
+function agentRunStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return Array.from(new Set(value.map(agentRunString).filter((item) => Boolean(item))));
+}
+function firstPriorValue(values, keys) {
+    if (!values)
+        return undefined;
+    for (const key of keys) {
+        const list = Array.isArray(values[key]) ? values[key] : [];
+        const first = list.map(agentRunString).find(Boolean);
+        if (first)
+            return first;
+    }
+    return undefined;
+}
+/**
+ * Build human-readable "notable prior values" for conversation recap from whatever
+ * dimension columns the prior result actually had. Domain-agnostic: name/label-ish
+ * columns are surfaced first, then any other dimension — no hard-coded jaffle entity
+ * columns — so follow-up questions get meaningful context on ANY repo.
+ */
+function buildPriorValueLeadParts(values) {
+    if (!values)
+        return [];
+    const keys = Object.keys(values);
+    const nameLike = keys.filter((key) => /(?:^|_)(?:name|label|title|nm)$/i.test(key));
+    const ordered = [...nameLike, ...keys.filter((key) => !nameLike.includes(key))];
+    const parts = [];
+    const seenLabels = new Set();
+    for (const key of ordered) {
+        if (parts.length >= 3)
+            break;
+        const value = firstPriorValue(values, [key]);
+        if (!value)
+            continue;
+        const label = (key.replace(/_?(?:name|id|key|label|title|nm)$/i, '').replace(/[_-]+/g, ' ').trim()
+            || key.replace(/[_-]+/g, ' ').trim()).toLowerCase();
+        if (seenLabels.has(label))
+            continue;
+        seenLabels.add(label);
+        parts.push(label ? `${label} "${value}"` : `"${value}"`);
+    }
+    return parts;
+}
 /** Deterministic, warm reply when no AI provider is configured — never governance-speak. */
 function buildConversationalFallback(kind, isGeneralKnowledge, question, suggestions) {
     const examples = suggestions.length > 0
@@ -12104,13 +13542,6 @@ function collectSettingsEnvStatus() {
         },
     ];
 }
-function isProviderSettingsId(value) {
-    return value === 'anthropic'
-        || value === 'openai'
-        || value === 'gemini'
-        || value === 'ollama'
-        || value === 'custom-openai';
-}
 function isDeterministicDqlGenerationProvider(value) {
     if (typeof value !== 'string')
         return false;
@@ -12131,8 +13562,8 @@ async function testProviderConfig(projectRoot, id, overrides) {
     const label = providerSettingsLabel(id);
     const details = providerConfigDetails(id, config);
     const isSubscriptionCli = id === 'claude-code' || id === 'codex';
-    // Subscription CLI providers are always testable — detection (installed + logged in)
-    // needs no saved config; the others require enabling/saving first.
+    // Subscription providers are always testable — the connection (browser OAuth, or
+    // an installed+logged-in CLI) needs no saved config; the others require enabling first.
     if (!config.enabled && !isSubscriptionCli) {
         return { ok: false, message: `${label} is disabled. Enable it (or Save) before testing.` };
     }
@@ -12140,6 +13571,11 @@ async function testProviderConfig(projectRoot, id, overrides) {
         return testOpenAIProviderConfig(config, label, details);
     if (id === 'anthropic')
         return testAnthropicProviderConfig(config, label, details);
+    // OAuth-first for subscriptions: when the user signed in via the browser, test the
+    // OAuth-backed provider (no CLI required); otherwise fall back to the CLI passthrough.
+    // Mirrors the runtime selection in dql-agent-provider / createBlockStudioAssistProvider.
+    const claudeOAuth = id === 'claude-code' && claudeOAuthConnected(projectRoot);
+    const codexOAuth = id === 'codex' && codexOAuthConnected(projectRoot);
     let provider;
     switch (id) {
         case 'gemini':
@@ -12149,10 +13585,14 @@ async function testProviderConfig(projectRoot, id, overrides) {
             provider = new OllamaProvider({ baseUrl: config.baseUrl, model: config.model });
             break;
         case 'claude-code':
-            provider = new ClaudeCodeCliProvider({ model: config.model });
+            provider = claudeOAuth
+                ? new ClaudeOAuthProvider({ projectRoot, model: config.model })
+                : new ClaudeCodeCliProvider({ model: config.model });
             break;
         case 'codex':
-            provider = new CodexCliProvider({ model: config.model });
+            provider = codexOAuth
+                ? new CodexOAuthProvider({ projectRoot, model: config.model })
+                : new CodexCliProvider({ model: config.model });
             break;
         case 'custom-openai':
         default:
@@ -12162,10 +13602,11 @@ async function testProviderConfig(projectRoot, id, overrides) {
     const available = await provider.available().catch(() => false);
     if (!available) {
         const cli = id === 'claude-code' ? 'claude' : 'codex';
+        const signIn = id === 'claude-code' ? 'Sign in with Claude' : 'Sign in with ChatGPT';
         return {
             ok: false,
             message: isSubscriptionCli
-                ? `${label} is not ready. Install the \`${cli}\` CLI and run \`${cli} ${id === 'claude-code' ? '/login' : 'login'}\` with your subscription, then test again.`
+                ? `${label} is not ready. Click "${signIn}" to sign in with your subscription, or install the \`${cli}\` CLI and run \`${cli} ${id === 'claude-code' ? '/login' : 'login'}\`, then test again.`
                 : `${label} is not configured or reachable${details}. Check API key, base URL, and local service state.`,
         };
     }
@@ -12248,10 +13689,16 @@ function providerSettingsLabel(id) {
     }
 }
 function providerConfigDetails(id, config) {
+    // Subscription providers (Claude Code / Codex) authenticate via OAuth/CLI, not an
+    // API key — omit the key clause so we don't report a misleading "API key missing".
+    const isSubscription = id === 'claude-code' || id === 'codex';
+    const authNote = isSubscription
+        ? ''
+        : id === 'ollama' ? 'local endpoint' : config.apiKey ? 'API key present' : 'API key missing';
     const parts = [
         config.model ? `model ${config.model}` : '',
         config.baseUrl ? `base URL ${config.baseUrl}` : '',
-        id === 'ollama' ? 'local endpoint' : config.apiKey ? 'API key present' : 'API key missing',
+        authNote,
     ].filter(Boolean);
     return parts.length ? ` (${parts.join(', ')})` : '';
 }
@@ -12273,7 +13720,7 @@ function recordAgentRuntimeSchemaSnapshot(projectRoot, schemaContext, source) {
     try {
         recordRuntimeSchemaSnapshot(projectRoot, {
             source,
-            tables: schemaContext.slice(0, 80).map((table) => ({
+            tables: schemaContext.map((table) => ({
                 relation: table.relation,
                 schema: table.schema,
                 name: table.name,
@@ -12427,7 +13874,9 @@ function buildNotebookResearchReviewChecklist(run) {
     const questionReady = Boolean(notebookResearchString(run.question));
     const hasReviewedSql = Boolean(notebookResearchString(run.reviewedSql));
     const hasGeneratedSql = Boolean(notebookResearchString(run.generatedSql));
+    const hasDqlArtifact = Boolean(normalizeDqlArtifactReference(run.dqlArtifact)?.source);
     const hasSql = hasReviewedSql || hasGeneratedSql;
+    const hasPromotableSource = hasReviewedSql || hasDqlArtifact;
     const preview = notebookResearchPreviewInfo(run.resultPreview);
     const previewReady = run.status === 'ready' && preview.hasPreview;
     const evidenceReady = notebookResearchEvidenceCount(run.evidence) > 0 || Boolean(run.contextPackId);
@@ -12446,8 +13895,8 @@ function buildNotebookResearchReviewChecklist(run) {
     const warnings = [];
     if (!questionReady)
         blockers.push('Add a business question before review.');
-    if (!hasSql && !reuseRecommended)
-        blockers.push('Add reviewed SQL or generate SQL before promotion.');
+    if (!hasSql && !hasDqlArtifact && !reuseRecommended)
+        blockers.push('Add reviewed SQL, generate SQL, or attach a DQL artifact before promotion.');
     if (run.status === 'error')
         blockers.push(run.error ? `Fix preview error: ${run.error}` : 'Fix the failed preview before promotion.');
     if (!previewReady && run.status !== 'error' && !reuseRecommended)
@@ -12473,15 +13922,17 @@ function buildNotebookResearchReviewChecklist(run) {
         },
         {
             id: 'sql',
-            label: 'Reviewed SQL',
-            status: hasReviewedSql || (reuseRecommended && !hasSql) ? 'passed' : hasGeneratedSql ? 'warning' : 'blocked',
+            label: hasDqlArtifact && !hasReviewedSql ? 'DQL artifact' : 'Reviewed SQL',
+            status: hasReviewedSql || hasDqlArtifact || (reuseRecommended && !hasSql) ? 'passed' : hasGeneratedSql ? 'warning' : 'blocked',
             detail: reuseRecommended && !hasSql
                 ? 'Existing certified DQL should be reused; no new SQL is required.'
-                : hasReviewedSql
-                    ? 'Reviewer SQL is saved.'
-                    : hasGeneratedSql
-                        ? 'Generated SQL exists; review it before promotion.'
-                        : 'No SQL is available for preview or DQL generation.',
+                : hasDqlArtifact && !hasReviewedSql
+                    ? 'Generated DQL artifact is saved for reviewer promotion.'
+                    : hasReviewedSql
+                        ? 'Reviewer SQL is saved.'
+                        : hasGeneratedSql
+                            ? 'Generated SQL exists; review it before promotion.'
+                            : 'No SQL is available for preview or DQL generation.',
         },
         {
             id: 'preview',
@@ -12518,33 +13969,35 @@ function buildNotebookResearchReviewChecklist(run) {
         {
             id: 'parameters',
             label: 'Parameter review',
-            status: reuseRecommended && !hasSql ? 'passed' : !hasSql ? 'pending' : dynamicParameters.length > 0 ? 'passed' : 'warning',
+            status: reuseRecommended && !hasSql ? 'passed' : !hasSql && !hasDqlArtifact ? 'pending' : hasDqlArtifact && !hasSql ? 'passed' : dynamicParameters.length > 0 ? 'passed' : 'warning',
             detail: reuseRecommended && !hasSql
                 ? 'Use the certified block parameters; no new SQL parameterization is required.'
-                : !hasSql
-                    ? 'Add SQL before checking runtime parameters.'
-                    : dynamicParameters.length > 0
-                        ? `Detected ${dynamicParameters.length.toLocaleString()} dynamic parameter${dynamicParameters.length === 1 ? '' : 's'}: ${dynamicParameters.slice(0, 6).map((item) => item.name).join(', ')}.`
-                        : staticParameters.length > 0
-                            ? `Only static or review-required literals were detected: ${staticParameters.slice(0, 6).map((item) => `${item.name} (${item.policy})`).join(', ')}.`
-                            : 'No reusable runtime parameters were detected. Certify as static only if the business question is intentionally fixed.',
+                : !hasSql && hasDqlArtifact
+                    ? 'Review parameters declared in the DQL artifact.'
+                    : !hasSql
+                        ? 'Add SQL or a DQL artifact before checking runtime parameters.'
+                        : dynamicParameters.length > 0
+                            ? `Detected ${dynamicParameters.length.toLocaleString()} dynamic parameter${dynamicParameters.length === 1 ? '' : 's'}: ${dynamicParameters.slice(0, 6).map((item) => item.name).join(', ')}.`
+                            : staticParameters.length > 0
+                                ? `Only static or review-required literals were detected: ${staticParameters.slice(0, 6).map((item) => `${item.name} (${item.policy})`).join(', ')}.`
+                                : 'No reusable runtime parameters were detected. Certify as static only if the business question is intentionally fixed.',
         },
         {
             id: 'dql_draft',
             label: 'DQL draft',
-            status: reuseRecommended && !hasDraft ? 'passed' : hasDraft ? 'passed' : hasReviewedSql && evidenceReady ? 'pending' : 'blocked',
+            status: reuseRecommended && !hasDraft ? 'passed' : hasDraft ? 'passed' : hasPromotableSource && evidenceReady ? 'pending' : 'blocked',
             detail: reuseRecommended && !hasDraft
                 ? 'No new draft is required because an existing DQL block should be reused.'
                 : hasDraft
                     ? `Draft saved at ${run.draftBlockPath}.`
-                    : !hasReviewedSql
-                        ? 'Save reviewed SQL before DQL draft creation.'
+                    : !hasPromotableSource
+                        ? 'Save reviewed SQL or review the generated DQL artifact before DQL draft creation.'
                         : evidenceReady
-                            ? 'Create a draft after SQL review.'
+                            ? (hasDqlArtifact && !hasReviewedSql ? 'Create a draft after DQL artifact review.' : 'Create a draft after SQL review.')
                             : 'Save metadata evidence before creating a reusable DQL draft.',
         },
     ];
-    const readyForDqlDraft = questionReady && hasReviewedSql && evidenceReady && run.status !== 'error';
+    const readyForDqlDraft = questionReady && hasPromotableSource && evidenceReady && run.status !== 'error';
     const readyForCertificationReview = readyForDqlDraft && previewReady && hasDraft && !reuseRecommended && !promotionReviewRequired;
     return { readyForDqlDraft, readyForCertificationReview, blockers, warnings, items };
 }
@@ -12552,6 +14005,8 @@ function buildNotebookResearchPlan(input) {
     const reviewedSql = notebookResearchString(input.reviewedSql);
     const generatedSql = notebookResearchString(input.generatedSql);
     const sql = reviewedSql ?? generatedSql;
+    const dqlArtifact = normalizeDqlArtifactReference(input.dqlArtifact) ?? input.run.dqlArtifact;
+    const hasDqlArtifact = Boolean(dqlArtifact?.source);
     const parameterized = sql ? parameterizeSqlForDqlImport(sql) : null;
     const evidence = input.evidence && typeof input.evidence === 'object' && !Array.isArray(input.evidence)
         ? input.evidence
@@ -12590,6 +14045,7 @@ function buildNotebookResearchPlan(input) {
         promotion: {
             path: notebookResearchPlanPromotionPath({
                 hasSql: Boolean(sql),
+                hasDqlArtifact,
                 hasEvidence,
                 hasPreview,
                 previewError: input.previewError,
@@ -12600,6 +14056,7 @@ function buildNotebookResearchPlan(input) {
         },
         reviewFocus: notebookResearchPlanFocus(input.run.intent, {
             hasSql: Boolean(sql),
+            hasDqlArtifact,
             hasEvidence,
             hasPreview,
             dynamicParameterCount: parameterized?.parameterPolicy.filter((entry) => entry.policy === 'dynamic').length ?? 0,
@@ -12612,7 +14069,7 @@ function buildNotebookResearchPlan(input) {
 function notebookResearchPlanPromotionPath(input) {
     if (input.promotionAction === 'reuse_existing')
         return 'reuse_existing';
-    if (!input.hasSql)
+    if (!input.hasSql && !input.hasDqlArtifact)
         return 'needs_sql';
     if (!input.hasEvidence)
         return 'review_context';
@@ -12624,8 +14081,8 @@ function notebookResearchPlanPromotionPath(input) {
 }
 function notebookResearchPlanFocus(intent, input) {
     const focus = new Set();
-    if (!input.hasSql)
-        focus.add('Add reviewed SQL or configure AI SQL generation.');
+    if (!input.hasSql && !input.hasDqlArtifact)
+        focus.add('Add reviewed SQL, a DQL artifact, or configure AI generation.');
     if (!input.hasEvidence)
         focus.add('Save metadata context evidence before DQL promotion.');
     if (!input.hasPreview)
@@ -13096,7 +14553,7 @@ function dedupeAgentSchemaColumns(columns) {
     }
     return Array.from(byName.values());
 }
-export function buildAgentSchemaContext(question, rows) {
+export function buildAgentSchemaContext(question, rows, options = {}) {
     const byRelation = new Map();
     for (const row of rows) {
         if (!row || typeof row !== 'object')
@@ -13125,16 +14582,82 @@ export function buildAgentSchemaContext(question, rows) {
     }
     const tokens = agentSchemaTokens(question);
     const shouldProbeValues = extractAgentValueSearchTerms(question).length > 0;
+    const limit = Math.max(1, Math.trunc(options.limit ?? 12));
     return Array.from(byRelation.values())
         .map((table) => ({
         table,
         score: scoreAgentSchemaTable(table, tokens) + (shouldProbeValues ? scoreAgentValueProbeTable(table) : 0),
     }))
-        .filter((entry) => entry.score > 0)
+        .filter((entry) => options.includeUnscored || entry.score > 0)
         .sort((a, b) => b.score - a.score || a.table.relation.localeCompare(b.table.relation))
-        .slice(0, 12)
+        .slice(0, limit)
         .map((entry) => entry.table);
 }
+function mergeAgentSchemaContexts(...contexts) {
+    const byRelation = new Map();
+    for (const table of contexts.flat()) {
+        const key = table.relation.toLowerCase();
+        const existing = byRelation.get(key);
+        if (!existing) {
+            byRelation.set(key, {
+                ...table,
+                columns: dedupeAgentSchemaColumns(table.columns).slice(0, 80),
+            });
+            continue;
+        }
+        byRelation.set(key, {
+            ...existing,
+            description: existing.description ?? table.description,
+            source: existing.source === table.source ? existing.source : 'catalog and runtime schema',
+            columns: dedupeAgentSchemaColumns([...existing.columns, ...table.columns]).slice(0, 80),
+        });
+    }
+    return Array.from(byRelation.values()).slice(0, 16);
+}
+function mergeAgentSchemaSampleValues(snapshot, enriched) {
+    const samples = new Map();
+    for (const table of enriched) {
+        for (const column of table.columns) {
+            if (!column.sampleValues?.length)
+                continue;
+            samples.set(`${table.relation.toLowerCase()}\u0000${column.name.toLowerCase()}`, column.sampleValues);
+        }
+    }
+    if (samples.size === 0)
+        return snapshot;
+    return snapshot.map((table) => ({
+        ...table,
+        columns: table.columns.map((column) => {
+            const sampleValues = samples.get(`${table.relation.toLowerCase()}\u0000${column.name.toLowerCase()}`);
+            return sampleValues?.length
+                ? { ...column, sampleValues: uniqueStrings([...(column.sampleValues ?? []), ...sampleValues]).slice(0, 8) }
+                : column;
+        }),
+    }));
+}
+// Common English plurals that are NOT entity nouns, so a multi-entity heuristic
+// doesn't count them. Domain-agnostic (no project-specific vocabulary).
+const NON_ENTITY_PLURALS = new Set([
+    'details', 'values', 'results', 'rows', 'numbers', 'records', 'items', 'things',
+    'totals', 'amounts', 'metrics', 'columns', 'fields', 'names', 'ids',
+]);
+/**
+ * Decide whether to run the (advisory, best-effort) runtime value-scan + schema
+ * enrichment for a question. Generic multi-entity / detail intent — no hard-coded
+ * project vocabulary — so it fires for ANY repo's join-shaped questions, not just
+ * jaffle. Over-triggering only costs a few extra bounded probes (all in try/catch).
+ */
+function shouldAugmentAgentRuntimeSchema(question) {
+    const lower = question.toLowerCase();
+    const wantsMetric = /\brevenu|\bsales\b|\bamount\b|\bspend\b|\bcost\b|\bcount\b|\btotal\b|\bsum\b|\bavg\b|\baverage\b|\bvalue\b|\bprice\b/.test(lower);
+    const wantsDetail = /\bdetails?\b|\bcomplete\b|\bbreakdown\b|\ball\s+values?\b|\beach\b|\bevery\b/.test(lower);
+    const referencesPriorRows = /\b(?:above|previous|prior|these|those|same)\s+\w+/.test(lower);
+    const explicitJoin = /\bjoin(?:ed|ing)?\b|\bcombine[ds]?\b|\bcross[- ]?reference\b|\balong\s+with\b|\btogether\s+with\b/.test(lower);
+    // Multi-entity intent: a linking word + >= 2 distinct plural content nouns.
+    const nouns = new Set((lower.match(/\b[a-z]{4,}s\b/g) ?? []).filter((word) => !NON_ENTITY_PLURALS.has(word)));
+    const multiEntity = /\b(?:and|with|plus|per|for\s+each|by)\b/.test(lower) && nouns.size >= 2;
+    return explicitJoin || referencesPriorRows || (multiEntity && (wantsMetric || wantsDetail));
+}
 async function enrichAgentSchemaContextWithValueMatches(question, schemaContext, executor, connection) {
     const searchTerms = extractAgentValueSearchTerms(question);
     if (schemaContext.length === 0 || searchTerms.length === 0)
@@ -13186,8 +14709,57 @@ function scoreAgentSchemaTable(table, tokens) {
                 score += 3;
         }
     }
-    if (/(customer|order|revenue|product|location|date|month)/i.test(table.name))
+    score += scoreCompositeAgentSchemaTable(table, tokens);
+    // Small tiebreaker toward modeled analytics tables (fct_/dim_/fact_/mart_ …),
+    // a warehouse-modeling convention that generalizes across repos — not a fixed
+    // list of jaffle entity names.
+    if (/^(?:fct|fact|dim|dimension|mart|rpt|report|agg|f|d)[_-]/i.test(table.name)
+        || /(?:^|[_-])(?:fact|dim|mart|summary|report)(?:$|[_-])/i.test(table.name)) {
         score += 1;
+    }
+    return score;
+}
+const COMPOSITE_METRIC_TOKENS = new Set([
+    'revenue', 'sales', 'amount', 'spend', 'price', 'cost', 'total', 'sum',
+    'count', 'quantity', 'qty', 'value', 'subtotal', 'order', 'orders',
+]);
+const COMPOSITE_STOPWORD_TOKENS = new Set([
+    'the', 'and', 'with', 'for', 'each', 'per', 'all', 'top', 'show', 'list',
+    'give', 'get', 'find', 'plus', 'along', 'together', 'combined', 'combine',
+    'detail', 'details', 'complete', 'breakdown', 'values', 'name', 'names',
+    ...COMPOSITE_METRIC_TOKENS,
+]);
+/**
+ * Boost the fact/junction table for a multi-entity ("composite") question. Fully
+ * domain-agnostic: the ask is detected from >= 2 distinct entity tokens + a metric,
+ * and the winning table is identified STRUCTURALLY (>= 2 foreign-key-style id columns
+ * plus a numeric measure column) rather than by hard-coded jaffle table names — so it
+ * ranks the right join table for any repo, while jaffle's fct_orders still qualifies.
+ */
+function scoreCompositeAgentSchemaTable(table, tokens) {
+    const entityTokens = [...tokens].filter((token) => token.length >= 3 && !COMPOSITE_STOPWORD_TOKENS.has(token));
+    const hasMetric = [...tokens].some((token) => COMPOSITE_METRIC_TOKENS.has(token));
+    const hasCompositeAsk = entityTokens.length >= 2 && hasMetric;
+    const hasPriorRowsAsk = ['above', 'previous', 'prior', 'these', 'those', 'same'].some((token) => tokens.has(token))
+        && entityTokens.length >= 1;
+    if (!hasCompositeAsk && !hasPriorRowsAsk)
+        return 0;
+    const columns = table.columns.map((column) => column.name.toLowerCase());
+    let score = 0;
+    // Structural fact/junction-table signal: multiple FK-style id columns + a measure.
+    const idColumnCount = columns.filter((name) => /(?:^id$|_id$|_key$|_sk$|_uuid$|_fk$)/.test(name)).length;
+    const hasMeasureColumn = columns.some((name) => /revenue|sales|amount|price|spend|cost|subtotal|total|quantity|\bqty\b|count|value/.test(name));
+    if (idColumnCount >= 2 && hasMeasureColumn)
+        score += 18;
+    else if (idColumnCount >= 2)
+        score += 8;
+    if (hasMeasureColumn)
+        score += 8;
+    // Reward columns whose names overlap the question's actual entity tokens (any domain).
+    for (const token of entityTokens) {
+        if (columns.some((name) => name.includes(token)))
+            score += 4;
+    }
     return score;
 }
 function scoreAgentValueProbeTable(table) {