@duckcodeailabs/dql-cli 1.7.1 → 1.8.0

package/dist/local-runtime.js

@@ -4,19 +4,19 @@ import { createServer } from "node:http";
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, watch, writeFileSync, } from "node:fs";
 import { createRequire } from "node:module";
 import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
 import { dirname, extname, join, normalize, relative, resolve, } from "node:path";
 import { Readable } from "node:stream";
 import { buildMixedSourceWarehouseFallbackSql, findMentionedNotebookDataset, planMixedSourceNotebookSql, planMixedSourceSql, } from "./mixed-source-sql.js";
-import Anthropic from "@anthropic-ai/sdk";
-import OpenAI from "openai";
+import { resolveNpmInvocation } from './npm-runtime.js';
 import { buildExecutionPlan, createWelcomeNotebook, deserializeNotebook, getConnectorFormSchemas, hasSemanticRefs, hasStandaloneSemanticRef, resolveSemanticRefs, } from '@duckcodeailabs/dql-notebook';
 import { loadSemanticLayerFromDir, normalizeDqlArtifactReference, serializeMetricDefinitionToYaml, resolveSemanticLayerAsync, resolveRepoSource, getDialect, Parser, NodeKind, blockParameterDefinitions, buildLineageGraph, buildManifest, collectInputFiles, findAppDocuments, findDashboardsForApp, isBlockIdRef, loadAppDocument, loadDashboardDocument, analyzeImpact, buildTrustChain, detectDomainFlows, getDomainTrustOverview, queryLineage, queryBusiness360, queryCompleteLineagePaths, LineageGraph, canonicalize, canonicalizeNotebook, diffDQL, diffNotebook, domainFolderSlug, previewModelingChange, applyModelingChange, previewDbtSourcePatch, applyDbtSourcePatch, loadDomainPackageRegistry, loadDbtNodeAuthoringDetail, relationshipValidationProofFingerprint, discoverDbtDomains, renderDomainDeclaration, ProjectSnapshotService, analyzeSqlReferences, } 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 { createDqlAgentProviderRunner, resolveAgentFollowUpContext } from './llm/providers/dql-agent-provider.js';
 import { listRemoteMcpSettings, saveRemoteMcpSettings } from './llm/mcp-config.js';
-import { ClaudeProvider, ConversationStore, advanceThreadState, buildConversationSnapshot, recallRelevantTurns, GeminiProvider, MemoryStore, OllamaProvider, OpenAIProvider, buildBlockBusinessFingerprint, buildBlockSqlFingerprints, buildLocalContextPack, defaultConversationPath, defaultMemoryPath, ensureDefaultMemoryFiles, ensureMetadataCatalogFresh, propose, proposePlan, recordCorrectionTrace, emitCorrectionEvalCase, mineJoinPatterns, reviewHint, AgentRunEngine, FileAgentRunStore, defaultAgentRunGates, createLlmAgentRunPlanner, createHybridRouter, computeResultStats, buildDeterministicDashboardStory, synthesizeAnswer, streamOrGenerate, narrateResult, normalizeAnthropicBaseUrl, buildProposePreview, buildFromPrompt, defaultAgentRunStorePath, resolveLocalOwner, resolveProposeConfig, recordQueryRun, recordRuntimeSchemaSnapshot, latestRuntimeSchemaSnapshotForProject, loadSkills, migrateLegacySkills, configuredSkillsPath, skillsDir, draftDomainSkillBootstrap, buildDomainSkillBootstrapPrompt, mergeDomainSkillBootstrapEnrichment, writeSkill, deleteSkill, deriveGeneratedDraftSlug, reindexProject, invalidateAgentProjectState, resolveDomainContextEnvelope, defaultKgPath, planAppFromPrompt, KGStore, planResearch, loadSemanticMetrics, cascadeTraceToEvidenceRouteSteps, createCascadeAnswerResult, createCascadeTrace, routeReasoningEffort, routeForCascadeAnswerTier, clampReasoningEffort, bumpReasoningEffort, resolveThinkingMode, coerceThinkingMode, probeLocalOllamaEmbeddings, upsertGeneratedDqlArtifactDraft, } from '@duckcodeailabs/dql-agent';
+import { ClaudeProvider, ConversationStore, advanceThreadState, buildConversationSnapshot, recallRelevantTurns, GeminiProvider, MemoryStore, OllamaProvider, OpenAIProvider, buildBlockBusinessFingerprint, buildBlockSqlFingerprints, buildAnalysisQuestionPlan, buildLocalContextPack, toAgentRetrievalEvidence, defaultConversationPath, defaultMemoryPath, ensureDefaultMemoryFiles, ensureAgentProjectReady, isAgentProjectIndexReady, currentMetadataFingerprint, ensureMetadataCatalogFresh, readIndexedDomainKnowledge, readIndexedKnowledge360, propose, proposePlan, recordCorrectionTrace, emitCorrectionEvalCase, mineJoinPatterns, reviewHint, AgentRunEngine, FileAgentRunStore, defaultAgentRunGates, createLlmAgentRunPlanner, createHybridRouter, computeResultStats, buildDeterministicDashboardStory, synthesizeAnswer, streamOrGenerate, narrateResult, buildProposePreview, buildFromPrompt, defaultAgentRunStorePath, resolveLocalOwner, resolveProposeConfig, recordQueryRun, recordRuntimeSchemaSnapshot, latestRuntimeSchemaSnapshotForProject, loadSkills, migrateLegacySkills, configuredSkillsPath, skillsDir, draftDomainSkillBootstrap, buildDomainSkillBootstrapPrompt, mergeDomainSkillBootstrapEnrichment, writeSkill, deleteSkill, deriveGeneratedDraftSlug, reindexProject, invalidateAgentProjectState, resolveDomainContextEnvelope, defaultKgPath, planAppFromPrompt, KGStore, planResearch, loadSemanticMetrics, cascadeTraceToEvidenceRouteSteps, createCascadeAnswerResult, createCascadeTrace, routeReasoningEffort, routeForCascadeAnswerTier, clampReasoningEffort, bumpReasoningEffort, resolveThinkingMode, coerceThinkingMode, upsertGeneratedDqlArtifactDraft, } from '@duckcodeailabs/dql-agent';
 import { gatherProposeEnrichment } from './propose-enrich.js';
 import { handleAppsApi, proposeAppAiBuild, recommendVisualization } from './apps-api.js';
 import { getActiveProvider, getEffectiveProviderConfig, isProviderSettingsId, listProviderSettings, saveProviderSettings, } from './settings/provider-settings.js';
@@ -153,6 +153,20 @@ export function parseAgentRunRequestBody(body) {
         },
     };
 }
+const AGENT_LOOKUP_DEADLINE_MS = 45_000;
+const AGENT_RESEARCH_DEADLINE_MS = 120_000;
+/**
+ * PERF-002: one wall-clock budget follows the request through routing, provider
+ * calls, repair, and execution. Ordinary Ask never inherits Research's budget
+ * merely because it spans two tables; explicit/deep investigation does.
+ */
+export function agentRunDeadlineMs(request) {
+    if (request.requestedMode === 'research' || request.analysisDepth === 'deep') {
+        return AGENT_RESEARCH_DEADLINE_MS;
+    }
+    const plan = buildAnalysisQuestionPlan(request.question);
+    return plan.needsResearchWorkspace ? AGENT_RESEARCH_DEADLINE_MS : AGENT_LOOKUP_DEADLINE_MS;
+}
 export function shouldSynthesizeAgentRunAnswer(governedAnswer) {
     if (governedAnswer.kind === 'no_answer')
         return false;
@@ -283,6 +297,7 @@ function conversationTurnInputFromRun(run) {
         sourceCertifiedBlock: agentRunString(payload?.sourceCertifiedBlock)
             ?? (artifact?.kind === 'answer' ? agentRunString(artifact.ref) : undefined),
         contextPackId: agentRunString(payload?.contextPackId) ?? agentRunString(contextPack?.id),
+        knowledgeLens: agentRunRecord(contextPack?.knowledgeLens),
         sql: agentRunString(payload?.proposedSql) ?? agentRunString(payload?.sql),
         dqlArtifact: agentRunRecord(payload?.dqlArtifact),
         cascade: agentRunRecord(payload?.cascade),
@@ -351,6 +366,21 @@ function compactConversationRecord(record) {
 function apiRequestId(scope) {
     return `${scope}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
 }
+/** UI-007 / E2E-005: report the installed CLI version that owns this runtime. */
+export function readDqlRuntimeVersion(runtimeUrl = import.meta.url) {
+    const runtimeDir = dirname(fileURLToPath(runtimeUrl));
+    for (const packagePath of [join(runtimeDir, 'package.json'), join(runtimeDir, '../package.json')]) {
+        try {
+            const parsed = JSON.parse(readFileSync(packagePath, 'utf-8'));
+            if (typeof parsed.version === 'string' && parsed.version.trim())
+                return parsed.version.trim();
+        }
+        catch {
+            // Source and published layouts place package.json at different levels.
+        }
+    }
+    return 'unknown';
+}
 function apiErrorEnvelope(input) {
     return {
         requestId: input.requestId,
@@ -377,6 +407,7 @@ export async function startLocalServer(opts) {
     const bindHost = opts.host ?? process.env.DQL_HOST ?? '127.0.0.1';
     const loopback = bindHost === '127.0.0.1' || bindHost === 'localhost' || bindHost === '::1';
     const authToken = opts.authToken ?? process.env.DQL_SERVER_TOKEN;
+    const runtimeVersion = readDqlRuntimeVersion();
     const allowedOrigins = new Set((opts.allowedOrigins ?? (process.env.DQL_ALLOWED_ORIGINS ?? '').split(','))
         .map((value) => value.trim().replace(/\/$/, ''))
         .filter(Boolean));
@@ -426,6 +457,102 @@ export async function startLocalServer(opts) {
             error: snapshot.error,
         };
     };
+    const latestDbtPreparationJob = () => Array.from(onboardingJobs.values())
+        .reverse()
+        .find((job) => job.kind === 'dbt_prepare' || job.kind === 'dbt_refresh');
+    const startDbtPreparationJob = (input) => {
+        const now = new Date().toISOString();
+        const id = apiRequestId(input.kind === 'dbt_refresh' ? 'dbt-refresh' : 'dbt-prepare');
+        const job = {
+            id,
+            kind: input.kind,
+            status: 'running',
+            stage: 'indexing',
+            progress: 65,
+            message: 'Indexing dbt models, columns, semantic metrics, certified blocks, and governed relationships.',
+            createdAt: now,
+            updatedAt: now,
+            snapshotId: input.snapshotId,
+            phases: [
+                { id: 'artifact_validation', label: 'Validated dbt project and artifacts', status: 'completed', durationMs: input.validationDurationMs },
+                { id: 'snapshot_compile', label: 'Compiled immutable project snapshot', status: 'completed', durationMs: input.compileDurationMs },
+                { id: 'search_index', label: 'Build governed search indexes', status: 'running' },
+            ],
+        };
+        if (onboardingJobs.size >= 24) {
+            for (const [existingId, existing] of onboardingJobs) {
+                if (existing.status === 'running' || existing.status === 'queued')
+                    continue;
+                onboardingJobs.delete(existingId);
+                if (onboardingJobs.size < 16)
+                    break;
+            }
+        }
+        onboardingJobs.set(id, job);
+        // Start after the Apply response can be returned. Governed Ask calls the
+        // same versioned preparation service, so an early first question awaits
+        // this in-flight promise instead of starting a duplicate cold rebuild.
+        setTimeout(() => {
+            void (async () => {
+                const indexStartedAt = Date.now();
+                try {
+                    const prepared = await ensureAgentProjectReady(projectRoot, {
+                        kgPath: defaultKgPath(projectRoot),
+                        manifest: input.manifest,
+                    });
+                    const current = onboardingJobs.get(id);
+                    if (!current || current.status === 'cancelled')
+                        return;
+                    const indexDurationMs = Date.now() - indexStartedAt;
+                    const completedAt = new Date().toISOString();
+                    onboardingJobs.set(id, {
+                        ...current,
+                        status: 'completed',
+                        stage: 'ready',
+                        progress: 100,
+                        message: `Ready. Indexed ${prepared.nodes.toLocaleString()} governed objects for fast search.`,
+                        updatedAt: completedAt,
+                        phases: current.phases.map((phase) => phase.id === 'search_index'
+                            ? { ...phase, status: 'completed', durationMs: indexDurationMs }
+                            : phase),
+                        result: {
+                            snapshotId: input.snapshotId,
+                            cacheHit: prepared.cacheHit,
+                            sourceVersion: prepared.sourceVersion,
+                            objectCount: prepared.nodes,
+                            edgeCount: prepared.edges,
+                            metadataFingerprint: prepared.metadataFingerprint,
+                            kgFingerprint: prepared.kgFingerprint,
+                            phaseDurationsMs: {
+                                artifactValidation: input.validationDurationMs,
+                                snapshotCompile: input.compileDurationMs,
+                                searchIndex: indexDurationMs,
+                                total: input.validationDurationMs + input.compileDurationMs + indexDurationMs,
+                            },
+                            completedAt,
+                        },
+                    });
+                }
+                catch (error) {
+                    const current = onboardingJobs.get(id);
+                    if (!current || current.status === 'cancelled')
+                        return;
+                    onboardingJobs.set(id, {
+                        ...current,
+                        status: 'failed',
+                        progress: 65,
+                        message: 'The dbt project is connected, but its governed search indexes need attention.',
+                        updatedAt: new Date().toISOString(),
+                        phases: current.phases.map((phase) => phase.id === 'search_index'
+                            ? { ...phase, status: 'failed', durationMs: Date.now() - indexStartedAt }
+                            : phase),
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            })();
+        }, 0);
+        return job;
+    };
     const onboardingDbtPaths = (body = {}) => {
         const repoUrl = typeof body.repoUrl === 'string' && body.repoUrl.trim() ? body.repoUrl.trim() : undefined;
         const branch = typeof body.branch === 'string' && body.branch.trim() ? body.branch.trim() : undefined;
@@ -522,28 +649,6 @@ export async function startLocalServer(opts) {
         }
         return candidate;
     };
-    // Zero-config semantic search: if the user is running Ollama with an embedding model
-    // but hasn't set an embed env var, auto-detect it so retrieval + metric/block matching
-    // get real semantic recall out of the box (match by meaning, not just keywords) — the
-    // biggest lever for "find the right metric/block instead of jumping to raw SQL".
-    // Explicit config always wins; when nothing is found we stay on the deterministic
-    // keyword matcher. Scoped to the app server (not eval/CI) and fully best-effort.
-    if (!process.env.DQL_OLLAMA_EMBED_URL && !process.env.DQL_OPENAI_API_KEY && !process.env.OPENAI_API_KEY) {
-        try {
-            const detected = await probeLocalOllamaEmbeddings();
-            if (detected) {
-                process.env.DQL_OLLAMA_EMBED_URL = detected.endpoint;
-                process.env.DQL_OLLAMA_EMBED_MODEL = detected.model;
-                console.log(`[dql] Semantic search on: local Ollama embeddings (${detected.model}) — matching by meaning, not just keywords.`);
-            }
-            else {
-                console.log('[dql] Semantic search: keyword-only. For higher matching accuracy, install Ollama and run `ollama pull nomic-embed-text` — DQL detects and uses it automatically, fully local & free.');
-            }
-        }
-        catch {
-            // Probe failure never blocks startup — fall back to the keyword matcher.
-        }
-    }
     // Auto-ensure the active connection's driver so a configured connection is never
     // left "broken" after a fresh clone, a CLI upgrade, or a Node version change (the
     // driver lives in gitignored, per-project .dql/connectors). Best-effort + non-fatal.
@@ -679,6 +784,15 @@ export async function startLocalServer(opts) {
         const nested = agentRunRecord(workspace.context);
         return agentRunString(workspace[key]) ?? (nested ? agentRunString(nested[key]) : undefined);
     };
+    const agentRunWorkspaceValues = (request, key) => {
+        const workspace = request.workspaceContext ?? {};
+        const nested = agentRunRecord(workspace.context);
+        const raw = workspace[key] ?? nested?.[key];
+        if (!Array.isArray(raw))
+            return undefined;
+        const values = raw.filter((item) => typeof item === 'string' && Boolean(item.trim())).map((item) => item.trim());
+        return values.length > 0 ? [...new Set(values)] : undefined;
+    };
     const agentRunNotebookPath = (request, runId) => (agentRunWorkspaceValue(request, 'notebookPath')
         ?? (request.selectedObject?.kind === 'notebook' || request.selectedObject?.kind === 'cell' ? request.selectedObject.path : undefined)
         ?? `notebooks/agent-research/${runId}.dqlnb`);
@@ -860,7 +974,7 @@ export async function startLocalServer(opts) {
             return provider.generate([{ role: 'system', content: system }, { role: 'user', content: user }], { maxTokens: 600, temperature: 0.2, signal });
         },
     });
-    async function runGovernedAgentAnswerForRun(request, repair, route = 'generated_answer', onProgress) {
+    async function runGovernedAgentAnswerForRun(request, repair, route = 'generated_answer', onProgress, routeDecision) {
         const governed = resolveGovernedAnswerRunner(projectRoot);
         const resolvedProvider = governed?.provider ?? null;
         const runner = governed?.runner ?? null;
@@ -886,6 +1000,9 @@ export async function startLocalServer(opts) {
             workspaceContext: request.workspaceContext,
             instruction: [
                 'Route through the governed DQL answer loop.',
+                ...(routeDecision?.meaningResolution?.selectedConceptIds.length
+                    ? [`Meaning resolution selected these retrieved qualified IDs: ${routeDecision.meaningResolution.selectedConceptIds.join(', ')}. Treat them as strong evidence, but still validate grain, dimensions, filters, authorization, and runtime compatibility before execution.`]
+                    : []),
                 'Prefer certified DQL blocks when they exactly cover the question.',
                 '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.',
@@ -898,6 +1015,9 @@ export async function startLocalServer(opts) {
         const controller = request.runId
             ? activeAgentRunControllers.get(request.runId) ?? new AbortController()
             : new AbortController();
+        const runSignal = request.signal
+            ? AbortSignal.any([request.signal, controller.signal])
+            : controller.signal;
         // 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.
@@ -918,6 +1038,7 @@ export async function startLocalServer(opts) {
                 activeDomain: requestedDomain,
                 purpose: requestedPurpose,
                 modelAreaId: requestedModelAreaId,
+                skillRefs: agentRunWorkspaceValues(request, 'skillRefs'),
                 source: 'explicit_ui',
                 snapshotId: runProjectSnapshot.snapshotId,
             })
@@ -939,6 +1060,7 @@ export async function startLocalServer(opts) {
             reasoningEffort,
             ...(analysisDepth ? { analysisDepth } : {}),
             projectRoot,
+            preparedContextPack: preparedAgentContextPacks.get(request),
             domainContext,
             projectSnapshot: { snapshotId: runProjectSnapshot.snapshotId, manifest: runProjectSnapshot.manifest },
             assertProjectSnapshot: (snapshotId) => {
@@ -947,6 +1069,12 @@ export async function startLocalServer(opts) {
                 projectSnapshots.assertCurrent(snapshotId);
             },
             ...(semanticDriver ? { semanticDriver } : {}),
+            ...(routeDecision?.meaningResolution?.selectedConceptIds.length
+                ? { preferredEvidenceIds: routeDecision.meaningResolution.selectedConceptIds }
+                : {}),
+            ...(routeDecision?.meaningResolution?.recommendedExecutionId
+                ? { preferredExecutionId: routeDecision.meaningResolution.recommendedExecutionId }
+                : {}),
             executeCertifiedBlock: executeCertifiedBlockForAgent,
             executeGeneratedSql: executeGeneratedSqlForAgent,
             getSchemaContext: getSchemaContextForAgent,
@@ -959,7 +1087,7 @@ export async function startLocalServer(opts) {
             if (turn.kind === 'error') {
                 providerError = turn.message;
             }
-        }, controller.signal);
+        }, runSignal);
         if (!governedAnswer) {
             throw new Error(providerError ?? 'The AI provider did not return a governed answer.');
         }
@@ -1001,9 +1129,11 @@ export async function startLocalServer(opts) {
             return;
         const existing = agentRunRecord(result.chartConfig) ?? {};
         // A declared chart on the execution result came from authored DQL and is a
-        // governed display contract. Agent `suggestedViz` remains a soft preference.
-        if (typeof existing.chart === 'string')
-            return;
+        // governed display contract. Preserve its type/bindings, but still enrich a
+        // missing display format from the result semantics; otherwise an authored
+        // KPI for `lifetime_spend` renders as a generic `671.4K` instead of `$671.4K`.
+        // Agent `suggestedViz` remains a soft preference when no chart was authored.
+        const hasAuthoredChart = typeof existing.chart === 'string';
         const recommendation = recommendVisualization(projectRoot, {
             blockRef: governedAnswer.sourceCertifiedBlock ?? governedAnswer.block?.name,
             prompt: question,
@@ -1014,17 +1144,26 @@ export async function startLocalServer(opts) {
         if (!recommendation.ok)
             return;
         const fieldHints = recommendation.display.fieldHints ?? {};
-        const chart = recommendation.display.defaultVisualization.replace(/_/g, '-');
+        const chart = hasAuthoredChart
+            ? String(existing.chart).replace(/_/g, '-')
+            : recommendation.display.defaultVisualization.replace(/_/g, '-');
         const agentChoice = typeof governedAnswer.suggestedViz === 'string'
             ? governedAnswer.suggestedViz.toLowerCase().replace(/_/g, '-')
             : undefined;
         result.chartConfig = {
             ...existing,
             chart,
-            decisionSource: agentChoice === chart ? 'agent' : 'data',
-            rationale: recommendation.display.rationale,
-            ...(typeof fieldHints.x === 'string' ? { x: fieldHints.x } : {}),
-            ...(typeof fieldHints.y === 'string' ? { y: fieldHints.y } : {}),
+            decisionSource: hasAuthoredChart ? 'authored' : agentChoice === chart ? 'agent' : 'data',
+            rationale: hasAuthoredChart
+                ? agentRunString(existing.rationale) ?? 'Authored DQL visualization enriched with result-aware display semantics.'
+                : recommendation.display.rationale,
+            ...(typeof existing.x !== 'string' && typeof fieldHints.x === 'string' ? { x: fieldHints.x } : {}),
+            ...(typeof existing.y !== 'string' && typeof fieldHints.y === 'string' ? { y: fieldHints.y } : {}),
+            ...(typeof existing.color !== 'string' && typeof fieldHints.color === 'string' ? { color: fieldHints.color } : {}),
+            ...(typeof existing.format !== 'string'
+                && (fieldHints.format === 'currency' || fieldHints.format === 'percent' || fieldHints.format === 'number')
+                ? { format: fieldHints.format }
+                : {}),
         };
         governedAnswer.suggestedViz = chart;
         const evidence = governedAnswer.evidence ?? {
@@ -1114,7 +1253,7 @@ export async function startLocalServer(opts) {
     const answerRunExecutor = async ({ request, route, routeDecision, attempt, repairHint, emit }) => {
         let governedAnswer;
         try {
-            governedAnswer = await runGovernedAgentAnswerForRun(request, { attempt, repairHint }, route, (message) => emit({ type: 'executor.started', message, route }));
+            governedAnswer = await runGovernedAgentAnswerForRun(request, { attempt, repairHint }, route, (message) => emit({ type: 'executor.started', message, route }), routeDecision);
             // Surface the approved Hint-Graph corrections that shaped this answer so the
             // UI can show an "applied learnings" chip (memoryContext is already on the answer).
             if (!governedAnswer.appliedHints) {
@@ -1278,49 +1417,49 @@ export async function startLocalServer(opts) {
         // more provider calls retrying the same incompatible candidate.
         const isPolicyBlocked = governedAnswer.kind === 'no_answer' && governedAnswer.refusalCode === 'policy_blocked';
         // The model tried to compose a governed query and declined despite having usable
-        // context (e.g. it wasn't confident about a multi-table join). That is NOT a
-        // question for the USER to clarify — it's a case to retry harder: escalate to a
-        // deeper research pass (higher reasoning effort + deep analysis) through the
-        // engine's bounded loop, exactly as a grounding gap is retried today.
+        // context (e.g. it wasn't confident about a multi-table join). The answer loop
+        // has already spent its one evidence-aware repair. Keep this terminal and
+        // inspectable; an ordinary Ask must never silently become a second Research run.
         const isModelDeclined = governedAnswer.kind === 'no_answer' && governedAnswer.refusalCode === 'model_declined';
-        const groundingRepairHint = isGroundingGap ? groundingGapRepairHint(governedAnswer) : undefined;
-        const declinedRepairHint = isModelDeclined
-            ? 'The first attempt declined to compose a governed query despite available context. Investigate the join path across the requested entities/metrics and compose a review-required query rather than declining.'
-            : undefined;
-        // Only a genuinely AMBIGUOUS question is surfaced as "needs clarification". A
-        // grounding gap or a model decline is retried/escalated by the engine, and a
-        // provider outage is surfaced as blocked so the UI offers a retry.
+        // Only a genuinely AMBIGUOUS question is surfaced as "needs clarification".
+        // Grounding/compiler gaps are terminal review states with their evidence trace;
+        // provider outages are blocked so the UI can offer an explicit retry.
         const needsClarification = governedAnswer.kind === 'no_answer'
             && !isGroundingGap && !isProviderError && !isModelDeclined && !isPolicyBlocked;
         const sql = governedAnswer.proposedSql ?? governedAnswer.sql;
         const runnableSql = governedAnswer.kind === 'no_answer' || (isExploratory && !governedAnswer.result)
             ? 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.
+        // Render executed rows deterministically for ordinary lookups. A second LLM
+        // call is reserved for an explicit research route; certified, semantic, and
+        // generated lookup answers must not pay another provider round-trip merely
+        // to restate values the host already has.
         let synthesizedAnswer;
         if (shouldSynthesizeAgentRunAnswer(governedAnswer)) {
             try {
-                const provider = await createBlockStudioAssistProvider(projectRoot);
-                if (provider) {
-                    const preview = agentResultToSynthesisPreview(governedAnswer.result);
-                    const draft = governedAnswer.answer ?? governedAnswer.text;
-                    const result = await synthesizeAnswer({
-                        question: request.question,
-                        category: routeDecision?.category,
-                        // The primary Ask reply is always business-facing. Analysts keep
-                        // the full DQL, SQL, lineage, gates, and grain in the inspector.
-                        audience: 'stakeholder',
-                        resultPreview: preview,
-                        sql: sql,
-                        draftText: draft,
-                        gaps: businessNarrativeGaps(governedAnswer.validationWarnings),
-                    }, {
+                const provider = route === 'research'
+                    ? await createBlockStudioAssistProvider(projectRoot)
+                    : null;
+                const preview = agentResultToSynthesisPreview(governedAnswer.result);
+                const draft = governedAnswer.answer ?? governedAnswer.text;
+                const result = await synthesizeAnswer({
+                    question: request.question,
+                    category: routeDecision?.category,
+                    // The primary Ask reply is always business-facing. Analysts keep
+                    // the full DQL, SQL, lineage, gates, and grain in the inspector.
+                    audience: 'stakeholder',
+                    resultPreview: preview,
+                    sql: sql,
+                    draftText: draft,
+                    gaps: businessNarrativeGaps(governedAnswer.validationWarnings),
+                    rankingDirection: governedAnswer.contextPack?.questionPlan.requestedShape.rankingDirection,
+                }, provider
+                    ? {
                         complete: ({ system, user, signal, onDelta }) => streamOrGenerate(provider, [{ role: 'system', content: system }, { role: 'user', content: user }], { maxTokens: 350, temperature: 0.3, signal }, onDelta ?? (() => { })),
-                    });
-                    if (result.text)
-                        synthesizedAnswer = result.text;
-                }
+                    }
+                    : {});
+                if (result.text)
+                    synthesizedAnswer = result.text;
             }
             catch {
                 // Keep the governed draft on any synthesis failure.
@@ -1411,26 +1550,22 @@ export async function startLocalServer(opts) {
                                     : '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.', {
+                        ...agentRunEvaluation('grounding-gap', 'Metadata grounding', false, 'warning', 'The bounded lookup could not prove the required metadata grounding. No automatic retry or Research escalation was started.', {
                             refusalCode: governedAnswer.refusalCode,
                             refusalDetails: governedAnswer.refusalDetails,
                             validationWarnings: governedAnswer.validationWarnings,
                             route: governedAnswer.route,
                         }),
-                        suggestedRepair: groundingRepairHint,
-                        repairAction: { kind: 'retry', hint: groundingRepairHint },
                     },
                 ] : []),
                 ...(isModelDeclined ? [
                     {
-                        ...agentRunEvaluation('declined-despite-context', 'Answer grounding', false, 'blocking', 'The model declined to compose a governed query despite available context — escalating to a deeper investigation before accepting a refusal.', {
+                        ...agentRunEvaluation('declined-despite-context', 'Answer grounding', false, 'blocking', 'The bounded lookup could not compose a governed query after its in-lane repair. Start Research explicitly to investigate beyond this lookup budget.', {
                             refusalCode: governedAnswer.refusalCode,
                             refusalDetails: governedAnswer.refusalDetails,
                             validationWarnings: governedAnswer.validationWarnings,
                             route: governedAnswer.route,
                         }),
-                        suggestedRepair: declinedRepairHint,
-                        repairAction: { kind: 'escalate', route: 'research', hint: declinedRepairHint },
                     },
                 ] : []),
                 ...(isPolicyBlocked ? [
@@ -1968,7 +2103,138 @@ export async function startLocalServer(opts) {
             };
         },
     };
-    // Compact, catalog-grounded context the LLM planner decomposes `auto` turns against.
+    // One immutable, question-ranked pack is shared by routing, planning, schema
+    // lookup, and governed execution for the lifetime of a request. This removes
+    // both positional catalog truncation and the previous duplicate retrieval pass.
+    const preparedAgentContextPacks = new WeakMap();
+    const pendingAgentContextPacks = new WeakMap();
+    const buildAgentRunContextPack = async (request) => {
+        const prepared = preparedAgentContextPacks.get(request);
+        if (prepared)
+            return prepared;
+        const pending = pendingAgentContextPacks.get(request);
+        if (pending)
+            return pending;
+        const snapshot = projectSnapshot();
+        const requestedDomain = agentRunWorkspaceValue(request, 'domain');
+        // CTX-003: resolve result entities/values before evidence retrieval. The
+        // router, planner, and answer loop must rank the same typed follow-up; doing
+        // this only inside the provider adapter allowed stale catalog matches to win
+        // before "they" / "this amount" became customer-scoped context.
+        const followUp = resolveAgentFollowUpContext(request.conversationContext, request.question);
+        const serverSnapshot = agentRunRecord(request.conversationContext?.serverSnapshot);
+        const topicRelation = agentRunString(serverSnapshot?.topicRelation);
+        // The readiness marker is source-versioned. When it matches, pass the
+        // already-built metadata identity into retrieval so buildLocalContextPack
+        // opens the immutable snapshot directly instead of rebuilding all metadata
+        // merely to rediscover the same fingerprint on every follow-up.
+        const preparedMetadataFingerprint = isAgentProjectIndexReady(projectRoot)
+            ? currentMetadataFingerprint(projectRoot)
+            : undefined;
+        const task = buildLocalContextPack(projectRoot, {
+            question: request.question,
+            followUp,
+            priorContextPackId: agentRunString(request.conversationContext?.contextPackId),
+            conversationTopicRelation: topicRelation === 'continuation'
+                || topicRelation === 'refinement'
+                || topicRelation === 'return'
+                || topicRelation === 'shift'
+                ? topicRelation
+                : undefined,
+            preparedMetadataFingerprint,
+            surface: 'notebook',
+            selectedContext: {
+                selectedObject: request.selectedObject,
+                workspaceContext: request.workspaceContext,
+            },
+            strictness: request.analysisDepth === 'deep' ? 'exploratory' : 'balanced',
+            limit: request.analysisDepth === 'deep' ? 120 : 80,
+            domainContext: requestedDomain
+                ? resolveDomainContextEnvelope({
+                    manifest: snapshot.manifest,
+                    activeDomain: requestedDomain,
+                    purpose: agentRunWorkspaceValue(request, 'purpose'),
+                    modelAreaId: agentRunWorkspaceValue(request, 'modelAreaId'),
+                    skillRefs: agentRunWorkspaceValues(request, 'skillRefs'),
+                    source: 'explicit_ui',
+                    snapshotId: snapshot.snapshotId,
+                })
+                : undefined,
+        }).then((pack) => {
+            preparedAgentContextPacks.set(request, pack);
+            pendingAgentContextPacks.delete(request);
+            return pack;
+        }).catch((error) => {
+            pendingAgentContextPacks.delete(request);
+            throw error;
+        });
+        pendingAgentContextPacks.set(request, task);
+        return task;
+    };
+    const buildAgentRunEvidence = async (request) => {
+        const startedAt = Date.now();
+        const pack = await buildAgentRunContextPack(request);
+        const meaningEvidence = pack.retrievalDiagnostics.meaningEvidence;
+        if (!meaningEvidence) {
+            return {
+                snapshotId: pack.id,
+                sourceFingerprint: pack.freshness.fingerprint ?? undefined,
+                candidates: [],
+                diagnostics: { durationMs: Date.now() - startedAt },
+            };
+        }
+        const evidence = toAgentRetrievalEvidence(meaningEvidence, pack.questionPlan, {
+            snapshotId: pack.id,
+            sourceFingerprint: pack.freshness.fingerprint ?? undefined,
+            durationMs: Date.now() - startedAt,
+            truncated: pack.retrievalDiagnostics.topRejected.length > 0,
+        });
+        const certifiedFits = new Map(pack.retrievalDiagnostics.certifiedCandidateFits.map((fit) => [fit.objectKey, fit]));
+        const semanticEvidence = new Set(pack.routeDecision.selectedEvidence
+            .filter((item) => item.role === 'semantic_metric')
+            .map((item) => item.objectKey));
+        return {
+            ...evidence,
+            candidates: evidence.candidates.map((candidate) => {
+                if (candidate.kind === 'certified_block') {
+                    const fit = certifiedFits.get(candidate.id);
+                    return {
+                        ...candidate,
+                        compatibility: fit?.action === 'certified_answer'
+                            ? 'compatible'
+                            : fit?.action === 'rejected_for_fit'
+                                ? 'incompatible'
+                                : 'partial',
+                    };
+                }
+                if ((candidate.kind === 'semantic_metric' || candidate.kind === 'semantic_member')
+                    && semanticEvidence.has(candidate.id)
+                    && pack.routeDecision.route !== 'clarify'
+                    && pack.routeDecision.route !== 'conflict') {
+                    const requestedDimensions = pack.questionPlan.requestedShape.dimensions.map((dimension) => dimension.toLowerCase());
+                    const availableDimensions = (candidate.dimensions ?? []).map((dimension) => dimension.toLowerCase());
+                    const dimensionsFit = requestedDimensions.length === 0 || requestedDimensions.every((requested) => availableDimensions.some((available) => available === requested || available.endsWith(`.${requested}`)));
+                    const requestedTimeGrain = pack.questionPlan.timeTerms[0]?.toLowerCase();
+                    const availableTimeGrains = (candidate.timeGrains ?? []).map((grain) => grain.toLowerCase());
+                    const timeGrainFits = !requestedTimeGrain
+                        || availableTimeGrains.includes(requestedTimeGrain);
+                    return { ...candidate, compatibility: dimensionsFit && timeGrainFits ? 'compatible' : 'partial' };
+                }
+                if (candidate.trustTier === 'governed_sql')
+                    return { ...candidate, compatibility: 'partial' };
+                return candidate;
+            }),
+        };
+    };
+    const buildRankedAgentRunCatalogContext = async (request) => {
+        const evidence = await buildAgentRunEvidence(request);
+        return evidence.candidates.map((candidate) => {
+            const detail = candidate.definition ? `: ${candidate.definition}` : '';
+            return `- ${candidate.id} [${candidate.trustTier}; ${candidate.compatibility}]${detail}`;
+        }).join('\n');
+    };
+    // Compact fallback used only for plain conversational replies. Analytical
+    // turns use the structured, question-ranked evidence path above.
     const buildAgentRunCatalogContext = () => {
         try {
             const blocks = collectPlanBlocks(projectRoot, { certifiedOnly: true });
@@ -2004,7 +2270,7 @@ export async function startLocalServer(opts) {
                 { role: 'user', content: user },
             ], { maxTokens: 700, temperature: 0.1, signal });
         },
-        getCatalogContext: buildAgentRunCatalogContext,
+        getCatalogContext: buildRankedAgentRunCatalogContext,
     });
     // Hybrid router: keep the deterministic decision when it is confident (certified
     // fast paths + greetings stay 0-LLM); spend one cheap classification call only for
@@ -2014,13 +2280,22 @@ export async function startLocalServer(opts) {
         complete: async ({ system, user, signal }) => {
             const provider = await createBlockStudioAssistProvider(projectRoot);
             if (!provider)
-                throw new Error('No AI provider configured for routing.');
+                throw new Error('No AI provider configured for meaning resolution.');
             return provider.generate([
                 { role: 'system', content: system },
                 { role: 'user', content: user },
-            ], { maxTokens: 250, temperature: 0, signal });
+            ], {
+                maxTokens: 600,
+                temperature: 0,
+                // AGT-009/PERF-002: ambiguity gets one bounded resolver call. If the
+                // provider stalls, the router falls back to its evidence-only decision
+                // instead of leaving the UI in "Generating and validating SQL" for a
+                // minute or more.
+                signal: boundedAgentMeaningSignal(signal),
+            });
         },
-        getCatalogContext: () => buildAgentRunCatalogContext(),
+        getEvidence: buildAgentRunEvidence,
+        getCatalogContext: buildRankedAgentRunCatalogContext,
     });
     const agentRunStore = new FileAgentRunStore({ path: defaultAgentRunStorePath(projectRoot) });
     // A run may outlive its streaming browser connection, so cancellation is
@@ -2303,30 +2578,24 @@ export async function startLocalServer(opts) {
             };
         };
         const catalogContext = await buildAgentSchemaContextFromCatalog(projectRoot, question, preparedContextPack).catch(() => []);
+        const valueGrounding = resolveAgentRuntimeValueGrounding(projectConfig);
         if (catalogContext.length > 0) {
-            if (!connection)
+            if (!connection || valueGrounding.mode !== 'safe_automatic')
                 return catalogContext;
-            // Rescan live when the question shape calls for it OR the stored snapshot is
-            // stale/absent (P6) — otherwise a warehouse schema change between sessions is
-            // silently reasoned over from a cached snapshot that never expires.
-            const runtimeScan = (shouldAugmentAgentRuntimeSchema(question, preparedContextPack?.questionPlan) || runtimeSnapshotStale(projectRoot))
-                ? 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');
+            // The immutable dbt/DQL snapshot already owns schema discovery. A named
+            // row value must not turn a warm Ask into an information_schema scan over
+            // thousands of enterprise tables; only field-scoped value probes are live.
+            const enriched = await enrichAgentSchemaContextWithValueMatches(question, catalogContext, executor, connection, valueGrounding.searchSafeColumns);
+            recordAgentRuntimeSchemaSnapshot(projectRoot, catalogContext, 'catalog runtime schema');
             return enriched;
         }
         if (!connection)
             return [];
         try {
             const schemaContext = await scanRuntimeSchema();
-            const enriched = await enrichAgentSchemaContextWithValueMatches(question, schemaContext.ranked, executor, connection);
+            const enriched = valueGrounding.mode === 'safe_automatic'
+                ? await enrichAgentSchemaContextWithValueMatches(question, schemaContext.ranked, executor, connection, valueGrounding.searchSafeColumns)
+                : schemaContext.ranked;
             recordAgentRuntimeSchemaSnapshot(projectRoot, schemaContext.snapshot, 'full information_schema runtime scan');
             return enriched;
         }
@@ -3409,13 +3678,42 @@ export async function startLocalServer(opts) {
         }
         if (req.method === 'GET' && path === '/api/health') {
             res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
-            res.end(serializeJSON({ status: 'ok' }));
+            res.end(serializeJSON({ status: 'ok', version: runtimeVersion }));
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/onboarding/launch') {
+            const requestId = apiRequestId('onboarding-launch');
+            const acknowledgedVersion = readUserPrefs(userPrefsPath).setup?.acknowledgedVersion ?? null;
+            const shouldOpen = acknowledgedVersion !== runtimeVersion;
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({
+                requestId,
+                version: runtimeVersion,
+                acknowledgedVersion,
+                shouldOpen,
+                reason: shouldOpen ? (acknowledgedVersion ? 'version_upgrade' : 'first_install') : null,
+            }));
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/onboarding/acknowledge') {
+            const requestId = apiRequestId('onboarding-acknowledge');
+            const prefs = readUserPrefs(userPrefsPath);
+            prefs.setup = {
+                acknowledgedVersion: runtimeVersion,
+                acknowledgedAt: new Date().toISOString(),
+            };
+            writeUserPrefs(userPrefsPath, prefs);
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({ requestId, version: runtimeVersion, acknowledged: true }));
             return;
         }
         if (req.method === 'GET' && path === '/api/onboarding/status') {
             const requestId = apiRequestId('onboarding-status');
             const dbtProjectDir = findDbtProjectPath(projectRoot, projectConfig);
             const manifestPath = resolve(dbtProjectDir, projectConfig.dbt?.manifestPath ?? 'target/manifest.json');
+            const configuredDbtSource = projectConfig.dbt?.repoUrl ?? projectConfig.dbt?.projectDir;
+            const dbtConfigured = existsSync(join(dbtProjectDir, 'dbt_project.yml'))
+                || Boolean(configuredDbtSource && !/\{\{[^}]+\}\}/.test(configuredDbtSource));
             const configuredProfilesDir = projectConfig.dbt?.profilesDir ? resolve(projectRoot, projectConfig.dbt.profilesDir) : undefined;
             const profilePath = findDbtProfilePaths(projectRoot, dbtProjectDir, configuredProfilesDir)[0];
             const registry = loadDomainPackageRegistry(projectRoot);
@@ -3430,12 +3728,24 @@ export async function startLocalServer(opts) {
                     snapshotError = error instanceof Error ? error.message : String(error);
                 }
             }
+            const preparation = latestDbtPreparationJob();
+            const preparationForSnapshot = preparation?.snapshotId === snapshotId ? preparation : undefined;
+            const searchIndexesPresent = isAgentProjectIndexReady(projectRoot);
+            const snapshotState = preparationForSnapshot?.status === 'running' || preparationForSnapshot?.status === 'queued'
+                ? 'building'
+                : preparationForSnapshot?.status === 'failed'
+                    ? 'failed'
+                    : snapshotId && searchIndexesPresent
+                        ? 'ready'
+                        : snapshotId
+                            ? 'stale'
+                            : 'missing';
             res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
             res.end(serializeJSON({
                 requestId,
                 snapshotId,
                 dbt: {
-                    configured: Boolean(projectConfig.dbt),
+                    configured: dbtConfigured,
                     projectDir: projectConfig.dbt?.projectDir,
                     manifestPath: projectConfig.dbt?.manifestPath,
                     profilesDir: configuredProfilesDir
@@ -3446,14 +3756,27 @@ export async function startLocalServer(opts) {
                     subPath: projectConfig.dbt?.subPath,
                     projectFound: existsSync(join(dbtProjectDir, 'dbt_project.yml')),
                     manifestFound,
+                    artifactState: manifestFound ? 'ready' : 'missing',
                 },
                 modeling: {
                     enabled: projectConfig.manifestVersion === 3 && projectConfig.modeling?.mode === 'dbt-first',
                     manifestVersion: projectConfig.manifestVersion ?? 2,
                     mode: projectConfig.modeling?.mode,
+                    snapshotState,
                 },
                 domains: { count: registry.values().length, diagnostics: registry.diagnostics },
                 snapshot: { id: snapshotId, error: snapshotError },
+                preparation,
+                readiness: {
+                    project: {
+                        state: snapshotState === 'ready' ? 'ready' : snapshotState === 'building' ? 'preparing' : snapshotState === 'failed' ? 'failed' : dbtConfigured ? 'configured' : 'missing',
+                        message: preparationForSnapshot?.message ?? (snapshotState === 'ready'
+                            ? 'dbt metadata and governed search indexes are ready.'
+                            : snapshotState === 'stale'
+                                ? 'dbt metadata is configured; search indexes will be refreshed before governed Ask.'
+                                : undefined),
+                    },
+                },
                 capabilities: {
                     warehouse: Boolean(connection),
                     ai: Boolean(process.env.OPENAI_API_KEY || process.env.ANTHROPIC_API_KEY || process.env.GEMINI_API_KEY || process.env.OLLAMA_BASE_URL),
@@ -3478,6 +3801,7 @@ export async function startLocalServer(opts) {
         if (req.method === 'POST' && path === '/api/onboarding/dbt/apply') {
             const requestId = apiRequestId('onboarding-dbt-apply');
             try {
+                const applyStartedAt = Date.now();
                 const body = await readJSON(req);
                 let preview;
                 try {
@@ -3513,6 +3837,7 @@ export async function startLocalServer(opts) {
                     res.end(serializeJSON(apiErrorEnvelope({ requestId, code: 'SOURCE_CHANGED', message: 'dbt artifacts changed after preview. Review the refreshed preview before applying.', nextActions: ['Refresh the preview and review the new diff.'] })));
                     return;
                 }
+                const validationDurationMs = Date.now() - applyStartedAt;
                 const nextConfig = {
                     ...projectConfig,
                     manifestVersion: 3,
@@ -3538,8 +3863,12 @@ export async function startLocalServer(opts) {
                 projectSnapshots.invalidate();
                 invalidateAgentProjectState(projectRoot);
                 let snapshotId;
+                let snapshotManifest;
+                const compileStartedAt = Date.now();
                 try {
-                    snapshotId = projectSnapshot().snapshotId;
+                    const snapshot = projectSnapshot();
+                    snapshotId = snapshot.snapshotId;
+                    snapshotManifest = snapshot.manifest;
                 }
                 catch (error) {
                     const rollbackPath = `${configPath}.rollback-${process.pid}`;
@@ -3551,8 +3880,22 @@ export async function startLocalServer(opts) {
                     invalidateAgentProjectState(projectRoot);
                     throw Object.assign(new Error(`dbt-first configuration did not compile and was rolled back: ${error instanceof Error ? error.message : String(error)}`), { code: 'SNAPSHOT_BUILD_FAILED' });
                 }
+                const preparation = startDbtPreparationJob({
+                    kind: 'dbt_prepare',
+                    snapshotId,
+                    manifest: snapshotManifest,
+                    validationDurationMs,
+                    compileDurationMs: Date.now() - compileStartedAt,
+                });
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
-                res.end(serializeJSON({ requestId, snapshotId, applied: true, config: { manifestVersion: 3, modeling: nextConfig.modeling, dbt: nextConfig.dbt }, fingerprint: preview.fingerprint }));
+                res.end(serializeJSON({
+                    requestId,
+                    applied: true,
+                    config: { manifestVersion: 3, modeling: nextConfig.modeling, dbt: nextConfig.dbt },
+                    fingerprint: preview.fingerprint,
+                    jobId: preparation.id,
+                    ...preparation,
+                }));
             }
             catch (error) {
                 const code = typeof error === 'object' && error && 'code' in error ? String(error.code) : 'DBT_ARTIFACT_INVALID';
@@ -3563,7 +3906,7 @@ export async function startLocalServer(opts) {
         }
         if (req.method === 'POST' && path === '/api/onboarding/refresh') {
             const requestId = apiRequestId('onboarding-refresh');
-            const id = `dbt-refresh-${Date.now().toString(36)}`;
+            const refreshStartedAt = Date.now();
             try {
                 const body = await readJSON(req);
                 const currentArtifact = previewDbtOnboarding({});
@@ -3572,20 +3915,24 @@ export async function startLocalServer(opts) {
                     res.end(serializeJSON(apiErrorEnvelope({ requestId, code: 'SOURCE_CHANGED', message: 'dbt artifacts changed before refresh. Review the current artifact preview.', nextActions: ['Return to the dbt preview step and review the refreshed fingerprint.'] })));
                     return;
                 }
+                const validationDurationMs = Date.now() - refreshStartedAt;
+                const compileStartedAt = Date.now();
                 projectSnapshots.invalidate();
                 const snapshot = projectSnapshot();
                 invalidateAgentProjectState(projectRoot);
-                await reindexProject(projectRoot, { manifest: snapshot.manifest, kgPath: defaultKgPath(projectRoot) });
-                const job = { id, kind: 'dbt_refresh', status: 'completed', createdAt: new Date().toISOString(), result: { snapshotId: snapshot.snapshotId, diagnostics: snapshot.manifest.diagnostics ?? [] } };
-                onboardingJobs.set(id, job);
+                const job = startDbtPreparationJob({
+                    kind: 'dbt_refresh',
+                    snapshotId: snapshot.snapshotId,
+                    manifest: snapshot.manifest,
+                    validationDurationMs,
+                    compileDurationMs: Date.now() - compileStartedAt,
+                });
                 res.writeHead(202, { 'Content-Type': 'application/json; charset=utf-8' });
-                res.end(serializeJSON({ requestId, snapshotId: snapshot.snapshotId, jobId: id, ...job }));
+                res.end(serializeJSON({ requestId, jobId: job.id, ...job }));
             }
             catch (error) {
-                const job = { id, kind: 'dbt_refresh', status: 'failed', createdAt: new Date().toISOString(), error: error instanceof Error ? error.message : String(error) };
-                onboardingJobs.set(id, job);
                 res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
-                res.end(serializeJSON({ ...apiErrorEnvelope({ requestId, code: 'SNAPSHOT_BUILD_FAILED', message: job.error, nextActions: ['Keep using the previous snapshot while fixing compile diagnostics.'] }), jobId: id, ...job }));
+                res.end(serializeJSON(apiErrorEnvelope({ requestId, code: 'SNAPSHOT_BUILD_FAILED', message: error instanceof Error ? error.message : String(error), nextActions: ['Keep using the previous snapshot while fixing compile diagnostics.'] })));
             }
             return;
         }
@@ -3604,10 +3951,17 @@ export async function startLocalServer(opts) {
             const requestId = apiRequestId('onboarding-job-cancel');
             const id = decodeURIComponent(path.slice('/api/onboarding/jobs/'.length));
             const job = onboardingJobs.get(id);
-            if (job)
-                onboardingJobs.set(id, { ...job, status: 'cancelled' });
+            const cancelled = job ? {
+                ...job,
+                status: 'cancelled',
+                message: 'Stopped waiting for dbt preparation. The last valid snapshot remains available.',
+                updatedAt: new Date().toISOString(),
+                phases: job.phases.map((phase) => phase.status === 'running' ? { ...phase, status: 'cancelled' } : phase),
+            } : undefined;
+            if (cancelled)
+                onboardingJobs.set(id, cancelled);
             res.writeHead(job ? 200 : 404, { 'Content-Type': 'application/json; charset=utf-8' });
-            res.end(serializeJSON(job ? { requestId, ...job, status: 'cancelled' } : apiErrorEnvelope({ requestId, code: 'ONBOARDING_JOB_NOT_FOUND', message: `onboarding job not found: ${id}`, recoverable: false })));
+            res.end(serializeJSON(cancelled ? { requestId, ...cancelled } : apiErrorEnvelope({ requestId, code: 'ONBOARDING_JOB_NOT_FOUND', message: `onboarding job not found: ${id}`, recoverable: false })));
             return;
         }
         if (req.method === 'POST' && path === '/api/onboarding/domains/discover') {
@@ -3741,7 +4095,12 @@ export async function startLocalServer(opts) {
             const requestId = apiRequestId('domain-workspace');
             const suffix = decodeURIComponent(path.slice('/api/domain-workspaces/'.length));
             const relatedSuffix = '/related-products';
-            const domainId = suffix.endsWith(relatedSuffix) ? suffix.slice(0, -relatedSuffix.length) : suffix;
+            const knowledgeSuffix = '/knowledge';
+            const domainId = suffix.endsWith(relatedSuffix)
+                ? suffix.slice(0, -relatedSuffix.length)
+                : suffix.endsWith(knowledgeSuffix)
+                    ? suffix.slice(0, -knowledgeSuffix.length)
+                    : suffix;
             const snapshot = projectSnapshot();
             const manifest = snapshot.manifest;
             if (!manifest.modeling?.packages[domainId]) {
@@ -3749,6 +4108,19 @@ export async function startLocalServer(opts) {
                 res.end(serializeJSON(apiErrorEnvelope({ requestId, snapshotId: snapshot.snapshotId, code: 'DOMAIN_NOT_FOUND', message: `domain workspace not found: ${domainId}`, recoverable: false })));
                 return;
             }
+            if (suffix.endsWith(knowledgeSuffix)) {
+                await ensureMetadataCatalogFresh(projectRoot, { manifest, semanticLayer });
+                const knowledge = readIndexedDomainKnowledge(projectRoot, domainId)
+                    ?? canonicalDomainKnowledge(manifest, domainId, snapshot.snapshotId);
+                if (!knowledge) {
+                    res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON(apiErrorEnvelope({ requestId, snapshotId: snapshot.snapshotId, code: 'DOMAIN_KNOWLEDGE_NOT_FOUND', message: `domain knowledge capsule not found: ${domainId}`, recoverable: false })));
+                    return;
+                }
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ requestId, ...knowledge }));
+                return;
+            }
             res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
             res.end(serializeJSON(suffix.endsWith(relatedSuffix)
                 ? { requestId, domain: domainId, ...relatedProductsForDomain(manifest, domainId), snapshotId: snapshot.snapshotId }
@@ -3765,11 +4137,64 @@ export async function startLocalServer(opts) {
         // provenance references and the sparse DQL overlay, never copied dbt YAML.
         if (req.method === 'GET' && path === '/api/modeling/dbt-first') {
             const requestId = apiRequestId('modeling-dbt-first');
-            const snapshot = projectSnapshot();
+            const modelingEnabled = projectConfig.manifestVersion === 3 && projectConfig.modeling?.mode === 'dbt-first';
+            if (!modelingEnabled) {
+                res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(apiErrorEnvelope({
+                    requestId,
+                    code: 'DBT_FIRST_NOT_ENABLED',
+                    message: 'dbt-first modeling is not enabled. Connect and apply a dbt project from Settings → Project & dbt.',
+                    details: {
+                        manifestVersion: projectConfig.manifestVersion ?? 2,
+                        modelingMode: projectConfig.modeling?.mode ?? null,
+                    },
+                    nextActions: ['Open Settings → Project & dbt and apply a valid dbt project.'],
+                })));
+                return;
+            }
+            const dbtProjectDir = findDbtProjectPath(projectRoot, projectConfig);
+            const configuredManifestPath = projectConfig.dbt?.manifestPath ?? 'target/manifest.json';
+            const expectedManifestPath = resolve(dbtProjectDir, configuredManifestPath);
+            if (!existsSync(expectedManifestPath)) {
+                res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(apiErrorEnvelope({
+                    requestId,
+                    code: 'DBT_MANIFEST_NOT_FOUND',
+                    message: `The configured dbt manifest was not found at ${configuredManifestPath}.`,
+                    details: {
+                        projectDir: projectConfig.dbt?.projectDir ?? portableProjectPath(projectRoot, dbtProjectDir),
+                        manifestPath: configuredManifestPath,
+                    },
+                    nextActions: ['Run dbt parse, dbt compile, or dbt build in the configured dbt project, then refresh Domain Studio.'],
+                })));
+                return;
+            }
+            let snapshot;
+            try {
+                snapshot = projectSnapshot();
+            }
+            catch (error) {
+                res.writeHead(422, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(apiErrorEnvelope({
+                    requestId,
+                    code: 'DBT_MANIFEST_COMPILE_FAILED',
+                    message: apiErrorMessage(error),
+                    details: { manifestPath: configuredManifestPath },
+                    nextActions: ['Fix or rebuild the dbt manifest, then refresh Domain Studio.'],
+                })));
+                return;
+            }
             const manifest = snapshot.manifest;
             if (manifest.manifestVersion !== 3 || !manifest.modeling || !manifest.dbtProvenance) {
-                res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
-                res.end(serializeJSON(apiErrorEnvelope({ requestId, snapshotId: snapshot.snapshotId, code: 'DBT_FIRST_NOT_ENABLED', message: 'dbt-first modeling is not enabled. Set manifestVersion: 3 and modeling.mode: "dbt-first" in dql.config.json.', nextActions: ['Use Setup to connect dbt and enable dbt-first modeling.'] })));
+                res.writeHead(422, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(apiErrorEnvelope({
+                    requestId,
+                    snapshotId: snapshot.snapshotId,
+                    code: 'DBT_MANIFEST_COMPILE_FAILED',
+                    message: snapshot.error ?? 'DQL could not compile Domain Studio from the configured dbt manifest.',
+                    details: { manifestPath: configuredManifestPath },
+                    nextActions: ['Review the dbt artifact and DQL compile diagnostics, rebuild the dbt manifest, then refresh Domain Studio.'],
+                })));
                 return;
             }
             res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
@@ -3812,12 +4237,35 @@ export async function startLocalServer(opts) {
             const limit = Math.min(200, Math.max(1, Number(url.searchParams.get('limit')) || 50));
             const cursor = Math.max(0, Number(url.searchParams.get('cursor')) || 0);
             const query = (url.searchParams.get('q') ?? '').trim().toLowerCase();
+            const queryTokens = query.split(/[^a-z0-9]+/).filter(Boolean);
             const domain = (url.searchParams.get('domain') ?? '').trim();
             const boundByDbtId = new Map(Object.values(manifest.modeling?.entities ?? {}).map((entity) => [entity.dbtUniqueId, entity]));
             const nodes = Object.values(manifest.dbtProvenance?.nodes ?? {})
-                .filter((node) => !query || `${node.name} ${node.relation ?? ''} ${node.sourcePath ?? ''}`.toLowerCase().includes(query))
+                .filter((node) => {
+                if (!queryTokens.length)
+                    return true;
+                const haystack = `${node.name} ${node.uniqueId} ${node.relation ?? ''} ${node.sourcePath ?? ''}`.toLowerCase();
+                return queryTokens.every((token) => haystack.includes(token));
+            })
                 .filter((node) => !domain || boundByDbtId.get(node.uniqueId)?.domain === domain)
-                .sort((a, b) => a.uniqueId.localeCompare(b.uniqueId));
+                .sort((a, b) => {
+                if (!query)
+                    return a.uniqueId.localeCompare(b.uniqueId);
+                const score = (node) => {
+                    const name = node.name.toLowerCase();
+                    const uniqueId = node.uniqueId.toLowerCase();
+                    let value = name === query || uniqueId === query ? 1_000 : 0;
+                    if (name.startsWith(query))
+                        value += 500;
+                    if (uniqueId.startsWith(query))
+                        value += 300;
+                    if (name.includes(query))
+                        value += 200;
+                    value += queryTokens.reduce((total, token) => total + (name.startsWith(token) ? 80 : name.includes(token) ? 40 : 10), 0);
+                    return value;
+                };
+                return score(b) - score(a) || a.uniqueId.localeCompare(b.uniqueId);
+            });
             res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
             res.end(serializeJSON({
                 requestId,
@@ -4036,8 +4484,13 @@ export async function startLocalServer(opts) {
                 }
                 const wantsStream = url.searchParams.get('stream') === '1' || url.searchParams.get('stream') === 'true';
                 const runId = parsed.request.runId;
+                const runController = new AbortController();
+                parsed.request.signal = AbortSignal.any([
+                    runController.signal,
+                    AbortSignal.timeout(agentRunDeadlineMs(parsed.request)),
+                ]);
                 if (runId)
-                    activeAgentRunControllers.set(runId, new AbortController());
+                    activeAgentRunControllers.set(runId, runController);
                 try {
                     if (wantsStream) {
                         res.writeHead(200, {
@@ -9548,13 +10001,17 @@ export async function startLocalServer(opts) {
             try {
                 const graph = buildProjectLineageGraph(projectRoot, semanticLayer);
                 const result = queryBusiness360(graph, rawNodeId);
-                if (!result) {
+                const snapshot = projectSnapshot();
+                await ensureMetadataCatalogFresh(projectRoot, { manifest: snapshot.manifest, semanticLayer });
+                const knowledge = readIndexedKnowledge360(projectRoot, rawNodeId)
+                    ?? canonicalKnowledge360(snapshot.manifest, rawNodeId, snapshot.snapshotId);
+                if (!result && !knowledge) {
                     res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({ error: `Lineage node "${rawNodeId}" not found` }));
                     return;
                 }
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
-                res.end(serializeJSON(result));
+                res.end(serializeJSON(result ? { ...result, knowledge } : { version: 3, knowledge }));
             }
             catch (error) {
                 res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
@@ -10345,7 +10802,7 @@ export function resolveDefaultLLMProvider(projectRoot) {
     const preferred = ['openai', 'gemini', 'anthropic', 'custom-openai', 'ollama'];
     for (const id of preferred) {
         const provider = settings.find((item) => item.id === id);
-        if (provider?.enabled && provider.hasApiKey)
+        if (provider?.enabled && provider.configured)
             return id;
     }
     return null;
@@ -11779,7 +12236,8 @@ function installConnectorPackage(projectRoot, driver) {
             description: 'Project-local DQL connector packages',
         }, null, 2) + '\n', 'utf-8');
     }
-    execFileSync('npm', ['install', '--prefix', installRoot, '--no-audit', '--no-fund', definition.packageSpec], {
+    const npm = resolveNpmInvocation();
+    execFileSync(npm.command, [...npm.argsPrefix, 'install', '--prefix', installRoot, '--no-audit', '--no-fund', definition.packageSpec], {
         cwd: projectRoot,
         encoding: 'utf-8',
         stdio: 'pipe',
@@ -12986,9 +13444,18 @@ function readUserPrefs(userPrefsPath) {
             return { favorites: [], recentlyUsed: [] };
         }
         const raw = JSON.parse(readFileSync(userPrefsPath, 'utf-8'));
+        const acknowledgedVersion = typeof raw.setup?.acknowledgedVersion === 'string'
+            ? raw.setup.acknowledgedVersion.trim()
+            : '';
         return {
             favorites: Array.isArray(raw.favorites) ? raw.favorites.map(String) : [],
             recentlyUsed: Array.isArray(raw.recentlyUsed) ? raw.recentlyUsed.map(String) : [],
+            ...(acknowledgedVersion ? {
+                setup: {
+                    acknowledgedVersion,
+                    ...(typeof raw.setup?.acknowledgedAt === 'string' ? { acknowledgedAt: raw.setup.acknowledgedAt } : {}),
+                },
+            } : {}),
         };
     }
     catch {
@@ -15464,7 +15931,7 @@ async function createBlockStudioAssistProvider(projectRoot, requestedProvider) {
     const activeProvider = getActiveProvider(projectRoot);
     // Subscription CLI providers (Claude Code / Codex) carry no API key — they're
     // usable when enabled; their real "installed + logged in" check runs in available().
-    const isUsable = (provider) => provider.enabled && (provider.hasApiKey || provider.authMode === 'subscription_cli');
+    const isUsable = (provider) => provider.enabled && provider.configured;
     const selected = requestedProvider
         ? settings.find((provider) => provider.id === requestedProvider && isUsable(provider))
         : settings.find((provider) => provider.id === activeProvider && provider.enabled)
@@ -16386,17 +16853,127 @@ function buildNotebookTemplate(title, template) {
     return JSON.stringify({ dqlnbVersion: 2, version: 1, title, cells }, null, 2);
 }
 /** Build a lineage graph from the project's blocks and semantic layer. */
-// Simple lineage graph cache: rebuilds at most every 5 seconds
-let _lineageCache = null;
-const LINEAGE_CACHE_TTL_MS = 5000;
+// Cache per project + source fingerprint. A process can serve different roots,
+// and a time-only singleton previously returned the wrong graph after a change.
+const _lineageCache = new Map();
 function buildProjectLineageGraph(projectRoot, semanticLayer) {
-    if (_lineageCache && Date.now() - _lineageCache.builtAt < LINEAGE_CACHE_TTL_MS) {
-        return _lineageCache.graph;
-    }
+    const signature = lineageSourceSignature(projectRoot);
+    const cached = _lineageCache.get(projectRoot);
+    if (cached?.signature === signature)
+        return cached.graph;
     const graph = buildProjectLineageGraphUncached(projectRoot, semanticLayer);
-    _lineageCache = { graph, builtAt: Date.now() };
+    _lineageCache.set(projectRoot, { signature, graph });
     return graph;
 }
+function lineageSourceSignature(projectRoot) {
+    const hash = createHash('sha256');
+    const dbtManifestPath = resolveDbtManifestPath(projectRoot, {}) ?? undefined;
+    const inputs = new Set(collectInputFiles({ projectRoot, dbtManifestPath }));
+    const emittedManifest = join(projectRoot, 'dql-manifest.json');
+    if (existsSync(emittedManifest))
+        inputs.add(emittedManifest);
+    for (const input of [...inputs].sort()) {
+        try {
+            const stats = statSync(input);
+            hash.update(`${input}\0${stats.size}\0${stats.mtimeMs}\n`);
+        }
+        catch {
+            hash.update(`${input}\0missing\n`);
+        }
+    }
+    return hash.digest('hex');
+}
+/** UI-008: bounded compiler-owned Domain Knowledge Capsule response. */
+function canonicalDomainKnowledge(manifest, domainId, snapshotId) {
+    const graph = manifest.knowledgeGraph;
+    if (!graph)
+        return null;
+    const capsule = graph.domainCapsules[domainId]
+        ?? Object.values(graph.domainCapsules).find((item) => item.domainId === domainId && !item.modelAreaId)
+        ?? Object.values(graph.domainCapsules).find((item) => item.id === domainId || item.name === domainId);
+    const canonicalDomainId = capsule?.domainId
+        ?? Object.values(graph.objects ?? {}).find((item) => item.kind === 'domain' && (item.id === domainId || item.localId === domainId || item.aliases?.includes(domainId)))?.localId;
+    if (!canonicalDomainId)
+        return null;
+    const objects = Object.values(graph.objects ?? {})
+        .filter((item) => item.domainId === canonicalDomainId || item.id === `domain::${canonicalDomainId}`)
+        .sort((a, b) => a.id.localeCompare(b.id));
+    const objectIds = new Set(objects.map((item) => item.id));
+    const edges = (graph.edges ?? [])
+        .filter((edge) => objectIds.has(edge.from) || objectIds.has(edge.to))
+        .slice(0, 1_500);
+    const routes = graph.crossDomainRoutes.filter((route) => route.providerDomainId === canonicalDomainId || route.consumerDomainId === canonicalDomainId);
+    const routeSummary = routes.reduce((counts, route) => {
+        counts[route.state] = (counts[route.state] ?? 0) + 1;
+        return counts;
+    }, {});
+    return {
+        schemaVersion: graph.schemaVersion,
+        snapshotId,
+        sourceFingerprint: graph.sourceFingerprint,
+        domainId: canonicalDomainId,
+        capsule: capsule ?? graph.domainCapsules[canonicalDomainId],
+        counts: {
+            objects: objects.length,
+            edges: edges.length,
+            routes: routes.length,
+            routeStates: routeSummary,
+        },
+        objects: objects.slice(0, 750),
+        edges,
+        routes,
+        truncated: objects.length > 750 || edges.length >= 1_500,
+    };
+}
+/** REL-003: qualified-object neighborhood with route policy and provenance. */
+function canonicalKnowledge360(manifest, rawId, snapshotId) {
+    const graph = manifest.knowledgeGraph;
+    if (!graph)
+        return null;
+    const graphObjects = graph.objects ?? {};
+    const graphEdges = graph.edges ?? [];
+    const exact = graphObjects[rawId];
+    const matches = exact ? [exact] : Object.values(graphObjects).filter((item) => item.localId === rawId || item.aliases?.includes(rawId) || item.id.endsWith(`::${rawId}`));
+    if (matches.length !== 1) {
+        return matches.length > 1 ? {
+            snapshotId,
+            sourceFingerprint: graph.sourceFingerprint,
+            ambiguous: true,
+            candidates: matches.slice(0, 20).map((item) => ({ id: item.id, kind: item.kind, domainId: item.domainId })),
+        } : null;
+    }
+    const focus = matches[0];
+    const ids = new Set([focus.id]);
+    let frontier = new Set([focus.id]);
+    for (let depth = 0; depth < 2 && frontier.size > 0 && ids.size < 160; depth += 1) {
+        const next = new Set();
+        for (const edge of graphEdges) {
+            if (frontier.has(edge.from) && !ids.has(edge.to))
+                next.add(edge.to);
+            if (frontier.has(edge.to) && !ids.has(edge.from))
+                next.add(edge.from);
+        }
+        for (const id of next) {
+            if (ids.size >= 160)
+                break;
+            ids.add(id);
+        }
+        frontier = next;
+    }
+    const objects = [...ids].flatMap((id) => graphObjects[id] ? [graphObjects[id]] : []);
+    const edges = graphEdges.filter((edge) => ids.has(edge.from) && ids.has(edge.to)).slice(0, 500);
+    const domains = new Set(objects.flatMap((item) => item.domainId ? [item.domainId] : []));
+    const routes = graph.crossDomainRoutes.filter((route) => domains.has(route.providerDomainId) && domains.has(route.consumerDomainId));
+    return {
+        snapshotId,
+        sourceFingerprint: graph.sourceFingerprint,
+        focus,
+        objects,
+        edges,
+        routes,
+        truncated: ids.size >= 160 || edges.length >= 500,
+    };
+}
 function buildProjectLineageGraphUncached(projectRoot, semanticLayer) {
     const manifestPath = join(projectRoot, 'dql-manifest.json');
     if (existsSync(manifestPath)) {
@@ -17232,7 +17809,12 @@ async function readGitStatus(cwd) {
         behind = Number(match[0] ?? 0);
         ahead = Number(match[1] ?? 0);
     }
-    const statusRes = await execGit(gitRoot, ['status', '--porcelain=v1', '--untracked-files=normal']);
+    // UI-001, E2E-001: the Source Control surface is file-oriented. Git's
+    // "normal" untracked mode collapses a new directory into a single `?? dir/`
+    // record, which prevents the UI from showing or diffing the files inside it.
+    // Enumerate every untracked path so tracked and untracked changes share the
+    // same per-file review contract.
+    const statusRes = await execGit(gitRoot, ['status', '--porcelain=v1', '--untracked-files=all']);
     const changes = [];
     if (statusRes.code === 0) {
         for (const line of statusRes.stdout.split('\n')) {
@@ -17884,7 +18466,11 @@ async function testProviderConfig(projectRoot, id, overrides) {
     const base = getEffectiveProviderConfig(projectRoot, id);
     // When the user supplies inline values (testing what they typed before saving),
     // merge them over the saved config and test reachability regardless of enabled.
-    const inline = Boolean(overrides && (overrides.apiKey || overrides.baseUrl || overrides.model));
+    // The test route always passes an override object, even when every draft field
+    // is blank. That still means "test this candidate before save" and must allow
+    // a previously configured-but-disabled provider to be reactivated without
+    // forcing the user to paste its redacted secret again.
+    const inline = overrides !== undefined;
     const config = {
         ...base,
         ...(overrides?.apiKey ? { apiKey: overrides.apiKey } : {}),
@@ -17964,15 +18550,19 @@ async function testOpenAIProviderConfig(config, label, details) {
         return { ok: false, message: `${label} is not configured${details}. Add an API key in Settings or OPENAI_API_KEY.` };
     }
     try {
-        const client = new OpenAI({ apiKey: config.apiKey, baseURL: config.baseUrl });
-        const response = await client.responses.create({
-            model: config.model ?? 'gpt-5.5',
-            input: 'Reply with exactly: OK',
-            max_output_tokens: 16,
+        // Use the same provider adapter as governed Ask so enterprise gateways are
+        // tested against the runtime path users will actually execute.
+        const provider = new OpenAIProvider({
+            apiKey: config.apiKey,
+            baseUrl: config.baseUrl,
+            model: config.model,
         });
+        const response = await provider.generate([
+            { role: 'user', content: 'Reply with exactly: OK' },
+        ], { maxTokens: 16, temperature: 0 });
         return {
             ok: true,
-            message: `${label} SDK responded${details}: ${(response.output_text ?? 'OK').trim().slice(0, 80) || 'OK'}`,
+            message: `${label} responded through the governed runtime${details}: ${response.trim().slice(0, 80) || 'OK'}`,
         };
     }
     catch (error) {
@@ -17987,20 +18577,17 @@ async function testAnthropicProviderConfig(config, label, details) {
         return { ok: false, message: `${label} is not configured${details}. Add an API key in Settings or ANTHROPIC_API_KEY.` };
     }
     try {
-        const client = new Anthropic({
+        const provider = new ClaudeProvider({
             apiKey: config.apiKey,
-            ...(config.baseUrl ? { baseURL: normalizeAnthropicBaseUrl(config.baseUrl) } : {}),
-        });
-        const response = await client.messages.create({
-            model: config.model ?? 'claude-opus-4-8',
-            max_tokens: 16,
-            temperature: 0,
-            messages: [{ role: 'user', content: 'Reply with exactly: OK' }],
+            baseUrl: config.baseUrl,
+            model: config.model,
         });
-        const text = response.content?.filter((block) => block.type === 'text').map((block) => block.text ?? '').join('') ?? '';
+        const response = await provider.generate([
+            { role: 'user', content: 'Reply with exactly: OK' },
+        ], { maxTokens: 16, temperature: 0 });
         return {
             ok: true,
-            message: `${label} SDK responded${details}: ${text.trim().slice(0, 80) || 'OK'}`,
+            message: `${label} responded through the governed runtime${details}: ${response.trim().slice(0, 80) || 'OK'}`,
         };
     }
     catch (error) {
@@ -18049,6 +18636,13 @@ async function buildAgentSchemaContextFromCatalog(projectRoot, question, prepare
 }
 /** How long a stored live-warehouse schema snapshot is trusted before a rescan (P6). */
 const RUNTIME_SNAPSHOT_MAX_AGE_MS = 60 * 60 * 1000; // 1 hour
+// A resolver compares at most 12 compact cards and never performs tool calls;
+// ten seconds is the full allowance, not the start of another planning loop.
+const AGENT_MEANING_TIMEOUT_MS = 10_000;
+export function boundedAgentMeaningSignal(signal, timeoutMs = AGENT_MEANING_TIMEOUT_MS) {
+    const timeout = AbortSignal.timeout(Math.max(1, timeoutMs));
+    return signal ? AbortSignal.any([signal, timeout]) : timeout;
+}
 /**
  * Whether the project's stored live-schema snapshot is missing or older than the
  * freshness window (P6). Used to force a fresh information_schema scan even when the
@@ -18084,7 +18678,6 @@ function recordAgentRuntimeSchemaSnapshot(projectRoot, schemaContext, source) {
                     name: column.name,
                     type: column.type,
                     description: column.description,
-                    sampleValues: column.sampleValues?.slice(0, 8),
                 })),
             })),
         });
@@ -19017,25 +19610,29 @@ export function shouldAugmentAgentRuntimeSchema(question, questionPlan) {
     const plannedCompositeMetric = (questionPlan?.metricTerms?.length ?? 0) > 0 && plannedConcepts.size >= 2;
     return explicitJoin || referencesPriorRows || plannedCompositeMetric || (multiEntity && (wantsMetric || wantsDetail));
 }
-async function enrichAgentSchemaContextWithValueMatches(question, schemaContext, executor, connection) {
+async function enrichAgentSchemaContextWithValueMatches(question, schemaContext, executor, connection, searchSafeColumns) {
     const searchTerms = extractAgentValueSearchTerms(question);
     if (schemaContext.length === 0 || searchTerms.length === 0)
         return schemaContext;
     const matches = new Map();
-    for (const candidate of rankAgentValueProbeColumns(schemaContext).slice(0, 12)) {
+    const probes = rankAgentValueProbeColumns(schemaContext, searchSafeColumns).slice(0, 3).map(async (candidate) => {
         try {
-            const result = await executor.executeQuery(buildAgentValueProbeSql(candidate.table, candidate.column.name, searchTerms, connection), [], runtimeVariables({}), connection);
-            const values = uniqueStrings(result.rows.flatMap(valueProbeRowValues)).slice(0, 5);
-            if (values.length === 0)
-                continue;
-            const tableMatches = matches.get(candidate.table.relation) ?? new Map();
-            tableMatches.set(candidate.column.name, values);
-            matches.set(candidate.table.relation, tableMatches);
+            const result = await withAgentValueProbeTimeout(executor.executeQuery(buildAgentValueProbeSql(candidate.table, candidate.column.name, searchTerms, connection), [], runtimeVariables({}), connection), 2_000);
+            const values = uniqueStrings(result.rows.flatMap(valueProbeRowValues)).slice(0, 25);
+            return values.length > 0 ? { candidate, values } : undefined;
         }
         catch {
             // Value probes are advisory. Unsupported casts, privileges, and large-table
             // failures should not block the metadata-backed answer path.
+            return undefined;
         }
+    });
+    for (const match of await Promise.all(probes)) {
+        if (!match)
+            continue;
+        const tableMatches = matches.get(match.candidate.table.relation) ?? new Map();
+        tableMatches.set(match.candidate.column.name, match.values);
+        matches.set(match.candidate.table.relation, tableMatches);
     }
     if (matches.size === 0)
         return schemaContext;
@@ -19048,12 +19645,27 @@ async function enrichAgentSchemaContextWithValueMatches(question, schemaContext,
             columns: table.columns.map((column) => {
                 const sampleValues = tableMatches.get(column.name);
                 return sampleValues?.length
-                    ? { ...column, sampleValues: uniqueStrings([...(column.sampleValues ?? []), ...sampleValues]).slice(0, 5) }
+                    ? { ...column, sampleValues: uniqueStrings([...(column.sampleValues ?? []), ...sampleValues]).slice(0, 25) }
                     : column;
             }),
         };
     });
 }
+async function withAgentValueProbeTimeout(promise, timeoutMs) {
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => reject(new Error('VALUE_LOOKUP_TIMEOUT')), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
 function scoreAgentSchemaTable(table, tokens) {
     let score = 0;
     const relationTokens = agentSchemaTokens(`${table.schema ?? ''} ${table.name} ${table.relation}`);
@@ -19134,11 +19746,37 @@ function scoreAgentValueProbeTable(table) {
     }
     return Math.min(score, 18);
 }
-function rankAgentValueProbeColumns(schemaContext) {
+/**
+ * Resolve the project-admin boundary for live value lookup. An absent/malformed
+ * policy is deliberately disabled; a broad table or wildcard cannot make an
+ * unknown column search-safe.
+ */
+export function resolveAgentRuntimeValueGrounding(config) {
+    const configured = config.agent?.runtimeValueGrounding;
+    if (configured?.mode !== 'safe_automatic') {
+        return { mode: 'disabled', searchSafeColumns: new Set() };
+    }
+    const searchSafeColumns = new Set((configured.searchSafeColumns ?? [])
+        .map(normalizeAgentSafeColumnReference)
+        .filter((value) => value.split('.').length >= 2 && !value.includes('*')));
+    return searchSafeColumns.size > 0
+        ? { mode: 'safe_automatic', searchSafeColumns }
+        : { mode: 'disabled', searchSafeColumns };
+}
+function normalizeAgentSafeColumnReference(value) {
+    return value.trim().replace(/[`"\[\]]/g, '').toLowerCase();
+}
+function isExplicitlySearchSafeAgentColumn(table, column, searchSafeColumns) {
+    const qualified = normalizeAgentSafeColumnReference(`${table.relation}.${column.name}`);
+    const relationParts = table.relation.split('.').filter(Boolean);
+    const shortQualified = normalizeAgentSafeColumnReference(`${relationParts.slice(-1)[0] ?? table.relation}.${column.name}`);
+    return searchSafeColumns.has(qualified) || searchSafeColumns.has(shortQualified);
+}
+function rankAgentValueProbeColumns(schemaContext, searchSafeColumns) {
     const ranked = [];
     for (const table of schemaContext) {
         for (const column of table.columns) {
-            if (!isAgentValueProbeColumn(column))
+            if (!isAgentValueProbeColumn(column) || !isExplicitlySearchSafeAgentColumn(table, column, searchSafeColumns))
                 continue;
             ranked.push({
                 table,
@@ -19159,9 +19797,18 @@ function scoreAgentValueProbeColumn(table, column) {
         score += 3;
     return score;
 }
-function isAgentValueProbeColumn(column) {
+export function isAgentValueProbeColumn(column) {
     const name = column.name.toLowerCase();
-    if (/\b(password|secret|token|credential|hash|salt)\b/.test(name))
+    // Tokenize underscore/camel names before applying the hard deny-list. This is
+    // intentionally independent of an allowlist: secrets and free-text payloads
+    // can never be probed through automatic grounding.
+    const normalizedName = column.name
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/[_-]+/g, ' ')
+        .toLowerCase();
+    if (/\b(password|secret|token|credential|hash|salt|notes?|comments?|description|message|body|payload|content)\b/.test(normalizedName))
+        return false;
+    if (/\bemail\b/.test(normalizedName))
         return false;
     if (!hasAgentSchemaToken(name, [
         'account',
@@ -19199,15 +19846,22 @@ export function buildAgentValueProbeSql(table, column, searchTerms, connection)
     const relation = quoteAgentRelation(table.relation, connection);
     const identifier = quoteAgentIdentifier(column, connection);
     const castValue = `LOWER(CAST(${identifier} AS ${agentTextCastType(connection.driver)}))`;
-    const predicates = searchTerms
-        .slice(0, 5)
-        .map((term) => `${castValue} LIKE ${sqlStringLiteral(`%${escapeSqlLike(term.toLowerCase())}%`)} ESCAPE '\\'`)
+    const predicates = uniqueStrings(searchTerms.flatMap((term) => {
+        const normalized = term.toLowerCase().replace(/\s+/g, ' ').trim();
+        const tokens = normalized.split(' ').filter((token) => token.length >= 4);
+        return [
+            `${castValue} = ${sqlStringLiteral(normalized)}`,
+            ...tokens.slice(0, 2).map((token) => `${castValue} LIKE ${sqlStringLiteral(`${escapeSqlLike(token)}%`)} ESCAPE '\\'`),
+        ];
+    }))
+        .slice(0, 8)
+        .map((predicate) => predicate)
         .join(' OR ');
     return [
         `SELECT DISTINCT CAST(${identifier} AS ${agentTextCastType(connection.driver)}) AS value`,
         `FROM ${relation}`,
         `WHERE ${identifier} IS NOT NULL AND (${predicates})`,
-        'LIMIT 5',
+        'LIMIT 25',
     ].join('\n');
 }
 function agentTextCastType(driver) {
@@ -19291,6 +19945,9 @@ export function extractAgentValueSearchTerms(question) {
     for (const match of question.matchAll(/\b(?:for|named|called|only|where|customer|user|account|product)\s+([A-Za-z0-9@._-]+(?:\s+[A-Za-z0-9@._-]+){0,3})/gi)) {
         terms.push(match[1]);
     }
+    for (const match of question.matchAll(/\b(?:than|versus|vs\.?)\s+([A-Za-z0-9@._-]+(?:\s+[A-Za-z0-9@._-]+){0,3})/gi)) {
+        terms.push(match[1]);
+    }
     return uniqueStrings(terms
         .map(cleanAgentValueSearchTerm)
         .filter((term) => term.length >= 3 && !AGENT_VALUE_SEARCH_STOP_PHRASES.has(term.toLowerCase()))).slice(0, 6);
@@ -19301,6 +19958,7 @@ function cleanAgentValueSearchTerm(term) {
         .replace(/\s+/g, ' ')
         .trim()
         .replace(/^(?:account|customer|member|named|called|product|sku|subscriber|user)\s+/i, '')
+        .replace(/\s+\b(?:got|get|gets|bought|buy|buys|purchased|purchase|purchases|spent|spend|spends|has|have|with)\b.*$/i, '')
         .replace(/\s+\b(?:last|next|this)\b.*$/i, '')
         .replace(/\s+\b(?:last|this)\s+(?:day|week|month|quarter|year)\b.*$/i, '')
         .replace(/\s+\b(?:daily|weekly|monthly|quarterly|yearly)\b.*$/i, '')