@duckcodeailabs/dql-cli 1.12.10 → 1.13.0

package/dist/local-runtime.js

@@ -1,13 +1,16 @@
 import { execFileSync, execSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { gzipSync } from "node:zlib";
+import { gzip } from "node:zlib";
 import { createServer } from "node:http";
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, watch, writeFileSync, } from "node:fs";
+import { mkdir as mkdirAsync, rename as renameAsync, rm as rmAsync, writeFile as writeFileAsync, } from 'node:fs/promises';
 import { createRequire } from "node:module";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { dirname, extname, join, normalize, relative, resolve, sep, } from "node:path";
 import { Readable } from "node:stream";
+import { LocalOperationCoordinator, } from './local-operation-coordinator.js';
+import { ProjectRefreshCoordinator } from './project-refresh-coordinator.js';
 import { buildMixedSourceWarehouseFallbackSql, findMentionedNotebookDataset, planMixedSourceNotebookSql, planMixedSourceSql, } from "./mixed-source-sql.js";
 import { resolveNpmInvocation } from './npm-runtime.js';
 import { ensureDqlGitignore, isGovernedSourceFile, isLegacyBroadDqlIgnore, } from './git-contract.js';
@@ -24,7 +27,7 @@ import { listRemoteMcpSettings, saveRemoteMcpSettings } from './llm/mcp-config.j
 import { ClaudeProvider, ConversationStore, advanceThreadState, buildConversationSnapshot, conversationHistoryFromContext, recallRelevantTurns, renderConversationEnvelopeForPrompt, GeminiProvider, MemoryStore, OllamaProvider, OpenAIProvider, buildBlockBusinessFingerprint, buildBlockSqlFingerprints, buildAnalysisQuestionPlan, composeSemanticQueryForQuestion, aggregationIntegrityIssuesForSql, buildLocalContextPack, applyContextPackCompatibility, toAgentRetrievalEvidence, prepareConversationPath, defaultMemoryPath, ensureDefaultMemoryFiles, ensureAgentProjectReady, isAgentProjectIndexReady, currentMetadataFingerprint, ensureMetadataCatalogFresh, readIndexedDomainKnowledge, readIndexedKnowledge360, compactSemanticRuntimeFailure, classifyAnalyticalFailure, normalizeWarehouseSqlFailure, parseProposal, propose, proposePlan, recordGovernedCorrection, HintStore, defaultHintIndexPath, ensureHintIndexFresh, listHintsFromGit, getHintEvaluationFromGit, getCorrectionTraceFromGit, inspectGovernedHint, editGovernedHintCandidate, reopenGovernedHint, retireHint, supersedeHint, hintsConflict, mineJoinPatterns, reviewGovernedHint, AgentRunEngine, SqliteAgentRunStore, defaultAgentRunGates, createLlmAgentRunPlanner, createHybridRouter, computeResultStats, buildDeterministicDashboardStory, synthesizeAnswer, streamOrGenerate, narrateResult, buildProposePreview, buildFromPrompt, internalRelationIdsInSql, defaultAgentRunStorePath, defaultAgentRunSqlitePath, resolveLocalOwner, resolveProposeConfig, recordQueryRun, recordRuntimeSchemaSnapshot, latestRuntimeSchemaSnapshotForProject, loadSkills, migrateLegacySkills, configuredSkillsPath, skillsDir, draftDomainSkillBootstrap, buildDomainSkillBootstrapPrompt, mergeDomainSkillBootstrapEnrichment, writeSkill, deleteSkill, deriveGeneratedDraftSlug, deriveAnalyticalRepair, reindexProject, invalidateAgentProjectState, recordAgentRuntimeVersion, resolveDomainContextEnvelope, projectEmbeddingProvider, isHashedEmbeddingProvider, clearProjectEmbeddingCache, upgradeVectorIndexForProject, openMetadataCatalog, defaultKgPath, planAppFromPrompt, KGStore, planResearch, loadSemanticMetrics, cascadeTraceToEvidenceRouteSteps, createCascadeAnswerResult, createCascadeTrace, routeReasoningEffort, routeForCascadeAnswerTier, clampReasoningEffort, bumpReasoningEffort, resolveThinkingMode, coerceThinkingMode, upsertGeneratedDqlArtifactDraft, loadAgentSemanticLayer, isTrustedConversationTurn, resolveInternalRelationIds, analyticalError, tagAnalyticalError, withAnalyticalErrorOrigin, withAnalyticalErrorOriginSync, } from '@duckcodeailabs/dql-agent';
 import { addSqlResultFilter, filterableResultColumns, replaceBlockStudioSql } from './sql-result-filter.js';
 import { gatherProposeEnrichment } from './propose-enrich.js';
-import { handleAppsApi, proposeAppAiBuild, recommendVisualization } from './apps-api.js';
+import { handleAppsApi, proposeAppAiBuild, recommendVisualization, } from './apps-api.js';
 import { getActiveProvider, getEffectiveProviderConfig, isProviderSettingsId, listProviderSettings, saveProviderSettings, } from './settings/provider-settings.js';
 import { ClaudeCodeCliProvider, CodexCliProvider } from './providers/subscription-cli.js';
 import { ClaudeOAuthManager, ClaudeOAuthProvider, claudeOAuthConnected, CLAUDE_OAUTH_MODELS, CLAUDE_OAUTH_DEFAULT_MODEL, } from './providers/oauth/claude-oauth.js';
@@ -85,6 +88,63 @@ function hasDbtSemanticArtifacts(projectRoot, dbtProjectDir, configuredManifestP
     return false;
 }
 const AGENT_RUN_REQUESTED_MODES = new Set(['auto', 'ask', 'research', 'sql', 'block', 'app']);
+/** AGT-007 / AGT-022: App-specific context adapter into the uniform AgentRun. */
+export function buildAppCopilotResearchAgentRequest(input) {
+    const memoOnly = input.mode === 'memo_only';
+    const appResearch = {
+        mode: 'app_research',
+        generationMode: input.mode ?? 'sql_and_memo',
+        intent: input.intent,
+        appId: input.appId,
+        dashboardId: input.dashboardId,
+        sourceTileId: input.sourceTileId,
+        sourceBlockId: input.sourceBlockId,
+        title: input.title,
+        instruction: [
+            'Answer as an app-scoped analyst. Start from certified block/result context, active filters, dbt/semantic metadata, and schema evidence.',
+            memoOnly
+                ? 'Write the stakeholder memo from the supplied selected result, preview rows, generated SQL, metrics, drivers, filters, and caveats. Do not generate replacement SQL unless the user explicitly asks to fix SQL.'
+                : 'Generate review-required read-only SQL only when the certified result does not exactly answer the requested analysis grain. Execute only through the bounded generated SQL preview path.',
+            'In the natural-language answer, write a stakeholder analysis memo, not a generic chat answer. Use Markdown headings chosen for the question, usually Executive answer, Key numbers, Drivers or Business readout, Caveats, and Next action.',
+            'Use concrete numbers from the selected result or preview when available. If baseline, segment, grain, lineage, or source proof is missing, say that explicitly instead of inventing a driver story.',
+            'Keep raw SQL in proposedSql/sql. Do not put SQL code fences or implementation trace in the memo body.',
+        ].join(' '),
+        generatedSql: input.generatedSql,
+        metrics: input.metrics,
+        drivers: input.drivers,
+        resultPreviews: input.resultPreviews,
+        summaryHint: input.summaryHint,
+        recommendationHint: input.recommendationHint,
+        sqlError: input.sqlError,
+        sqlErrorKind: input.sqlErrorKind,
+        hasReportEvidence: input.hasReportEvidence,
+        context: input.context,
+    };
+    return {
+        question: memoOnly
+            ? [
+                `Research question: ${input.question}`,
+                'Write the business memo now using only the evidence envelope supplied as upstream context.',
+                'Return Markdown sections. Keep SQL, query text, implementation trace, and raw routing details out of the memo body.',
+                'If the evidence is insufficient, state the gap and the next reviewer action instead of filling the story with generic text.',
+            ].join('\n')
+            : input.question,
+        requestedMode: 'research',
+        audience: 'stakeholder',
+        selectedObject: {
+            kind: 'app',
+            id: input.appId,
+            title: input.title,
+        },
+        analysisDepth: 'deep',
+        workspaceContext: {
+            surface: 'app_copilot',
+            appId: input.appId,
+            dashboardId: input.dashboardId,
+            appResearch,
+        },
+    };
+}
 const AGENT_RUN_SELECTED_OBJECT_KINDS = new Set([
     'notebook',
     'cell',
@@ -228,6 +288,7 @@ export function parseAgentRunRequestBody(body) {
         request: {
             question,
             selectedEvidenceId: agentRunString(record.selectedEvidenceId),
+            clarificationSourceQuestion: agentRunString(record.clarificationSourceQuestion),
             requestedMode,
             audience,
             intent: agentRunString(record.intent),
@@ -324,7 +385,16 @@ export function agentRunDeadlineMs(request, env = process.env, activeProviderId)
     if (request.requestedMode === 'research' || effectiveDepth === 'deep') {
         return scale(researchDeadline);
     }
-    const plan = buildAnalysisQuestionPlan(request.question);
+    // A structured clarification chip displays a compact metric/path label, but
+    // the engine restores and executes the original analytical question. Budget
+    // from that same original question as well. Otherwise a complex ranking or
+    // cross-model request can incorrectly inherit the 45s scalar-lookup budget
+    // merely because the selected label is short, then time out after the user
+    // already supplied the exact governed meaning.
+    const deadlineQuestion = request.selectedEvidenceId
+        ? request.clarificationSourceQuestion?.trim() || request.question
+        : request.question;
+    const plan = buildAnalysisQuestionPlan(deadlineQuestion);
     if (plan.needsResearchWorkspace || isAnalyticalBuildQuestion(plan)) {
         return scale(researchDeadline);
     }
@@ -418,6 +488,41 @@ export function repairableSqlFromAgentRun(run) {
     }
     return undefined;
 }
+/** Editable DQL retained on an immutable failed run, including its bound values. */
+export function repairableDqlArtifactFromAgentRun(run) {
+    for (const artifact of run.artifacts) {
+        const payload = agentRunRecord(artifact.payload);
+        if (!payload)
+            continue;
+        const dqlArtifact = normalizeDqlArtifactReference(payload.dqlArtifact);
+        // Only an ownerless/custom SQL block is editable in place. Certified and
+        // semantic artifacts remain immutable; their retained compiled SQL may
+        // still produce a separate review-required repair result below.
+        if (dqlArtifact?.kind === 'sql_block'
+            && dqlArtifact.source?.trim()
+            && notebookDqlSourceAllowsBackgroundRepair(dqlArtifact.source)) {
+            return dqlArtifact;
+        }
+    }
+    return undefined;
+}
+/**
+ * Keep the parameter surface immutable while repairing malformed DQL. A parser
+ * cannot reliably read a broken wrapper, so collect both declared parameter
+ * names and SQL interpolation names with a deliberately small lexical pass.
+ */
+export function dqlRepairParameterContract(source) {
+    const names = new Set();
+    for (const match of source.matchAll(/\$\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}/g)) {
+        names.add(match[1]);
+    }
+    for (const match of source.matchAll(/\bparams\s*\{([\s\S]*?)\}/gi)) {
+        for (const declaration of match[1].matchAll(/(?:^|\n)\s*([A-Za-z_][A-Za-z0-9_]*)\s*:/g)) {
+            names.add(declaration[1]);
+        }
+    }
+    return [...names].sort((left, right) => left.localeCompare(right));
+}
 /** Structured producer failure retained on the source run. */
 export function warehouseFailureFromAgentRun(run) {
     for (const artifact of run.artifacts) {
@@ -429,10 +534,49 @@ export function warehouseFailureFromAgentRun(run) {
     }
     return undefined;
 }
+/**
+ * Retain planning and retrieval evidence for a successful derived repair while
+ * deliberately dropping the source failure and any result-bound facts. This
+ * is the presentation contract used by "How it was answered" and by grounded
+ * follow-ups after repair.
+ */
+export function repairPresentationContextFromAgentRun(run) {
+    const retainedKeys = [
+        'resolvedAnalyticalPlan',
+        'analyticalExecutionGraph',
+        'analyticalFreshnessObservation',
+        'governedCompilationReceipt',
+        'governedAnalyticalGraphCompilationReceipt',
+        'contextPack',
+        'contextPackId',
+        'cascade',
+        'citations',
+        'lineage',
+    ];
+    const context = {};
+    for (const artifact of run.artifacts) {
+        const payload = agentRunRecord(artifact.payload);
+        if (!payload)
+            continue;
+        for (const key of retainedKeys) {
+            if (context[key] === undefined && payload[key] !== undefined)
+                context[key] = payload[key];
+        }
+        const semanticTrace = agentRunRecord(payload.semanticExecutionTrace);
+        if (context.semanticExecutionTrace === undefined && semanticTrace && !semanticTrace.failure) {
+            context.semanticExecutionTrace = semanticTrace;
+        }
+    }
+    return context;
+}
 /** Permission, authentication, policy and unsafe-query failures are never AI-repaired. */
 export function analyticalFailureAllowsDeterministicRetry(failure) {
     return !failure || !['permission', 'authentication', 'unsafe', 'cancelled'].includes(failure.category);
 }
+/** Structured policy/access refusals stay terminal even when retained SQL exists. */
+export function analyticalFailureAllowsAppRepair(failure) {
+    return !failure || !['PERMISSION_DENIED', 'POLICY_DENIED'].includes(failure.code);
+}
 function businessNarrativeGaps(warnings) {
     const businessRelevant = (warnings ?? []).filter((warning) => !(/missing requested output column/i.test(warning)
         || /\bquery plan\b/i.test(warning)
@@ -1011,11 +1155,11 @@ export async function startLocalServer(opts) {
     const resolveNamedConnection = (name) => {
         if (!name)
             return null;
-        const stored = getStoredConnections(projectConfig);
-        const normalized = normalizeStoredConnection(stored[name]);
-        return normalized
-            ? normalizeProjectConnection(normalized, projectRoot)
-            : null;
+        // `GET /api/connections` exposes the active legacy/default connection as
+        // `default` so every execution surface can present one uniform selector.
+        // Resolve that selector through the same project contract used by metadata
+        // APIs instead of looking only in the newer named `connections` map.
+        return projectConnectionById(projectRoot, projectConfig, name);
     };
     const resolveExecutionConnection = async (body) => {
         const target = body.executionTarget && typeof body.executionTarget === "object"
@@ -1104,6 +1248,35 @@ export async function startLocalServer(opts) {
     // unchanged. Explicit refresh, save, and certification paths still request
     // the default forced rebuild below.
     await refreshLocalMetadataCatalog(projectRoot, undefined, undefined, false);
+    // PERF-001 / API-001: project mutations acknowledge after their source file
+    // is durable. Rebuildable manifest, lineage, metadata, and KG projections run
+    // in one coalesced worker lane and remain observable across page navigation.
+    const operationCoordinator = new LocalOperationCoordinator(join(projectRoot, '.dql', 'cache', 'operations.sqlite'));
+    const operationSseClients = new Set();
+    const operationIdempotency = new Map();
+    const projectRefreshCoordinator = new ProjectRefreshCoordinator(operationCoordinator, () => {
+        projectSnapshots.invalidate();
+        dbtNodeDetailCache.clear();
+        invalidateAgentProjectState(projectRoot);
+        _lineageCache.delete(projectRoot);
+    });
+    const scheduleProjectRefresh = (reason, writeManifest = true) => (projectRefreshCoordinator.schedule({
+        projectRoot,
+        dbtManifestPath: resolveDbtManifestPath(projectRoot, projectConfig) ?? undefined,
+        writeManifest,
+        reason,
+    }));
+    const unsubscribeOperationEvents = operationCoordinator.subscribe((operation) => {
+        const payload = serializeJSON(operation);
+        for (const client of operationSseClients) {
+            try {
+                client.write(`event: operation\ndata: ${payload}\n\n`);
+            }
+            catch {
+                operationSseClients.delete(client);
+            }
+        }
+    });
     const startupDbtManifestPath = resolveDbtManifestPath(projectRoot, projectConfig);
     if (startupDbtManifestPath && !isAgentProjectIndexReady(projectRoot)) {
         try {
@@ -1185,8 +1358,8 @@ export async function startLocalServer(opts) {
             catch { /* non-fatal */ }
         }
     }
-    const executeLocalSqlForStoredResult = async (sql) => {
-        const activeConnection = requireActiveConnection();
+    const executeLocalSqlForStoredResult = async (sql, executionConnection) => {
+        const activeConnection = requireActiveConnection(executionConnection);
         const semantic = prepareSemanticSql(sql, semanticLayer);
         if (semantic.unresolvedRefs.length > 0) {
             throw new Error(`Unknown semantic reference${semantic.unresolvedRefs.length > 1 ? 's' : ''}: ${semantic.unresolvedRefs.join(', ')}`);
@@ -2453,6 +2626,23 @@ export async function startLocalServer(opts) {
             const needsClarification = Boolean(plan.followUp);
             const notebookPath = agentRunNotebookPath(request, runId);
             const researchIntent = agentRunResearchIntent(request);
+            const researchSource = agentRunRecord(request.workspaceContext?.researchSource);
+            const researchExecutionConnection = !needsClarification && request.executionTarget
+                ? await resolveAgentRunExecutionConnection(request)
+                : undefined;
+            const researchExecutionConnectionName = request.executionTarget?.target === 'connection'
+                ? request.executionTarget.connectionName
+                : undefined;
+            const researchContextEnvelope = {
+                surface: 'unified_agent_run',
+                agentRunId: runId,
+                routeDecision,
+                selectedObject: request.selectedObject,
+                executionTarget: request.executionTarget,
+                workspaceContext: request.workspaceContext,
+                researchSource,
+                plan,
+            };
             let researchRun;
             let researchWorkspaceError;
             if (!needsClarification) {
@@ -2474,14 +2664,7 @@ export async function startLocalServer(opts) {
                             intent: researchIntent,
                             domain: agentRunWorkspaceValue(request, 'domain'),
                             owner: agentRunWorkspaceValue(request, 'owner'),
-                            context: {
-                                surface: 'unified_agent_run',
-                                agentRunId: runId,
-                                routeDecision,
-                                selectedObject: request.selectedObject,
-                                workspaceContext: request.workspaceContext,
-                                plan,
-                            },
+                            context: researchContextEnvelope,
                         });
                         emit({
                             type: 'artifact.created',
@@ -2496,14 +2679,13 @@ export async function startLocalServer(opts) {
                             sourceCellFingerprint,
                             question: request.question,
                             intent: researchIntent,
-                            context: {
-                                surface: 'unified_agent_run',
-                                agentRunId: runId,
-                                routeDecision,
-                                selectedObject: request.selectedObject,
-                                workspaceContext: request.workspaceContext,
-                                plan,
-                            },
+                            context: researchContextEnvelope,
+                            executionConnection: researchExecutionConnection,
+                            executionConnectionName: researchExecutionConnectionName,
+                            signal: request.signal,
+                            baselineSql: agentRunString(researchSource?.sql),
+                            baselineDqlArtifact: researchSource?.dqlArtifact,
+                            baselineRunId: agentRunString(researchSource?.runId),
                         });
                         researchRun = withNotebookResearchChecklist(executed);
                     }
@@ -2816,7 +2998,7 @@ export async function startLocalServer(opts) {
                             message: `Generating review-required SQL for an uncovered question: ${question}`,
                             route: 'app_build',
                         });
-                        return runGovernedAgentAnswerForRun({ question });
+                        return generateAppBuildAnswerWithRepair(question);
                     },
                 });
             }
@@ -3474,7 +3656,7 @@ export async function startLocalServer(opts) {
      * string, so the only remaining reasons to differ are the connection and the
      * governance gates, both of which report themselves honestly.
      */
-    const executeGeneratedSqlDirect = async (question, sql, seed, executionConnection) => {
+    const executeGeneratedSqlDirect = async (question, sql, seed, executionConnection, bindings) => {
         const activeConnection = requireActiveConnection(executionConnection);
         const rowBound = clampAnalyticalRowBound(seed?.limit ?? 200);
         const trimmed = sql.trim().replace(/;\s*$/, '').trim();
@@ -3535,7 +3717,7 @@ export async function startLocalServer(opts) {
             })
             : null;
         const rawResult = semanticExecution?.result
-            ?? await executor.executeQuery(preparation.executedSql, [], runtimeVariables({}), preparation.connection);
+            ?? await executor.executeQuery(preparation.executedSql, bindings?.sqlParams ?? [], runtimeVariables(bindings?.variables ?? {}), preparation.connection);
         const normalized = normalizeQueryResult(rawResult, semantic.semanticRefs);
         // The authoritative bound. `buildRowBoundedSql` may legitimately decline to
         // touch the statement, and only one of 15 drivers honours a maxRows hint, so
@@ -3716,13 +3898,15 @@ export async function startLocalServer(opts) {
      * evidence. The refusal can say the relation is not visible to this
      * connection, rather than only that DQL had not looked at it.
      */
-    const probeNamedRelationsForAgent = async (relations, probeConnection) => {
+    const probeNamedRelationsForAgent = async (relations, probeConnection, verifyExecutionSchema = false) => {
         const probeTarget = probeConnection ?? connection;
         if (!probeTarget)
             return undefined;
-        // Same operator switch that governs live value grounding: a deployment that
-        // wants zero live metadata traffic keeps it.
-        if (resolveAgentRuntimeValueGrounding(projectConfig).mode !== 'safe_automatic')
+        // Named relation discovery remains behind the operator's live-grounding
+        // switch. Executable schema verification is different: it is a bounded,
+        // read-only metadata point lookup for relations already selected from dbt,
+        // and never reads row values or mutates the active target.
+        if (!verifyExecutionSchema && resolveAgentRuntimeValueGrounding(projectConfig).mode !== 'safe_automatic')
             return undefined;
         const sql = buildNamedRelationProbeSql(relations);
         if (!sql)
@@ -3775,12 +3959,29 @@ export async function startLocalServer(opts) {
             && activeRuntimeSnapshot.status !== 'stale');
         const valueGrounding = resolveAgentRuntimeValueGrounding(projectConfig);
         if (catalogContext.length > 0) {
-            if (!schemaConnection || valueGrounding.mode !== 'safe_automatic')
+            if (!schemaConnection)
                 return catalogContext;
-            // 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, schemaConnection, valueGrounding.searchSafeColumns);
+            // dbt metadata is the semantic authority, but generated SQL must use the
+            // physical columns visible on THIS execution target. Verify only the few
+            // question-ranked relations with a bounded information_schema point lookup;
+            // this is read-only and never mutates DuckDB, Snowflake, or any other target.
+            let executionSchema = catalogContext;
+            try {
+                const live = await probeNamedRelationsForAgent(catalogContext.slice(0, 4).map((table) => table.relation), schemaConnection, true);
+                if (live?.schemaContext?.length) {
+                    executionSchema = reconcileAgentSchemaContextWithLive(catalogContext, live.schemaContext);
+                }
+            }
+            catch {
+                // Live verification is additive. Existing metadata remains available if
+                // the connection cannot expose information_schema to this user.
+            }
+            // The immutable dbt/DQL snapshot owns schema discovery. Live verification
+            // only confirms those named relations; row values remain governed by the
+            // separate allowlisted grounding policy below.
+            if (valueGrounding.mode !== 'safe_automatic')
+                return executionSchema;
+            const enriched = await enrichAgentSchemaContextWithValueMatches(question, executionSchema, executor, schemaConnection, valueGrounding.searchSafeColumns);
             return enriched;
         }
         // An activated, scope-qualified warehouse generation is the complete warm
@@ -3803,83 +4004,474 @@ export async function startLocalServer(opts) {
             return [];
         }
     };
-    const generateInvestigationSqlForApp = async (input) => {
-        const governed = resolveGovernedAnswerRunner(projectRoot);
-        const resolvedProvider = governed?.provider ?? null;
-        const runner = governed?.runner ?? null;
-        if (!resolvedProvider || !runner) {
-            throw new Error('No AI provider is configured. Configure a subscription (Claude Code / Codex), OpenAI, Gemini, Ollama, or a custom OpenAI-compatible endpoint in Settings.');
+    const boundedRepairError = (message, status, warehouseFailure) => Object.assign(new Error(message), { status, ...(warehouseFailure ? { warehouseFailure } : {}) });
+    /**
+     * Shared one-attempt SQL repair for Ask and Notebook. It never creates a
+     * conversation, writes a DQL file, changes targets, or promotes trust.
+     */
+    const executeBoundedSqlRepair = async (input) => {
+        let result;
+        let repairedSql = input.sourceSql;
+        let repairMode = 'deterministic';
+        let firstFailure;
+        try {
+            result = await executeGeneratedSqlDirect(input.question, input.sourceSql, undefined, input.targetConnection, { sqlParams: input.sqlParams, variables: input.variables });
         }
-        let governedAnswer;
-        let providerError;
-        const memoOnly = input.mode === 'memo_only';
-        const reasoningEffort = resolveRunReasoningEffort(projectRoot, resolvedProvider, 'research', false);
-        const contextEnvelope = {
-            mode: 'app_research',
-            generationMode: input.mode ?? 'sql_and_memo',
-            intent: input.intent,
-            appId: input.appId,
-            dashboardId: input.dashboardId,
-            sourceTileId: input.sourceTileId,
-            sourceBlockId: input.sourceBlockId,
-            title: input.title,
-            instruction: [
-                'Answer as an app-scoped analyst. Start from certified block/result context, active filters, dbt/semantic metadata, and schema evidence.',
-                memoOnly
-                    ? 'Write the stakeholder memo from the supplied selected result, preview rows, generated SQL, metrics, drivers, filters, and caveats. Do not generate replacement SQL unless the user explicitly asks to fix SQL.'
-                    : 'Generate review-required read-only SQL only when the certified result does not exactly answer the requested analysis grain. Execute only through the bounded generated SQL preview path.',
-                'In the natural-language answer, write a stakeholder analysis memo, not a generic chat answer. Use Markdown headings chosen for the question, usually Executive answer, Key numbers, Drivers or Business readout, Caveats, and Next action.',
-                'Use concrete numbers from the selected result or preview when available. If baseline, segment, grain, lineage, or source proof is missing, say that explicitly instead of inventing a driver story.',
-                'Keep raw SQL in proposedSql/sql. Do not put SQL code fences or implementation trace in the memo body.',
-            ].join(' '),
-            generatedSql: input.generatedSql,
-            metrics: input.metrics,
-            drivers: input.drivers,
-            resultPreviews: input.resultPreviews,
-            summaryHint: input.summaryHint,
-            recommendationHint: input.recommendationHint,
-            sqlError: input.sqlError,
-            sqlErrorKind: input.sqlErrorKind,
-            hasReportEvidence: input.hasReportEvidence,
-            context: input.context,
-        };
-        const controller = new AbortController();
-        await runner.run({
-            provider: resolvedProvider,
-            messages: [{
+        catch (error) {
+            firstFailure = normalizeWarehouseSqlFailure(error, input.targetConnection.driver);
+        }
+        if (!result) {
+            if (firstFailure?.retryDisposition !== 'model_repair') {
+                throw boundedRepairError(firstFailure?.redactedMessage ?? 'The deterministic repair did not produce an executable query.', 422, firstFailure);
+            }
+            const provider = await createBlockStudioAssistProvider(projectRoot);
+            if (!provider) {
+                throw boundedRepairError('Configure an available AI provider in Settings to repair this query.', 409);
+            }
+            let schemaContext;
+            try {
+                schemaContext = await getSchemaContextForAgent(input.question, undefined, input.targetConnection, input.targetConnectionName);
+            }
+            catch (error) {
+                const failure = normalizeWarehouseSqlFailure(error, input.targetConnection.driver);
+                throw boundedRepairError(failure.redactedMessage, 422, failure);
+            }
+            const boundedSchema = schemaContext.slice(0, 16).map((table) => ({
+                relation: table.relation,
+                columns: table.columns.slice(0, 40).map((column) => ({ name: column.name, type: column.type })),
+            }));
+            let raw;
+            try {
+                raw = await provider.generate([
+                    {
+                        role: 'system',
+                        content: [
+                            'Repair one failed read-only analytical SQL statement.',
+                            'Return exactly one JSON object in a ```json fence with keys summary, sql, viz, outputs.',
+                            'Preserve the requested grain, filters, output columns, and aggregation semantics.',
+                            input.sqlParams?.length
+                                ? 'Preserve every positional parameter placeholder exactly; do not add, remove, or renumber placeholders.'
+                                : '',
+                            'Use only relations and columns present in the supplied schema context.',
+                            'Never emit internal DQL relation identities such as source::, model::, seed::, or snapshot::.',
+                            'Do not add writes, DDL, multiple statements, or commentary outside the JSON fence.',
+                        ].join(' '),
+                    },
+                    {
+                        role: 'user',
+                        content: JSON.stringify({
+                            question: input.question,
+                            driver: input.targetConnection.driver,
+                            failure: firstFailure.redactedMessage,
+                            sql: input.sourceSql,
+                            parameters: input.sqlParams?.map((parameter) => ({
+                                name: parameter.name,
+                                placeholder: `$${parameter.position}`,
+                            })),
+                            schema: boundedSchema,
+                        }),
+                    },
+                ], { maxTokens: 1200, temperature: 0 });
+            }
+            catch {
+                throw boundedRepairError('The AI provider could not complete this repair. Check Provider Settings and retry.', 502);
+            }
+            const proposal = parseProposal(raw);
+            if (!proposal.sql?.trim()) {
+                throw boundedRepairError('The AI repair did not return an executable SQL statement.', 422);
+            }
+            repairedSql = proposal.sql.trim();
+            const requiredPlaceholders = (input.sqlParams ?? []).map((parameter) => `$${parameter.position}`);
+            if (requiredPlaceholders.some((placeholder) => !new RegExp(`${placeholder.replace('$', '\\$')}\\b`).test(repairedSql))) {
+                throw boundedRepairError('The repair changed this cell\'s parameter contract, so DQL stopped it before execution.', 422);
+            }
+            repairMode = 'ai';
+            try {
+                result = await executeGeneratedSqlDirect(input.question, repairedSql, undefined, input.targetConnection, { sqlParams: input.sqlParams, variables: input.variables });
+            }
+            catch (error) {
+                const failure = normalizeWarehouseSqlFailure(error, input.targetConnection.driver);
+                throw boundedRepairError(failure.redactedMessage, 422, failure);
+            }
+        }
+        // Keep preview-only row bounds out of editable notebook source. The one
+        // deterministic source rewrite we do persist is decoding internal graph
+        // identities, because those can never execute as warehouse SQL.
+        let rewrites = [];
+        if (internalRelationIdsInSql(repairedSql).length > 0) {
+            const normalizedSource = await prepareAnalyticalExecutionSql({
+                sql: repairedSql,
+                subject: 'Repaired SQL',
+                executor,
+                connection: input.targetConnection,
+                projectRoot,
+                projectConfig,
+                enforceReadOnly: true,
+            });
+            repairedSql = normalizedSource.decodedSql;
+            rewrites = normalizedSource.rewrites;
+        }
+        return { result, repairedSql, repairMode, firstFailure, rewrites };
+    };
+    /**
+     * Repair a DQL wrapper that cannot compile far enough to expose executable
+     * SQL. This is the DQL-side half of the same bounded repair contract used by
+     * Ask and Notebook: one provider call, one block, identical parameters, one
+     * read-only execution, and the exact target selected by the failed run.
+     */
+    const executeBoundedDqlRepair = async (input) => {
+        const provider = await createBlockStudioAssistProvider(projectRoot);
+        if (!provider) {
+            throw boundedRepairError('Configure an available AI provider in Settings to repair this DQL cell.', 409);
+        }
+        let schemaContext;
+        try {
+            // Include source identifiers in retrieval so a terse cell title still
+            // resolves the physical dbt relations and live target columns it uses.
+            schemaContext = await getSchemaContextForAgent(`${input.question}\n${input.source.slice(0, 6_000)}`, undefined, input.targetConnection, input.targetConnectionName);
+        }
+        catch (error) {
+            const failure = normalizeWarehouseSqlFailure(error, input.targetConnection.driver);
+            throw boundedRepairError(failure.redactedMessage, 422, failure);
+        }
+        const boundedSchema = schemaContext.slice(0, 16).map((table) => ({
+            relation: table.relation,
+            columns: table.columns.slice(0, 40).map((column) => ({ name: column.name, type: column.type })),
+        }));
+        let raw;
+        try {
+            raw = await provider.generate([
+                {
+                    role: 'system',
+                    content: [
+                        'Repair one malformed executable DQL custom block and its embedded read-only SQL.',
+                        'Return only one JSON object with exactly one key named dql. Do not use markdown.',
+                        'The DQL shape is: block "Name" { type = "custom" params { name: type = default } query = """SELECT ...""" visualization { ... } tests { ... } }.',
+                        'Preserve the block name, business fields, visualization, tests, requested grain, filters, output columns, and aggregation semantics.',
+                        'Preserve every declared parameter and every ${parameter} interpolation exactly. Do not add or remove parameters.',
+                        'Use only relations and columns present in the supplied schema context.',
+                        'Never emit internal relation identities such as source::, model::, seed::, or snapshot::.',
+                        'Return exactly one custom block. Never certify it, bind a saved block, add writes, DDL, or multiple SQL statements.',
+                    ].join(' '),
+                },
+                {
                     role: 'user',
-                    content: memoOnly
-                        ? [
-                            `Research question: ${input.question}`,
-                            'Write the business memo now using only the evidence envelope supplied as upstream context.',
-                            'Return Markdown sections. Keep SQL, query text, implementation trace, and raw routing details out of the memo body.',
-                            'If the evidence is insufficient, state the gap and the next reviewer action instead of filling the story with generic text.',
-                        ].join('\n')
-                        : input.question,
-                }],
-            upstream: {
-                cellId: `app-research:${input.appId}:${input.dashboardId ?? 'app'}`,
-                sql: JSON.stringify(contextEnvelope, null, 2),
+                    content: JSON.stringify({
+                        question: input.question,
+                        driver: input.targetConnection.driver,
+                        failure: input.failure.slice(0, 2_000),
+                        dql: input.source.slice(0, 40_000),
+                        parameters: input.parameters ?? {},
+                        schema: boundedSchema,
+                    }),
+                },
+            ], { maxTokens: 2400, temperature: 0 });
+        }
+        catch {
+            throw boundedRepairError('The AI provider could not complete this DQL repair. Check Provider Settings and retry.', 502);
+        }
+        let repairedSource;
+        try {
+            const parsed = parseFirstJsonObject(raw);
+            repairedSource = parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+                && typeof parsed.dql === 'string'
+                ? String(parsed.dql).trim()
+                : undefined;
+        }
+        catch {
+            repairedSource = undefined;
+        }
+        if (!repairedSource) {
+            throw boundedRepairError('The AI repair did not return a complete DQL block.', 422);
+        }
+        if (repairedSource.length > 50_000) {
+            throw boundedRepairError('The repaired DQL exceeded the safe editable-cell size limit.', 422);
+        }
+        if (/^\s*@block\(/i.test(repairedSource) || /\btype\s*=\s*"semantic"/i.test(repairedSource)) {
+            throw boundedRepairError('The repair changed this editable custom block into a governed reference or semantic block.', 422);
+        }
+        if (!/\bstatus\s*=\s*"certified"/i.test(input.source)
+            && /\bstatus\s*=\s*"certified"/i.test(repairedSource)) {
+            throw boundedRepairError('The repair attempted to certify an AI-edited block, so DQL stopped it.', 422);
+        }
+        const beforeParameters = dqlRepairParameterContract(input.source);
+        const afterParameters = dqlRepairParameterContract(repairedSource);
+        if (beforeParameters.join('|') !== afterParameters.join('|')) {
+            throw boundedRepairError('The repair changed this block\'s parameter contract, so DQL stopped it before execution.', 422);
+        }
+        let invocation;
+        let plan;
+        try {
+            const program = new Parser(repairedSource, '<bounded-dql-repair>').parse();
+            const blocks = program.statements.filter((statement) => statement.kind === NodeKind.BlockDecl);
+            if (blocks.length !== 1 || program.statements.length !== 1) {
+                throw new Error('The repaired source must contain exactly one DQL block.');
+            }
+            const block = blocks[0];
+            if (block.kind !== NodeKind.BlockDecl || block.blockType !== 'custom') {
+                throw new Error('The repaired source must remain a custom DQL block.');
+            }
+            invocation = prepareBlockInvocation({
+                source: repairedSource,
+                parameters: input.parameters,
+                question: input.question,
+                surface: 'notebook',
+            });
+            if (invocation.errors.length)
+                throw new Error(invocation.errors.join(' '));
+            if (invocation.unresolvedParameters.length) {
+                throw new Error(`Provide required parameters before retrying: ${invocation.unresolvedParameters.join(', ')}.`);
+            }
+            plan = buildExecutionPlan({
+                id: 'bounded-dql-repair',
+                type: 'dql',
+                source: repairedSource,
+                title: input.artifactName,
+            }, {
+                semanticLayer,
+                driver: input.targetConnection.driver,
+                parameters: invocation.values,
+            });
+            if (!plan?.sql?.trim())
+                throw new Error('The repaired DQL did not compile to SQL.');
+        }
+        catch (error) {
+            throw boundedRepairError(`The repaired DQL did not compile safely: ${error instanceof Error ? error.message : String(error)}`, 422);
+        }
+        const seed = {
+            kind: 'sql_block',
+            source: repairedSource,
+            name: input.artifactName ?? plan.title,
+            persistence: 'transient',
+            trustState: 'review_required',
+            compiledSql: plan.sql,
+            ...(invocation.parameters.length ? { parameters: invocation.parameters } : {}),
+            ...(Object.keys(invocation.values).length ? { parameterValues: invocation.values } : {}),
+        };
+        let result;
+        try {
+            result = await executeGeneratedSqlDirect(input.question, plan.sql, seed, input.targetConnection, { sqlParams: plan.sqlParams, variables: { ...plan.variables, ...invocation.values } });
+        }
+        catch (error) {
+            const failure = normalizeWarehouseSqlFailure(error, input.targetConnection.driver);
+            throw boundedRepairError(failure.redactedMessage, 422, failure);
+        }
+        result = {
+            ...result,
+            dqlArtifact: {
+                ...(result.dqlArtifact ?? seed),
+                source: repairedSource,
+                compiledSql: result.sql ?? plan.sql,
+                trustState: 'review_required',
+                persistence: 'transient',
+                ...(result.executionReceipt ? { executionReceipt: result.executionReceipt } : {}),
             },
-            reasoningEffort,
-            analysisDepth: 'deep',
-            projectRoot,
-            executeCertifiedBlock: executeCertifiedBlockForAgent,
-            executeGeneratedSql: executeGeneratedSqlForAgent,
-            getSchemaContext: getSchemaContextForAgent,
-        }, (turn) => {
-            if (turn.kind === 'tool_result' && turn.id === 'governed_answer') {
-                governedAnswer = turn.output;
+        };
+        return {
+            result,
+            repairedSql: plan.sql,
+            repairedSource,
+            repairMode: 'ai',
+            rewrites: [],
+            sqlParams: plan.sqlParams,
+            variables: { ...plan.variables, ...invocation.values },
+        };
+    };
+    /**
+     * App proposal parity with Ask/Notebook repair. The first governed attempt is
+     * retained unchanged. Only an execution failure with retained read-only SQL
+     * may spend the shared one-attempt repair budget, on the same connection.
+     * The repaired candidate is still exploratory and review-required.
+     */
+    const generateAppBuildAnswerWithRepair = async (question, appContext) => {
+        const request = {
+            question,
+            audience: 'stakeholder',
+            workspaceContext: appContext
+                ? { surface: 'app_builder', appContext }
+                : { surface: 'app_builder' },
+        };
+        const answer = await runGovernedAgentAnswerForRun(request);
+        const sourceSql = answer.proposedSql?.trim() || answer.sql?.trim();
+        const hasExecutionFailure = agentAnswerHasExecutionFailure(answer)
+            || Boolean(answer.warehouseFailure)
+            || Boolean(answer.analyticalFailure);
+        if (answer.result || !sourceSql || !hasExecutionFailure)
+            return answer;
+        const attemptedAt = new Date().toISOString();
+        const originalFailure = answer.warehouseFailure?.redactedMessage
+            ?? answer.executionError
+            ?? 'The generated query did not execute.';
+        const originalSqlFingerprint = `sha256:${createHash('sha256').update(sourceSql).digest('hex')}`;
+        const failedTrace = (message) => ({
+            version: 1,
+            status: 'failed',
+            source: 'query_generator',
+            attemptedAt,
+            originalFailure,
+            originalSqlFingerprint,
+            approvalEligible: false,
+            message,
+        });
+        if (!analyticalFailureAllowsDeterministicRetry(answer.warehouseFailure)
+            || !analyticalFailureAllowsAppRepair(answer.analyticalFailure)) {
+            return {
+                ...answer,
+                appBuilderRepair: failedTrace('This failure needs an access, policy, or connection decision and was not sent to AI repair.'),
+            };
+        }
+        try {
+            const targetConnection = await resolveAgentRunExecutionConnection(request);
+            const targetConnectionName = request.executionTarget?.target === 'connection'
+                ? request.executionTarget.connectionName
+                : request.executionTarget?.target === 'local'
+                    ? 'local'
+                    : projectConfig.defaultConnectionName;
+            const repaired = await executeBoundedSqlRepair({
+                question,
+                sourceSql,
+                targetConnection,
+                targetConnectionName,
+            });
+            const repair = {
+                version: 1,
+                status: 'repaired',
+                source: 'query_generator',
+                mode: repaired.repairMode,
+                attemptedAt,
+                originalFailure,
+                originalSqlFingerprint,
+                repairedSqlFingerprint: `sha256:${createHash('sha256').update(repaired.repairedSql).digest('hex')}`,
+                approvalEligible: false,
+                message: `${repaired.repairMode === 'ai' ? 'AI' : 'Deterministic'} repair executed successfully on the same data target. Review the repaired query before adding it to the private App draft.`,
+            };
+            return {
+                ...answer,
+                result: repaired.result,
+                proposedSql: repaired.repairedSql,
+                sql: repaired.repairedSql,
+                executionError: undefined,
+                warehouseFailure: undefined,
+                analyticalFailure: undefined,
+                validationWarnings: [
+                    ...(answer.validationWarnings ?? []),
+                    repair.message,
+                ],
+                appBuilderRepair: repair,
+            };
+        }
+        catch (error) {
+            return {
+                ...answer,
+                appBuilderRepair: failedTrace(error instanceof Error
+                    ? `The bounded repair could not complete: ${error.message}`
+                    : 'The bounded repair could not complete.'),
+            };
+        }
+    };
+    const repairFailedAppTileExecution = async (input) => {
+        const attemptedAt = new Date().toISOString();
+        const driver = input.targetConnection?.driver ?? connection?.driver ?? 'duckdb';
+        const failure = normalizeWarehouseSqlFailure(input.error, driver);
+        const originalFailure = failure.redactedMessage;
+        const originalSqlFingerprint = input.sourceSql
+            ? `sha256:${createHash('sha256').update(input.sourceSql).digest('hex')}`
+            : undefined;
+        const failed = (message) => ({
+            ok: false,
+            repair: {
+                version: 1,
+                status: 'failed',
+                source: input.source,
+                attemptedAt,
+                originalFailure,
+                ...(originalSqlFingerprint ? { originalSqlFingerprint } : {}),
+                approvalEligible: false,
+                message,
+            },
+        });
+        if (!input.targetConnection) {
+            return failed('Configure the original data target before retrying this App tile.');
+        }
+        if (!input.sourceSql?.trim() && input.sourceDql?.trim()) {
+            try {
+                const repaired = await executeBoundedDqlRepair({
+                    question: input.question,
+                    source: input.sourceDql,
+                    failure: originalFailure,
+                    targetConnection: input.targetConnection,
+                    targetConnectionName: input.targetConnectionName,
+                    parameters: input.variables,
+                    artifactName: input.artifactName,
+                });
+                const repair = {
+                    version: 1,
+                    status: 'repaired',
+                    source: input.source,
+                    mode: repaired.repairMode,
+                    attemptedAt,
+                    originalFailure,
+                    repairedSqlFingerprint: `sha256:${createHash('sha256').update(repaired.repairedSql).digest('hex')}`,
+                    approvalEligible: false,
+                    message: `${repaired.repairMode === 'ai' ? 'AI' : 'Deterministic'} DQL repair executed successfully on the same data target. The App result remains review-required and the source file was not changed.`,
+                };
+                return {
+                    ok: true,
+                    result: repaired.result,
+                    repairedSql: repaired.repairedSql,
+                    repairedDql: repaired.repairedSource,
+                    repair,
+                };
             }
-            if (turn.kind === 'error') {
-                providerError = turn.message;
+            catch (error) {
+                return failed(error instanceof Error
+                    ? `The bounded DQL repair could not complete: ${error.message}`
+                    : 'The bounded DQL repair could not complete.');
             }
-        }, controller.signal);
-        if (!governedAnswer) {
-            throw new Error(providerError ?? 'The AI provider did not return a governed answer.');
         }
+        if (!input.sourceSql?.trim()) {
+            return failed('DQL retained the failure, but no read-only SQL or editable DQL was available for bounded repair.');
+        }
+        if (!analyticalFailureAllowsDeterministicRetry(failure)) {
+            return failed('This failure needs an access, policy, or connection decision and was not sent to AI repair.');
+        }
+        try {
+            const repaired = await executeBoundedSqlRepair({
+                question: input.question,
+                sourceSql: input.sourceSql,
+                targetConnection: input.targetConnection,
+                targetConnectionName: input.targetConnectionName,
+                sqlParams: input.sqlParams,
+                variables: input.variables,
+            });
+            const repair = {
+                version: 1,
+                status: 'repaired',
+                source: input.source,
+                mode: repaired.repairMode,
+                attemptedAt,
+                originalFailure,
+                ...(originalSqlFingerprint ? { originalSqlFingerprint } : {}),
+                repairedSqlFingerprint: `sha256:${createHash('sha256').update(repaired.repairedSql).digest('hex')}`,
+                approvalEligible: false,
+                message: `${repaired.repairMode === 'ai' ? 'AI' : 'Deterministic'} repair executed successfully on the same data target. The result remains review-required.`,
+            };
+            return { ok: true, result: repaired.result, repairedSql: repaired.repairedSql, repair };
+        }
+        catch (error) {
+            return failed(error instanceof Error
+                ? `The bounded repair could not complete: ${error.message}`
+                : 'The bounded repair could not complete.');
+        }
+    };
+    const generateInvestigationSqlForApp = async (input) => {
+        const request = buildAppCopilotResearchAgentRequest(input);
+        // AGT-007 / AGT-022: App Copilot keeps its server-owned App evidence
+        // adapter, while routing the actual investigation through the uniform
+        // snapshot, retrieval, trust, execution, and bounded-repair orchestration.
+        const governedAnswer = await runGovernedAgentAnswerForRun(request, undefined, 'research');
         return {
-            sql: memoOnly ? undefined : governedAnswer.proposedSql ?? governedAnswer.sql,
+            sql: input.mode === 'memo_only' ? undefined : governedAnswer.proposedSql ?? governedAnswer.sql,
             answer: governedAnswer.answer ?? governedAnswer.text,
             result: governedAnswer.result,
             analysisPlan: governedAnswer.analysisPlan,
@@ -3997,6 +4589,9 @@ export async function startLocalServer(opts) {
         let generatedSql = notebookResearchString(input.generatedSql) ?? run.generatedSql;
         let reviewedSql = notebookResearchString(input.reviewedSql) ?? run.reviewedSql;
         let dqlArtifact = normalizeDqlArtifactReference(input.dqlArtifact) ?? run.dqlArtifact;
+        const baselineSql = notebookResearchString(input.baselineSql);
+        const baselineDqlArtifact = normalizeDqlArtifactReference(input.baselineDqlArtifact);
+        let usedBaselineFallback = false;
         const startedAt = new Date().toISOString();
         storage.updateRun(run.id, {
             domain,
@@ -4047,7 +4642,7 @@ export async function startLocalServer(opts) {
                     generationWarnings.push('No AI provider is configured. Metadata context was saved as a research plan; paste SQL or configure an AI provider to generate candidate SQL.');
                 }
                 else {
-                    const controller = new AbortController();
+                    const researchSignal = input.signal ?? new AbortController().signal;
                     try {
                         await runner.run({
                             provider: resolvedProvider,
@@ -4069,18 +4664,19 @@ export async function startLocalServer(opts) {
                             reasoningEffort: resolveRunReasoningEffort(projectRoot, resolvedProvider, 'research', false),
                             analysisDepth: 'deep',
                             projectRoot,
-                            executeCertifiedBlock: executeCertifiedBlockForAgent,
-                            executeGeneratedSql: executeGeneratedSqlForAgent,
-                            getSchemaContext: getSchemaContextForAgent,
+                            executeCertifiedBlock: (node, invocation) => executeCertifiedBlockForAgent(node, invocation, input.executionConnection, input.executionConnectionName),
+                            executeGeneratedSql: (sql, artifact) => executeGeneratedArtifactForAgent(question, sql, artifact, input.executionConnection, input.executionConnectionName),
+                            getSchemaContext: (schemaQuestion, preparedContextPack) => getSchemaContextForAgent(schemaQuestion, preparedContextPack, input.executionConnection, input.executionConnectionName),
                         }, (turn) => {
                             if (turn.kind === 'tool_result' && turn.id === 'governed_answer') {
                                 governedAnswer = turn.output;
                             }
                             if (turn.kind === 'error')
                                 providerError = turn.message;
-                        }, controller.signal);
+                        }, researchSignal);
                     }
                     catch (error) {
+                        rethrowIfCancelled(error, input.signal);
                         providerError = error instanceof Error ? error.message : String(error);
                     }
                     if (!governedAnswer) {
@@ -4095,6 +4691,25 @@ export async function startLocalServer(opts) {
                     }
                 }
             }
+            const deeperCompositionFailed = !governedAnswer
+                || governedAnswer.kind === 'no_answer'
+                || agentAnswerHasExecutionFailure(governedAnswer)
+                || Boolean(governedAnswer.analyticalFailure)
+                || (!governedAnswer.result && !generatedSql && !dqlArtifact);
+            if (!reviewedSql && baselineSql && deeperCompositionFailed) {
+                const failure = governedAnswer?.executionError
+                    ?? governedAnswer?.analyticalFailure?.message
+                    ?? governedAnswer?.answer
+                    ?? governedAnswer?.text
+                    ?? providerError;
+                generatedSql = baselineSql;
+                dqlArtifact = baselineDqlArtifact ?? dqlArtifact;
+                usedBaselineFallback = true;
+                generationWarnings.push([
+                    'The deeper composition did not produce a safer executable query, so DQL kept and revalidated the successful Ask baseline on the same data target.',
+                    failure ? `Research detail: ${failure}` : '',
+                ].filter(Boolean).join(' '));
+            }
             const sqlForPreview = reviewedSql || generatedSql;
             const warnings = [
                 ...(contextPack.warnings ?? []),
@@ -4103,14 +4718,14 @@ export async function startLocalServer(opts) {
             ].filter(Boolean);
             let resultPreview;
             let previewError;
-            if (governedAnswer?.result?.rows && !reviewedSql) {
+            if (!usedBaselineFallback && governedAnswer?.result?.rows && !reviewedSql) {
                 resultPreview = normalizeNotebookAgentResult(governedAnswer.result);
             }
             else if (sqlForPreview) {
                 try {
                     const previewSql = buildAgentPreviewSql(sqlForPreview);
                     const previewStart = Date.now();
-                    resultPreview = await executeLocalSqlForStoredResult(previewSql);
+                    resultPreview = await executeLocalSqlForStoredResult(previewSql, input.executionConnection);
                     recordNotebookQueryRun(projectRoot, {
                         notebookPath: run.notebookPath,
                         cellId: run.sourceCellId,
@@ -4150,8 +4765,10 @@ export async function startLocalServer(opts) {
                 : undefined;
             const evidence = {
                 trustStatus: {
-                    label: governedAnswer?.trustLabel
-                        ?? (reviewedSql ? 'Reviewed notebook SQL' : generatedSql ? 'AI-generated research SQL' : dqlArtifact ? 'AI-generated DQL artifact' : 'Metadata-grounded research plan'),
+                    label: usedBaselineFallback
+                        ? 'Successful Ask baseline · revalidated on the same target'
+                        : governedAnswer?.trustLabel
+                            ?? (reviewedSql ? 'Reviewed notebook SQL' : generatedSql ? 'AI-generated research SQL' : dqlArtifact ? 'AI-generated DQL artifact' : 'Metadata-grounded research plan'),
                     reviewRequired: true,
                 },
                 contextPackId: contextPack.id,
@@ -4185,9 +4802,11 @@ export async function startLocalServer(opts) {
                     ...(governedAnswer?.citations ?? []),
                 ].slice(0, 40),
             };
-            const summary = notebookResearchString(governedAnswer?.answer)
-                ?? notebookResearchString(governedAnswer?.text)
-                ?? notebookResearchSummary(question, resultPreview, previewError);
+            const summary = usedBaselineFallback && resultPreview && !previewError
+                ? 'Research retained the successful Ask baseline and revalidated it on the same data target. No unverified replacement query was accepted; use the dossier to add the next breakdown or comparison.'
+                : notebookResearchString(governedAnswer?.answer)
+                    ?? notebookResearchString(governedAnswer?.text)
+                    ?? notebookResearchSummary(question, resultPreview, previewError);
             const recommendation = previewError
                 ? 'Review the SQL, selected metadata, and connection context before rerunning.'
                 : dqlArtifact && !reviewedSql
@@ -4225,6 +4844,9 @@ export async function startLocalServer(opts) {
                 contextPackId: contextPack.id,
                 routeDecision,
                 warnings: [
+                    ...(usedBaselineFallback && input.baselineRunId
+                        ? [`Baseline Ask run: ${input.baselineRunId}`]
+                        : []),
                     ...warnings,
                     ...(display && !display.ok ? [display.error] : []),
                     ...(display && display.ok ? display.warnings : []),
@@ -4235,6 +4857,7 @@ export async function startLocalServer(opts) {
             }) ?? run;
         }
         catch (error) {
+            rethrowIfCancelled(error, input.signal);
             return storage.updateRun(run.id, {
                 domain,
                 owner,
@@ -4461,16 +5084,19 @@ export async function startLocalServer(opts) {
     });
     // SSE clients for /api/watch hot-reload
     const sseClients = new Set();
+    const projectWatchers = [];
+    let runtimeClosing = false;
     // Watch all Git-owned authoring roots. Domain Packages are recursive and are
     // the canonical home for modeling, skills, blocks, notebooks, Apps, and evals.
     if (projectRoot) {
-        let sourceRefreshTimer;
         for (const dir of ['domains', 'skills', 'tests', 'notebooks', 'workbooks', 'blocks', 'apps', 'dashboards', 'semantic-layer', 'data']) {
             const watchDir = join(projectRoot, dir);
             if (!existsSync(watchDir))
                 continue;
             try {
-                watch(watchDir, { persistent: false, recursive: true }, (eventType, filename) => {
+                const watcher = watch(watchDir, { persistent: false, recursive: true }, (eventType, filename) => {
+                    if (runtimeClosing)
+                        return;
                     if (!filename)
                         return;
                     const path = `${dir}/${filename}`;
@@ -4485,11 +5111,7 @@ export async function startLocalServer(opts) {
                     }
                     if (['domains', 'skills', 'tests', 'blocks', 'apps', 'notebooks'].includes(dir)) {
                         invalidateAgentProjectState(projectRoot);
-                        if (sourceRefreshTimer)
-                            clearTimeout(sourceRefreshTimer);
-                        sourceRefreshTimer = setTimeout(() => {
-                            void refreshUnifiedProjectIndexes(projectRoot).catch(() => undefined);
-                        }, 250);
+                        scheduleProjectRefresh(`file:${path}`);
                     }
                     // Hot-reload semantic layer on change and notify frontend
                     if (dir === 'semantic-layer') {
@@ -4507,21 +5129,20 @@ export async function startLocalServer(opts) {
                         }).catch(() => { });
                     }
                 });
+                projectWatchers.push(watcher);
             }
             catch { /* dir not watchable */ }
         }
         const configuredDbtManifest = resolveDbtManifestPath(projectRoot, projectConfig);
         if (configuredDbtManifest && existsSync(dirname(configuredDbtManifest))) {
             try {
-                watch(dirname(configuredDbtManifest), { persistent: false }, (_eventType, filename) => {
+                const watcher = watch(dirname(configuredDbtManifest), { persistent: false }, (_eventType, filename) => {
+                    if (runtimeClosing)
+                        return;
                     if (!filename || !['manifest.json', 'catalog.json', 'semantic_manifest.json', 'run_results.json'].includes(String(filename)))
                         return;
                     invalidateAgentProjectState(projectRoot);
-                    if (sourceRefreshTimer)
-                        clearTimeout(sourceRefreshTimer);
-                    sourceRefreshTimer = setTimeout(() => {
-                        void refreshUnifiedProjectIndexes(projectRoot).catch(() => undefined);
-                    }, 250);
+                    scheduleProjectRefresh(`dbt:${String(filename)}`);
                     const payload = JSON.stringify({ type: 'dbt-artifacts-changed', path: String(filename) });
                     for (const client of sseClients) {
                         try {
@@ -4543,6 +5164,7 @@ export async function startLocalServer(opts) {
                         }
                     }).catch(() => { });
                 });
+                projectWatchers.push(watcher);
             }
             catch { /* dbt artifact directory not watchable */ }
         }
@@ -4625,11 +5247,15 @@ export async function startLocalServer(opts) {
             result: normalizeQueryResult(result),
             chartConfig: plan?.chartConfig ?? validation.chartConfig ?? null,
             invocation,
+            tests: plan?.tests ?? [],
         };
     };
-    const runBlockStudioTestSummary = async (source, targetConnection) => {
-        const activeConnection = requireActiveConnection(targetConnection);
+    const runBlockStudioTestSummary = async (source, targetConnection, executedPreview) => {
         const start = Date.now();
+        if (executedPreview) {
+            return evaluateBlockStudioTests(executedPreview.tests, executedPreview.result.rows, executedPreview.result.columns, start);
+        }
+        const activeConnection = requireActiveConnection(targetConnection);
         const tableMapping = await resolveSemanticTableMapping(executor, activeConnection, semanticLayer, projectRoot);
         // Run tests against the SAME SQL the preview runs: for a semantic block with a
         // pre-compiled query, that's the query (not a recompiled metric), so the test's
@@ -4674,40 +5300,7 @@ export async function startLocalServer(opts) {
         const columns = Array.isArray(rawResult?.columns)
             ? rawResult.columns.map((column) => typeof column === 'string' ? column : column?.name ?? String(column))
             : [];
-        const assertions = [];
-        let passed = 0;
-        let failed = 0;
-        for (const test of tests) {
-            const name = `assert ${test.field} ${test.operator} ${formatBlockStudioExpected(test.expected)}`;
-            let actual;
-            if (test.field === 'row_count') {
-                actual = rows.length;
-            }
-            else if (!columns.includes(test.field)) {
-                assertions.push({ name, passed: false, expected: test.expected, error: `Column '${test.field}' not found in results` });
-                failed += 1;
-                continue;
-            }
-            else {
-                actual = rows[0]?.[test.field];
-            }
-            const ok = compareBlockStudioValues(actual, test.operator, test.expected);
-            if (ok) {
-                assertions.push({ name, passed: true, actual, expected: test.expected });
-                passed += 1;
-            }
-            else {
-                assertions.push({
-                    name,
-                    passed: false,
-                    actual,
-                    expected: test.expected,
-                    error: `${String(actual)} ${test.operator} ${formatBlockStudioExpected(test.expected)} is false`,
-                });
-                failed += 1;
-            }
-        }
-        return { passed, failed, skipped: 0, duration: Date.now() - start, assertions, runAt: new Date() };
+        return evaluateBlockStudioTests(tests, rows, columns, start);
     };
     const saveDqlGenerationDraft = (importId, candidate) => saveDqlGenerationDraftForProject(projectRoot, importId, candidate);
     const createDqlGenerationSessionFromBody = async (body) => {
@@ -4766,7 +5359,9 @@ export async function startLocalServer(opts) {
             blockers.push(error instanceof Error ? error.message : String(error));
         }
         try {
-            testResults = await runBlockStudioTestSummary(source);
+            testResults = preview
+                ? await runBlockStudioTestSummary(source, undefined, preview)
+                : await runBlockStudioTestSummary(source);
         }
         catch (error) {
             testResults = {
@@ -4923,15 +5518,24 @@ export async function startLocalServer(opts) {
                 writeHead(status, { ...headers, ...validatorHeaders });
                 return end(raw);
             }
-            const gz = gzipSync(raw);
-            writeHead(status, {
-                ...headers,
-                ...validatorHeaders,
-                'Content-Encoding': 'gzip',
-                'Content-Length': gz.byteLength,
-                Vary: 'Accept-Encoding, Origin',
+            gzip(raw, (error, gz) => {
+                if (response.destroyed || response.writableEnded)
+                    return;
+                if (error) {
+                    writeHead(status, { ...headers, ...validatorHeaders });
+                    end(raw);
+                    return;
+                }
+                writeHead(status, {
+                    ...headers,
+                    ...validatorHeaders,
+                    'Content-Encoding': 'gzip',
+                    'Content-Length': gz.byteLength,
+                    Vary: 'Accept-Encoding, Origin',
+                });
+                end(gz);
             });
-            return end(gz);
+            return response;
         });
         return rawResponse;
     };
@@ -4950,7 +5554,7 @@ export async function startLocalServer(opts) {
                 res.setHeader('Access-Control-Allow-Origin', requestOrigin);
             res.setHeader('Vary', 'Origin');
             res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
-            res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+            res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, Idempotency-Key');
             if (!originAllowed && path.startsWith('/api/')) {
                 res.writeHead(403, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({ error: 'Origin is not allowed.' }));
@@ -4985,6 +5589,40 @@ export async function startLocalServer(opts) {
                 res.end(serializeJSON({ status: 'ok', version: runtimeVersion, versionStatus, retrievalHealth }));
                 return;
             }
+            if (req.method === 'GET' && path === '/api/operations/events') {
+                res.writeHead(200, {
+                    'Content-Type': 'text/event-stream',
+                    'Cache-Control': 'no-cache',
+                    'Connection': 'keep-alive',
+                    'X-Accel-Buffering': 'no',
+                });
+                res.write(': connected\n\n');
+                operationSseClients.add(res);
+                for (const operation of operationCoordinator.list(20).reverse()) {
+                    res.write(`event: operation\ndata: ${serializeJSON(operation)}\n\n`);
+                }
+                req.on('close', () => operationSseClients.delete(res));
+                return;
+            }
+            if (req.method === 'GET' && path === '/api/operations') {
+                const limit = Number(url.searchParams.get('limit') ?? 50);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ operations: operationCoordinator.list(limit) }));
+                return;
+            }
+            const operationMatch = path.match(/^\/api\/operations\/([^/]+)$/);
+            if (operationMatch && req.method === 'GET') {
+                const operation = operationCoordinator.get(decodeURIComponent(operationMatch[1]));
+                res.writeHead(operation ? 200 : 404, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(operation ?? { error: 'Operation not found.' }));
+                return;
+            }
+            if (operationMatch && req.method === 'DELETE') {
+                const operation = operationCoordinator.cancel(decodeURIComponent(operationMatch[1]));
+                res.writeHead(operation ? 200 : 404, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(operation ?? { error: 'Operation not found.' }));
+                return;
+            }
             if (req.method === 'GET' && path === '/api/onboarding/launch') {
                 const requestId = apiRequestId('onboarding-launch');
                 const prefs = readUserPrefs(userPrefsPath);
@@ -5593,15 +6231,79 @@ export async function startLocalServer(opts) {
             }
             if (req.method === 'GET' && path === '/api/modeling/dbt-first/inventory') {
                 const requestId = apiRequestId('modeling-inventory');
-                const snapshot = projectSnapshot();
+                const physicalOnly = url.searchParams.get('physicalOnly') === 'true';
+                const modelingEnabled = projectConfig.manifestVersion === 3 && projectConfig.modeling?.mode === 'dbt-first';
+                if (physicalOnly && !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.',
+                        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 (physicalOnly && !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: { manifestPath: configuredManifestPath },
+                        nextActions: ['Run dbt parse, dbt compile, or dbt build, then refresh the database catalog.'],
+                    })));
+                    return;
+                }
+                let snapshot;
+                if (physicalOnly) {
+                    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 the database catalog.'],
+                        })));
+                        return;
+                    }
+                }
+                else {
+                    snapshot = projectSnapshot();
+                }
                 const manifest = snapshot.manifest;
-                const limit = Math.min(200, Math.max(1, Number(url.searchParams.get('limit')) || 50));
+                if (physicalOnly && (manifest.manifestVersion !== 3 || !manifest.modeling || !manifest.dbtProvenance)) {
+                    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 the dbt database catalog.',
+                        details: { manifestPath: configuredManifestPath },
+                        nextActions: ['Review the dbt artifact, rebuild it, then refresh the database catalog.'],
+                    })));
+                    return;
+                }
+                // PERF-001 / CTX-005: only the Database browser opts into the smaller,
+                // physical-relation contract. Existing modeling consumers retain their
+                // original inventory scope and pagination defaults.
+                const maxLimit = physicalOnly ? 100 : 200;
+                const defaultLimit = physicalOnly ? 25 : 50;
+                const limit = Math.min(maxLimit, Math.max(1, Number(url.searchParams.get('limit')) || defaultLimit));
                 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 physicalIds = physicalOnly ? physicalDbtRelationIds(expectedManifestPath) : undefined;
                 const nodes = Object.values(manifest.dbtProvenance?.nodes ?? {})
+                    .filter((node) => !physicalOnly || (Boolean(node.relation) && (!physicalIds || physicalIds.has(node.uniqueId))))
                     .filter((node) => {
                     if (!queryTokens.length)
                         return true;
@@ -5634,6 +6336,11 @@ export async function startLocalServer(opts) {
                     nextCursor: cursor + limit < nodes.length ? cursor + limit : null,
                     total: nodes.length,
                     snapshotId: snapshot.snapshotId,
+                    ...(physicalOnly ? {
+                        manifestPath: manifest.dbtProvenance.manifestPath,
+                        projectName: manifest.dbtProvenance.projectName,
+                        scope: 'dbt_relations',
+                    } : {}),
                 }));
                 return;
             }
@@ -5840,13 +6547,14 @@ export async function startLocalServer(opts) {
                     return;
                 }
                 const sourceSql = repairableSqlFromAgentRun(sourceRun);
+                const sourceDqlArtifact = repairableDqlArtifactFromAgentRun(sourceRun);
                 const retainedFailure = warehouseFailureFromAgentRun(sourceRun);
-                if (!sourceSql || !analyticalFailureAllowsDeterministicRetry(retainedFailure)) {
+                if ((!sourceSql && !sourceDqlArtifact) || !analyticalFailureAllowsDeterministicRetry(retainedFailure)) {
                     res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({
-                        error: sourceSql
+                        error: sourceSql || sourceDqlArtifact
                             ? 'This failure requires authorized access or a policy change and cannot be repaired by AI.'
-                            : 'This run has no retained SQL statement to repair.',
+                            : 'This run has no retained SQL statement or editable DQL artifact to repair.',
                         ...(retainedFailure ? { warehouseFailure: retainedFailure } : {}),
                     }));
                     return;
@@ -5870,97 +6578,40 @@ export async function startLocalServer(opts) {
                     : sourceRun.executionTarget?.target === 'local'
                         ? 'local'
                         : projectConfig.defaultConnectionName;
-                let result;
-                let repairedSql = sourceSql;
-                let repairMode = 'deterministic';
-                let firstFailure;
+                let repaired;
                 try {
-                    result = await executeGeneratedSqlDirect(sourceRun.question, sourceSql, undefined, targetConnection);
+                    // Prefer the editable DQL contract even when the failed run also
+                    // retained compiled SQL. This keeps parameters, visualization, tests,
+                    // and the corrected wrapper attached to the repaired Ask result.
+                    repaired = sourceDqlArtifact
+                        ? await executeBoundedDqlRepair({
+                            question: sourceRun.question,
+                            source: sourceDqlArtifact.source,
+                            failure: retainedFailure?.redactedMessage
+                                ?? sourceRun.diagnosticReceipt?.failure?.message
+                                ?? sourceRun.summary,
+                            targetConnection,
+                            targetConnectionName,
+                            parameters: sourceDqlArtifact.parameterValues,
+                            artifactName: sourceDqlArtifact.name,
+                        })
+                        : await executeBoundedSqlRepair({
+                            question: sourceRun.question,
+                            sourceSql: sourceSql,
+                            targetConnection,
+                            targetConnectionName,
+                        });
                 }
                 catch (error) {
-                    firstFailure = normalizeWarehouseSqlFailure(error, targetConnection.driver);
-                }
-                if (!result) {
-                    if (firstFailure?.retryDisposition !== 'model_repair') {
-                        res.writeHead(422, { 'Content-Type': 'application/json; charset=utf-8' });
-                        res.end(serializeJSON({
-                            error: firstFailure?.redactedMessage ?? 'The deterministic repair did not produce an executable query.',
-                            ...(firstFailure ? { warehouseFailure: firstFailure } : {}),
-                        }));
-                        return;
-                    }
-                    const provider = await createBlockStudioAssistProvider(projectRoot);
-                    if (!provider) {
-                        res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
-                        res.end(serializeJSON({ error: 'Configure an available AI provider in Settings to repair this query.' }));
-                        return;
-                    }
-                    let schemaContext;
-                    try {
-                        schemaContext = await getSchemaContextForAgent(sourceRun.question, undefined, targetConnection, targetConnectionName);
-                    }
-                    catch (error) {
-                        const failure = normalizeWarehouseSqlFailure(error, targetConnection.driver);
-                        res.writeHead(422, { 'Content-Type': 'application/json; charset=utf-8' });
-                        res.end(serializeJSON({ error: failure.redactedMessage, warehouseFailure: failure }));
-                        return;
-                    }
-                    const boundedSchema = schemaContext.slice(0, 16).map((table) => ({
-                        relation: table.relation,
-                        columns: table.columns.slice(0, 40).map((column) => ({ name: column.name, type: column.type })),
+                    const repairError = error;
+                    res.writeHead(repairError.status ?? 500, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({
+                        error: repairError.message,
+                        ...(repairError.warehouseFailure ? { warehouseFailure: repairError.warehouseFailure } : {}),
                     }));
-                    let raw;
-                    try {
-                        raw = await provider.generate([
-                            {
-                                role: 'system',
-                                content: [
-                                    'Repair one failed read-only analytical SQL statement.',
-                                    'Return exactly one JSON object in a ```json fence with keys summary, sql, viz, outputs.',
-                                    'Preserve the user question, selected grain, filters, and aggregation semantics.',
-                                    'Use only relations and columns present in the supplied schema context.',
-                                    'Never emit internal DQL relation identities such as source::, model::, seed::, or snapshot::.',
-                                    'Do not add writes, DDL, multiple statements, or commentary outside the JSON fence.',
-                                ].join(' '),
-                            },
-                            {
-                                role: 'user',
-                                content: JSON.stringify({
-                                    question: sourceRun.question,
-                                    driver: targetConnection.driver,
-                                    failure: firstFailure.redactedMessage,
-                                    sql: sourceSql,
-                                    schema: boundedSchema,
-                                }),
-                            },
-                        ], { maxTokens: 1200, temperature: 0 });
-                    }
-                    catch {
-                        res.writeHead(502, { 'Content-Type': 'application/json; charset=utf-8' });
-                        res.end(serializeJSON({ error: 'The AI provider could not complete this repair. Check Provider Settings and retry.' }));
-                        return;
-                    }
-                    const proposal = parseProposal(raw);
-                    if (!proposal.sql?.trim()) {
-                        res.writeHead(422, { 'Content-Type': 'application/json; charset=utf-8' });
-                        res.end(serializeJSON({ error: 'The AI repair did not return an executable SQL statement.' }));
-                        return;
-                    }
-                    repairedSql = proposal.sql.trim();
-                    repairMode = 'ai';
-                    try {
-                        result = await executeGeneratedSqlDirect(sourceRun.question, repairedSql, undefined, targetConnection);
-                    }
-                    catch (error) {
-                        const failure = normalizeWarehouseSqlFailure(error, targetConnection.driver);
-                        res.writeHead(422, { 'Content-Type': 'application/json; charset=utf-8' });
-                        res.end(serializeJSON({
-                            error: failure.redactedMessage,
-                            warehouseFailure: failure,
-                        }));
-                        return;
-                    }
+                    return;
                 }
+                const { result, repairedSql, repairMode, firstFailure } = repaired;
                 const completedAt = new Date().toISOString();
                 const preview = agentResultToSynthesisPreview(result);
                 const synthesis = await synthesizeAnswer({
@@ -5972,6 +6623,8 @@ export async function startLocalServer(opts) {
                     ...(preview ? { columnFormats: agentColumnDisplayFormats(projectRoot, preview.columns) } : {}),
                 });
                 const sourceFailure = analyticalFailedRunFromAgentRun(sourceRun)?.failure;
+                const presentationContext = repairPresentationContextFromAgentRun(sourceRun);
+                const executionResultFingerprint = result.executionReceipt?.resultFingerprint;
                 const artifact = agentRunArtifact('answer', 'Repaired analytical answer', {
                     kind: 'uncertified',
                     certification: 'analyst_review_required',
@@ -5979,13 +6632,31 @@ export async function startLocalServer(opts) {
                     trustLabel: 'AI-generated · review required',
                     answer: synthesis.text,
                     text: synthesis.text,
+                    ...presentationContext,
                     result,
                     proposedSql: repairedSql,
                     sql: result.sql ?? repairedSql,
                     dqlArtifact: result.dqlArtifact,
+                    diagnosticReceipt: {
+                        version: 1,
+                        phase: 'run.completed',
+                        route: 'generated_answer',
+                        repair: {
+                            attempt: 1,
+                            mode: repairMode,
+                            sourceRunId: sourceRun.id,
+                            targetPreserved: true,
+                            readOnly: true,
+                        },
+                        execution: {
+                            rowCount: result.rowCount,
+                            ...(executionResultFingerprint ? { resultFingerprint: executionResultFingerprint } : {}),
+                        },
+                    },
                     previousAttempt: {
                         sourceRunId: sourceRun.id,
-                        sql: sourceSql,
+                        ...(sourceSql ? { sql: sourceSql } : {}),
+                        ...(sourceDqlArtifact?.source ? { dql: sourceDqlArtifact.source } : {}),
                         failure: retainedFailure ?? firstFailure,
                     },
                     repair: { attempt: 1, mode: repairMode },
@@ -6168,39 +6839,83 @@ 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, process.env, getActiveProvider(projectRoot))),
-                    ]);
                     if (runId)
                         activeAgentRunControllers.set(runId, runController);
+                    let streamConnected = true;
+                    res.on('close', () => { streamConnected = false; });
+                    const writeStream = (event, data) => {
+                        if (!streamConnected || res.destroyed || res.writableEnded)
+                            return;
+                        try {
+                            writeAgentRunSse(res, event, data);
+                        }
+                        catch {
+                            streamConnected = false;
+                        }
+                    };
+                    if (wantsStream) {
+                        res.writeHead(200, {
+                            'Content-Type': 'text/event-stream; charset=utf-8',
+                            'Cache-Control': 'no-cache',
+                            'Connection': 'keep-alive',
+                            'X-Accel-Buffering': 'no',
+                        });
+                    }
+                    const operation = runId ? operationCoordinator.create({
+                        type: 'agent_run',
+                        scope: `agent-run:${runId}`,
+                        resourceRevision: parsed.request.threadId,
+                        message: 'AI request accepted. You can change pages while it runs.',
+                        cancellable: true,
+                    }) : null;
+                    if (wantsStream)
+                        writeStream('agent-run-accepted', { runId, operationId: operation?.id });
+                    let completedRun;
+                    let runError;
                     try {
+                        const executeRun = async (operationSignal, report) => {
+                            parsed.request.signal = AbortSignal.any([
+                                runController.signal,
+                                ...(operationSignal ? [operationSignal] : []),
+                                AbortSignal.timeout(agentRunDeadlineMs(parsed.request, process.env, getActiveProvider(projectRoot))),
+                            ]);
+                            report?.({ phase: 'reasoning', progress: 8, message: 'Grounding the request and selecting the governed route.' });
+                            try {
+                                const run = await agentRunEngine.run(parsed.request, (event) => {
+                                    if (wantsStream)
+                                        writeStream('agent-run-event', event);
+                                    report?.({ phase: event.type, progress: 45, message: event.message });
+                                }, (delta) => {
+                                    if (wantsStream)
+                                        writeStream('agent-run-answer-delta', { runId: parsed.request.runId, delta });
+                                });
+                                completedRun = run;
+                                recordConversationTurn(conversationStore, parsed.request.threadId, run);
+                                return { runId: run.id, threadId: parsed.request.threadId, status: run.status };
+                            }
+                            catch (error) {
+                                runError = error;
+                                throw error;
+                            }
+                        };
+                        if (operation)
+                            await operationCoordinator.run(operation.id, (signal, report) => executeRun(signal, report));
+                        else
+                            await executeRun();
+                        if (runError)
+                            throw runError;
+                        if (!completedRun)
+                            throw new Error('The AI request ended before producing a stored run.');
                         if (wantsStream) {
-                            res.writeHead(200, {
-                                'Content-Type': 'text/event-stream; charset=utf-8',
-                                'Cache-Control': 'no-cache',
-                                'Connection': 'keep-alive',
-                                'X-Accel-Buffering': 'no',
-                            });
-                            const run = await agentRunEngine.run(parsed.request, (event) => {
-                                writeAgentRunSse(res, 'agent-run-event', event);
-                            }, (delta) => {
-                                writeAgentRunSse(res, 'agent-run-answer-delta', { runId: parsed.request.runId, delta });
-                            });
-                            recordConversationTurn(conversationStore, parsed.request.threadId, run);
-                            // The terminal frame carried the whole stored run — 2.4 MB on a real
-                            // question, of which the renderable part was ~3 KB. The rest was the
-                            // same artifacts repeated four times over. The client renders from
-                            // the projection and fetches the full record from the run-state
-                            // route only if something needs it.
-                            writeAgentRunSse(res, 'agent-run-complete', slimAgentRunForTransport(run));
-                            res.end();
+                            // The complete stored run stays in the run-state route; the live
+                            // stream ships only the renderable transport projection.
+                            writeStream('agent-run-complete', slimAgentRunForTransport(completedRun));
+                            if (streamConnected && !res.writableEnded)
+                                res.end();
                             return;
                         }
-                        const run = await agentRunEngine.run(parsed.request);
-                        recordConversationTurn(conversationStore, parsed.request.threadId, run);
                         res.writeHead(201, { 'Content-Type': 'application/json; charset=utf-8' });
-                        res.end(serializeJSON({ run }));
+                        res.end(serializeJSON({ run: completedRun }));
                     }
                     finally {
                         if (runId)
@@ -6210,8 +6925,10 @@ export async function startLocalServer(opts) {
                 catch (error) {
                     const message = error instanceof Error ? error.message : String(error);
                     if (res.headersSent) {
-                        writeAgentRunSse(res, 'agent-run-error', { error: message });
-                        res.end();
+                        if (!res.destroyed && !res.writableEnded) {
+                            writeAgentRunSse(res, 'agent-run-error', { error: message });
+                            res.end();
+                        }
                     }
                     else {
                         res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
@@ -7883,9 +8600,14 @@ export async function startLocalServer(opts) {
                         ? body.variables
                         : {};
                     const dashboardVariables = dashboardRuntimeVariables(loaded.dashboard, variables);
+                    const requestedTileId = typeof body.tileId === 'string' && body.tileId.trim()
+                        ? body.tileId.trim()
+                        : undefined;
                     const tiles = [];
                     let localApps = null;
                     for (const item of loaded.dashboard.layout.items) {
+                        if (requestedTileId && item.i !== requestedTileId)
+                            continue;
                         if (item.text) {
                             tiles.push({
                                 tileId: item.i,
@@ -7973,9 +8695,194 @@ export async function startLocalServer(opts) {
                                     kind: 'ai_pin',
                                     name: pin.title,
                                 },
+                                artifact: {
+                                    version: 1,
+                                    sourceKind: 'ai_pin',
+                                    name: pinArtifact?.name ?? pin.title,
+                                    ...(pinArtifact?.sourcePath ? { sourcePath: pinArtifact.sourcePath } : {}),
+                                    ...(pinArtifact?.source ? { dql: pinArtifact.source.slice(0, 40_000) } : {}),
+                                    ...(pinArtifact?.compiledSql || pin.sql ? { sql: (pinArtifact?.compiledSql ?? pin.sql).slice(0, 40_000) } : {}),
+                                    trustState: pinArtifact?.trustState === 'certified' || pin.certification === 'certified'
+                                        ? 'certified'
+                                        : 'review_required',
+                                    explanation: [
+                                        'This result comes from a saved App insight.',
+                                        pinArtifact ? 'The DQL artifact was executed again with the current App parameters.' : 'The saved bounded result is displayed with its original trust state.',
+                                    ],
+                                    executionTarget: executionTargetDescriptor(body),
+                                },
                             });
                             continue;
                         }
+                        if (item.draftAnalysis) {
+                            let draftSource;
+                            let draftAppRelativePath;
+                            let draftParameters = {};
+                            let draftTargetConnection;
+                            let draftRepairPlan;
+                            try {
+                                const draftPath = join(loaded.appDir, item.draftAnalysis.ref);
+                                draftAppRelativePath = relative(loaded.appDir, draftPath);
+                                if (draftAppRelativePath.startsWith('..') || draftAppRelativePath.startsWith('/')) {
+                                    throw new Error('App-scoped analysis reference escapes the App directory.');
+                                }
+                                draftSource = readFileSync(draftPath, 'utf-8');
+                                const fingerprint = `sha256:${createHash('sha256').update(draftSource).digest('hex')}`;
+                                if (fingerprint !== item.draftAnalysis.artifactFingerprint) {
+                                    throw new Error('App-scoped analysis changed after approval. Review the draft again.');
+                                }
+                                draftParameters = dashboardTileParameterValues({
+                                    item,
+                                    dashboardValues: dashboardVariables,
+                                    requestValues: variables,
+                                });
+                                draftTargetConnection = isConnectionConfig(body.connection)
+                                    ? body.connection
+                                    : connection ?? undefined;
+                                draftRepairPlan = buildExecutionPlan({ id: item.i, type: 'dql', source: draftSource, title: item.title ?? item.i }, {
+                                    semanticLayer,
+                                    driver: draftTargetConnection?.driver ?? 'duckdb',
+                                    parameters: draftParameters,
+                                });
+                                let result;
+                                let repair;
+                                let repairedSql;
+                                let repairedDql;
+                                try {
+                                    result = await executeDqlArtifactSourceForAgent(draftSource, { name: item.title ?? item.i, path: draftAppRelativePath }, { question: item.title, parameters: draftParameters });
+                                }
+                                catch (executionError) {
+                                    const repaired = await repairFailedAppTileExecution({
+                                        source: 'draft_analysis',
+                                        question: item.title ?? item.i,
+                                        sourceSql: draftRepairPlan?.sql,
+                                        sourceDql: draftSource,
+                                        artifactName: item.title ?? item.i,
+                                        error: executionError,
+                                        targetConnection: draftTargetConnection,
+                                        targetConnectionName: projectConfig.defaultConnectionName,
+                                        sqlParams: draftRepairPlan?.sqlParams,
+                                        variables: { ...(draftRepairPlan?.variables ?? {}), ...draftParameters },
+                                    });
+                                    if (!repaired.ok) {
+                                        tiles.push({
+                                            tileId: item.i,
+                                            status: 'error',
+                                            tileType: 'draftAnalysis',
+                                            title: item.title ?? item.i,
+                                            error: executionError instanceof Error ? executionError.message : String(executionError),
+                                            trustState: 'review_required',
+                                            repair: repaired.repair,
+                                            artifact: {
+                                                version: 1,
+                                                sourceKind: 'draft_analysis',
+                                                name: item.title ?? item.i,
+                                                sourcePath: draftAppRelativePath,
+                                                dql: draftSource.slice(0, 40_000),
+                                                ...(draftRepairPlan?.sql ? { sql: draftRepairPlan.sql.slice(0, 40_000) } : {}),
+                                                trustState: 'review_required',
+                                                explanation: ['This App-scoped analysis remains review-required.', 'Automatic repair could not produce a safe executable result.'],
+                                                executionTarget: executionTargetDescriptor(body),
+                                            },
+                                        });
+                                        continue;
+                                    }
+                                    result = repaired.result;
+                                    repair = repaired.repair;
+                                    repairedSql = repaired.repairedSql;
+                                    repairedDql = repaired.repairedDql;
+                                }
+                                tiles.push({
+                                    tileId: item.i,
+                                    status: 'ok',
+                                    tileType: 'draftAnalysis',
+                                    title: item.title ?? item.i,
+                                    viz: item.viz,
+                                    chartConfig: mergeDashboardChartConfig(result.chartConfig, item),
+                                    result,
+                                    trustState: 'review_required',
+                                    citation: { kind: repair ? 'app_draft_analysis_repaired' : 'app_draft_analysis', name: item.title ?? item.i, path: draftAppRelativePath },
+                                    ...(repair ? { repair } : {}),
+                                    artifact: {
+                                        version: 1,
+                                        sourceKind: 'draft_analysis',
+                                        name: item.title ?? item.i,
+                                        sourcePath: draftAppRelativePath,
+                                        dql: (repairedDql ?? draftSource).slice(0, 40_000),
+                                        ...(repairedSql ?? draftRepairPlan?.sql ? { sql: (repairedSql ?? draftRepairPlan.sql).slice(0, 40_000) } : {}),
+                                        trustState: 'review_required',
+                                        explanation: [
+                                            'This is private App analysis and remains review-required.',
+                                            repair ? 'A bounded repair ran on the original data target without changing the saved source file.' : 'The saved App-scoped DQL was executed with the current filters.',
+                                        ],
+                                        executionTarget: executionTargetDescriptor(body),
+                                    },
+                                });
+                            }
+                            catch (err) {
+                                const repaired = await repairFailedAppTileExecution({
+                                    source: 'draft_analysis',
+                                    question: item.title ?? item.i,
+                                    sourceSql: draftRepairPlan?.sql,
+                                    sourceDql: draftSource,
+                                    artifactName: item.title ?? item.i,
+                                    error: err,
+                                    targetConnection: draftTargetConnection,
+                                    targetConnectionName: projectConfig.defaultConnectionName,
+                                    sqlParams: draftRepairPlan?.sqlParams,
+                                    variables: { ...(draftRepairPlan?.variables ?? {}), ...draftParameters },
+                                });
+                                if (repaired.ok && draftSource) {
+                                    tiles.push({
+                                        tileId: item.i,
+                                        status: 'ok',
+                                        tileType: 'draftAnalysis',
+                                        title: item.title ?? item.i,
+                                        viz: item.viz,
+                                        chartConfig: mergeDashboardChartConfig(repaired.result.chartConfig, item),
+                                        result: repaired.result,
+                                        trustState: 'review_required',
+                                        citation: { kind: 'app_draft_analysis_repaired', name: item.title ?? item.i, path: draftAppRelativePath },
+                                        repair: repaired.repair,
+                                        artifact: {
+                                            version: 1,
+                                            sourceKind: 'draft_analysis',
+                                            name: item.title ?? item.i,
+                                            ...(draftAppRelativePath ? { sourcePath: draftAppRelativePath } : {}),
+                                            dql: (repaired.repairedDql ?? draftSource).slice(0, 40_000),
+                                            sql: repaired.repairedSql.slice(0, 40_000),
+                                            trustState: 'review_required',
+                                            explanation: ['A bounded DQL repair executed on the original data target. The saved App analysis was not changed.'],
+                                            executionTarget: executionTargetDescriptor(body),
+                                        },
+                                    });
+                                    continue;
+                                }
+                                tiles.push({
+                                    tileId: item.i,
+                                    status: 'error',
+                                    tileType: 'draftAnalysis',
+                                    title: item.title ?? item.i,
+                                    error: err instanceof Error ? err.message : String(err),
+                                    trustState: 'review_required',
+                                    repair: repaired.repair,
+                                    ...(draftSource ? {
+                                        artifact: {
+                                            version: 1,
+                                            sourceKind: 'draft_analysis',
+                                            name: item.title ?? item.i,
+                                            ...(draftAppRelativePath ? { sourcePath: draftAppRelativePath } : {}),
+                                            dql: draftSource.slice(0, 40_000),
+                                            ...(draftRepairPlan?.sql ? { sql: draftRepairPlan.sql.slice(0, 40_000) } : {}),
+                                            trustState: 'review_required',
+                                            explanation: ['Automatic repair could not produce a safe executable result. The saved App analysis was not changed.'],
+                                            executionTarget: executionTargetDescriptor(body),
+                                        },
+                                    } : {}),
+                                });
+                            }
+                            continue;
+                        }
                         if (item.semantic) {
                             try {
                                 if (!semanticLayer)
@@ -8016,16 +8923,69 @@ export async function startLocalServer(opts) {
                                 if (!composed)
                                     throw new Error('The governed semantic query could not be composed.');
                                 const prepared = prepareLocalExecution(composed.sql, targetConnection, projectRoot, projectConfig);
-                                const result = await executor.executeQuery(prepared.sql, [], {}, prepared.connection);
+                                let normalizedResult;
+                                let repair;
+                                let executedSql = composed.sql;
+                                try {
+                                    const result = await executor.executeQuery(prepared.sql, [], {}, prepared.connection);
+                                    normalizedResult = normalizeQueryResult(result);
+                                }
+                                catch (executionError) {
+                                    const repaired = await repairFailedAppTileExecution({
+                                        source: 'semantic_query',
+                                        question: item.title ?? item.semantic.id,
+                                        sourceSql: composed.sql,
+                                        error: executionError,
+                                        targetConnection,
+                                    });
+                                    if (!repaired.ok) {
+                                        tiles.push({
+                                            tileId: item.i,
+                                            status: 'error',
+                                            tileType: 'semantic',
+                                            title: item.title ?? item.semantic.id,
+                                            error: executionError instanceof Error ? executionError.message : String(executionError),
+                                            trustState: 'review_required',
+                                            repair: repaired.repair,
+                                            artifact: {
+                                                version: 1,
+                                                sourceKind: 'semantic_query',
+                                                name: item.title ?? item.semantic.id,
+                                                sql: composed.sql.slice(0, 40_000),
+                                                trustState: 'review_required',
+                                                explanation: ['Automatic repair could not execute the governed semantic query safely.'],
+                                                executionTarget: executionTargetDescriptor(body),
+                                            },
+                                        });
+                                        continue;
+                                    }
+                                    normalizedResult = normalizeQueryResult(repaired.result);
+                                    repair = repaired.repair;
+                                    executedSql = repaired.repairedSql;
+                                }
                                 tiles.push({
                                     tileId: item.i,
                                     status: 'ok',
                                     tileType: 'semantic',
                                     title: item.title ?? item.semantic.id,
                                     viz: item.viz,
-                                    result: normalizeQueryResult(result),
+                                    result: normalizedResult,
                                     trustState: 'review_required',
-                                    citation: { kind: 'semantic_query', name: item.semantic.id },
+                                    citation: { kind: repair ? 'semantic_query_repaired' : 'semantic_query', name: item.semantic.id },
+                                    ...(repair ? { repair } : {}),
+                                    artifact: {
+                                        version: 1,
+                                        sourceKind: 'semantic_query',
+                                        name: item.title ?? item.semantic.id,
+                                        sql: executedSql.slice(0, 40_000),
+                                        trustState: 'review_required',
+                                        explanation: [
+                                            `Metrics: ${item.semantic.metrics.join(', ') || 'none'}.`,
+                                            `Dimensions: ${item.semantic.dimensions?.join(', ') || 'none'}.`,
+                                            repair ? 'The composed SQL needed bounded repair and therefore remains review-required.' : 'The governed semantic intent was composed for the active warehouse and remains review-required until approval.',
+                                        ],
+                                        executionTarget: executionTargetDescriptor(body),
+                                    },
                                 });
                             }
                             catch (err) {
@@ -8050,6 +9010,11 @@ export async function startLocalServer(opts) {
                             });
                             continue;
                         }
+                        let blockSource;
+                        let blockTargetConnection;
+                        let blockPlan;
+                        let blockFilterApplication;
+                        let blockInvocation;
                         try {
                             assertAppAccess({
                                 app: loaded.app,
@@ -8057,55 +9022,55 @@ export async function startLocalServer(opts) {
                                 level: 'execute',
                             });
                             const absBlockPath = join(projectRoot, block.filePath);
-                            const source = readFileSync(absBlockPath, 'utf-8');
-                            const targetConnection = isConnectionConfig(body.connection) ? body.connection : connection;
-                            const tableMapping = await resolveSemanticTableMapping(executor, targetConnection, semanticLayer, projectRoot);
+                            blockSource = readFileSync(absBlockPath, 'utf-8');
+                            blockTargetConnection = requireActiveConnection(isConnectionConfig(body.connection) ? body.connection : connection);
+                            const tableMapping = await resolveSemanticTableMapping(executor, blockTargetConnection, semanticLayer, projectRoot);
                             const boundParameters = dashboardTileParameterValues({
                                 item,
                                 dashboardValues: dashboardVariables,
                                 requestValues: variables,
                             });
-                            const invocation = prepareBlockInvocation({
+                            blockInvocation = prepareBlockInvocation({
                                 block: block.name,
-                                source,
+                                source: blockSource,
                                 parameters: { ...dashboardVariables, ...boundParameters },
                                 parameterSources: Object.fromEntries(Object.keys(boundParameters).map((name) => [name, 'surface'])),
                                 surface: 'app',
                             });
-                            if (invocation.errors.length || invocation.unresolvedParameters.length) {
+                            if (blockInvocation.errors.length || blockInvocation.unresolvedParameters.length) {
                                 tiles.push({
                                     tileId: item.i,
                                     status: 'unresolved',
                                     tileType: 'block',
                                     blockId: block.name,
                                     title: item.title ?? block.name,
-                                    error: invocation.errors[0] ?? `Needs values for: ${invocation.unresolvedParameters.join(', ')}`,
+                                    error: blockInvocation.errors[0] ?? `Needs values for: ${blockInvocation.unresolvedParameters.join(', ')}`,
                                     invocation: {
-                                        resolvedParameters: invocation.resolvedParameters,
-                                        unresolvedParameters: invocation.unresolvedParameters,
-                                        auditId: invocation.auditId,
+                                        resolvedParameters: blockInvocation.resolvedParameters,
+                                        unresolvedParameters: blockInvocation.unresolvedParameters,
+                                        auditId: blockInvocation.auditId,
                                     },
                                 });
                                 continue;
                             }
                             const semanticCompose = semanticLayer
-                                ? await composeSemanticBlockSqlForRuntime(source, semanticLayer, {
-                                    driver: targetConnection.driver,
+                                ? await composeSemanticBlockSqlForRuntime(blockSource, semanticLayer, {
+                                    driver: blockTargetConnection.driver,
                                     tableMapping,
                                     projectRoot,
                                     projectConfig,
                                     detectedProvider: semanticDetectedProvider,
-                                    parameters: invocation.values,
+                                    parameters: blockInvocation.values,
                                 })
                                 : null;
-                            const plan = buildExecutionPlan({ id: item.i, type: 'dql', source, title: item.title ?? block.name }, {
+                            blockPlan = buildExecutionPlan({ id: item.i, type: 'dql', source: blockSource, title: item.title ?? block.name }, {
                                 semanticLayer,
-                                driver: targetConnection.driver,
+                                driver: blockTargetConnection.driver,
                                 tableMapping,
-                                parameters: invocation.values,
+                                parameters: blockInvocation.values,
                                 semanticSql: semanticCompose?.sql ?? undefined,
                             });
-                            if (!plan && !semanticCompose?.sql) {
+                            if (!blockPlan && !semanticCompose?.sql) {
                                 tiles.push({
                                     tileId: item.i,
                                     status: 'error',
@@ -8114,15 +9079,15 @@ export async function startLocalServer(opts) {
                                 });
                                 continue;
                             }
-                            const filterApplication = applyDashboardFiltersToBlockExecution({
-                                sql: semanticCompose?.sql ?? plan.sql,
-                                sqlParams: plan?.sqlParams ?? [],
-                                variables: { ...(plan?.variables ?? {}), ...dashboardVariables },
+                            blockFilterApplication = applyDashboardFiltersToBlockExecution({
+                                sql: semanticCompose?.sql ?? blockPlan.sql,
+                                sqlParams: blockPlan?.sqlParams ?? [],
+                                variables: { ...(blockPlan?.variables ?? {}), ...dashboardVariables },
                                 block,
                                 dashboard: loaded.dashboard,
                             });
-                            const prepared = prepareLocalExecution(filterApplication.sql, targetConnection, projectRoot, projectConfig);
-                            const result = await executor.executeQuery(prepared.sql, filterApplication.sqlParams, runtimeVariables({ ...filterApplication.variables, ...invocation.values }), prepared.connection);
+                            const prepared = prepareLocalExecution(blockFilterApplication.sql, blockTargetConnection, projectRoot, projectConfig);
+                            const result = await executor.executeQuery(prepared.sql, blockFilterApplication.sqlParams, runtimeVariables({ ...blockFilterApplication.variables, ...blockInvocation.values }), prepared.connection);
                             tiles.push({
                                 tileId: item.i,
                                 status: 'ok',
@@ -8131,22 +9096,37 @@ export async function startLocalServer(opts) {
                                 certificationStatus: block.status ?? null,
                                 title: item.title ?? block.name,
                                 viz: item.viz,
-                                chartConfig: mergeDashboardChartConfig(plan?.chartConfig, item),
+                                chartConfig: mergeDashboardChartConfig(blockPlan?.chartConfig, item),
                                 result: normalizeQueryResult(result),
                                 filters: {
-                                    applied: filterApplication.appliedFilters,
-                                    skipped: filterApplication.skippedFilters,
+                                    applied: blockFilterApplication.appliedFilters,
+                                    skipped: blockFilterApplication.skippedFilters,
                                 },
                                 invocation: {
-                                    resolvedParameters: invocation.resolvedParameters,
-                                    unresolvedParameters: invocation.unresolvedParameters,
-                                    auditId: invocation.auditId,
+                                    resolvedParameters: blockInvocation.resolvedParameters,
+                                    unresolvedParameters: blockInvocation.unresolvedParameters,
+                                    auditId: blockInvocation.auditId,
                                 },
+                                trustState: block.status === 'certified' ? 'certified' : 'review_required',
                                 citation: {
                                     kind: 'block',
                                     name: block.name,
                                     path: block.filePath,
                                 },
+                                artifact: {
+                                    version: 1,
+                                    sourceKind: 'certified_block',
+                                    name: block.name,
+                                    sourcePath: block.filePath,
+                                    dql: blockSource.slice(0, 40_000),
+                                    sql: blockFilterApplication.sql.slice(0, 40_000),
+                                    trustState: block.status === 'certified' ? 'certified' : 'review_required',
+                                    explanation: [
+                                        block.status === 'certified' ? 'This tile executed a certified project block.' : 'This project block is not certified and remains review-required.',
+                                        'Dashboard filters and typed parameters were bound before read-only execution.',
+                                    ],
+                                    executionTarget: executionTargetDescriptor(body),
+                                },
                             });
                         }
                         catch (err) {
@@ -8159,11 +9139,87 @@ export async function startLocalServer(opts) {
                                 });
                             }
                             else {
+                                const repaired = await repairFailedAppTileExecution({
+                                    source: 'certified_block',
+                                    question: item.title ?? block.name,
+                                    sourceSql: blockFilterApplication?.sql ?? blockPlan?.sql,
+                                    sourceDql: blockSource,
+                                    artifactName: block.name,
+                                    error: err,
+                                    targetConnection: blockTargetConnection,
+                                    targetConnectionName: projectConfig.defaultConnectionName,
+                                    sqlParams: blockFilterApplication?.sqlParams ?? blockPlan?.sqlParams,
+                                    variables: {
+                                        ...(blockPlan?.variables ?? {}),
+                                        ...(blockFilterApplication?.variables ?? {}),
+                                        ...(blockInvocation?.values ?? {}),
+                                    },
+                                });
+                                if (repaired.ok) {
+                                    tiles.push({
+                                        tileId: item.i,
+                                        status: 'ok',
+                                        tileType: 'block',
+                                        blockId: block.name,
+                                        blockPath: block.filePath,
+                                        certificationStatus: block.status ?? null,
+                                        title: item.title ?? block.name,
+                                        viz: item.viz,
+                                        chartConfig: mergeDashboardChartConfig(blockPlan?.chartConfig, item),
+                                        result: normalizeQueryResult(repaired.result),
+                                        ...(blockFilterApplication ? {
+                                            filters: {
+                                                applied: blockFilterApplication.appliedFilters,
+                                                skipped: blockFilterApplication.skippedFilters,
+                                            },
+                                        } : {}),
+                                        ...(blockInvocation ? {
+                                            invocation: {
+                                                resolvedParameters: blockInvocation.resolvedParameters,
+                                                unresolvedParameters: blockInvocation.unresolvedParameters,
+                                                auditId: blockInvocation.auditId,
+                                            },
+                                        } : {}),
+                                        trustState: 'review_required',
+                                        repair: repaired.repair,
+                                        citation: { kind: 'block_repaired', name: block.name, path: block.filePath },
+                                        artifact: {
+                                            version: 1,
+                                            sourceKind: 'certified_block',
+                                            name: block.name,
+                                            sourcePath: block.filePath,
+                                            ...(repaired.repairedDql ?? blockSource ? { dql: (repaired.repairedDql ?? blockSource).slice(0, 40_000) } : {}),
+                                            sql: repaired.repairedSql.slice(0, 40_000),
+                                            trustState: 'review_required',
+                                            explanation: [
+                                                'The saved certified block was not changed.',
+                                                'A bounded repair executed on the original data target; this repaired result requires human review.',
+                                            ],
+                                            executionTarget: executionTargetDescriptor(body),
+                                        },
+                                    });
+                                    continue;
+                                }
                                 tiles.push({
                                     tileId: item.i,
                                     status: 'error',
+                                    tileType: 'block',
                                     blockId: block.name,
                                     error: err instanceof Error ? err.message : String(err),
+                                    repair: repaired.repair,
+                                    ...(blockSource ? {
+                                        artifact: {
+                                            version: 1,
+                                            sourceKind: 'certified_block',
+                                            name: block.name,
+                                            sourcePath: block.filePath,
+                                            dql: blockSource.slice(0, 40_000),
+                                            ...(blockFilterApplication?.sql ?? blockPlan?.sql ? { sql: (blockFilterApplication?.sql ?? blockPlan.sql).slice(0, 40_000) } : {}),
+                                            trustState: 'review_required',
+                                            explanation: ['Automatic repair could not produce a safe executable result. The saved block was not changed.'],
+                                            executionTarget: executionTargetDescriptor(body),
+                                        },
+                                    } : {}),
                                 });
                             }
                         }
@@ -8198,6 +9254,10 @@ export async function startLocalServer(opts) {
                         filterFingerprint,
                         resultFingerprint,
                         personaFingerprint,
+                        successfulTileIds: tiles.filter((tile) => tile.status === 'ok').map((tile) => tile.tileId),
+                        semanticApprovalEligibleTileIds: tiles.filter((tile) => (tile.status === 'ok'
+                            && tile.tileType === 'semantic'
+                            && (!('repair' in tile) || tile.repair?.approvalEligible !== false))).map((tile) => tile.tileId),
                         facts: storyResult.facts,
                         story: storyResult.story,
                         expiresAt: Date.now() + 15 * 60_000,
@@ -8249,7 +9309,30 @@ export async function startLocalServer(opts) {
                         // Two-phase app build gap-fill: bounded governed answers for uncovered
                         // questions. Throws when no provider is configured — propose degrades
                         // gracefully by listing the gap instead.
-                        generateGovernedAnswer: (question) => runGovernedAgentAnswerForRun({ question }),
+                        generateGovernedAnswer: (question, appContext) => generateAppBuildAnswerWithRepair(question, appContext),
+                        queueOperation: (input, task) => {
+                            const operation = operationCoordinator.create(input);
+                            void operationCoordinator.run(operation.id, task);
+                            return operation;
+                        },
+                        scheduleProjectRefresh: (reason) => { scheduleProjectRefresh(reason); },
+                        verifyDashboardRun: ({ runId, appId, dashboardId, tileIds }) => {
+                            const evidence = dashboardRunEvidence.get(runId);
+                            if (!evidence || evidence.expiresAt < Date.now())
+                                return { ok: false, error: 'The dashboard run receipt expired. Run the dashboard again.' };
+                            if (evidence.appId !== appId || evidence.dashboardId !== dashboardId)
+                                return { ok: false, error: 'The dashboard run receipt does not match this App page.' };
+                            const successful = new Set(evidence.successfulTileIds);
+                            const failed = tileIds.filter((tileId) => !successful.has(tileId));
+                            if (failed.length > 0)
+                                return { ok: false, error: `These semantic tiles did not complete successfully: ${failed.join(', ')}` };
+                            const approvalEligible = new Set(evidence.semanticApprovalEligibleTileIds);
+                            const repaired = tileIds.filter((tileId) => !approvalEligible.has(tileId));
+                            if (repaired.length > 0) {
+                                return { ok: false, error: `These semantic previews required SQL repair and cannot be approved as governed semantic results: ${repaired.join(', ')}. Review them as exploratory App analysis instead.` };
+                            }
+                            return { ok: true, snapshotId: evidence.snapshotId, resultFingerprint: evidence.resultFingerprint };
+                        },
                         // Story narration for commit — LLM-backed with deterministic fallback.
                         narrate: narrateForAgentRun,
                     });
@@ -8425,13 +9508,21 @@ export async function startLocalServer(opts) {
                         res.end(serializeJSON({ error: 'Invalid path' }));
                         return;
                     }
-                    mkdirSync(dirname(absPath), { recursive: true });
+                    await mkdirAsync(dirname(absPath), { recursive: true });
                     const toWrite = absPath.endsWith('.dql')
                         ? canonicalizeSafe(content)
                         : absPath.endsWith('.dqlnb')
                             ? canonicalizeNotebookSafe(content)
                             : content;
-                    writeFileSync(absPath, toWrite, 'utf-8');
+                    const tempPath = `${absPath}.tmp-${process.pid}-${Date.now()}`;
+                    try {
+                        await writeFileAsync(tempPath, toWrite, 'utf-8');
+                        await renameAsync(tempPath, absPath);
+                    }
+                    catch (error) {
+                        await rmAsync(tempPath, { force: true }).catch(() => undefined);
+                        throw error;
+                    }
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({ ok: true }));
                 }
@@ -9720,21 +10811,194 @@ export async function startLocalServer(opts) {
                         res.end(serializeJSON({ error: 'source is required' }));
                         return;
                     }
-                    const summary = await runBlockStudioTestSummary(source);
-                    const results = summary.assertions.map((assertion) => ({
-                        name: assertion.name,
-                        field: assertion.name.match(/^assert\s+(\S+)/)?.[1] ?? assertion.name,
-                        operator: assertion.name.match(/^assert\s+\S+\s+(\S+)/)?.[1] ?? '',
-                        expected: assertion.expected !== undefined ? String(assertion.expected) : assertion.name.replace(/^assert\s+\S+\s+\S+\s*/, ''),
-                        passed: assertion.passed,
-                        actual: assertion.error ?? (assertion.actual !== undefined ? String(assertion.actual) : undefined),
+                    const summary = await runBlockStudioTestSummary(source);
+                    const results = summary.assertions.map((assertion) => ({
+                        name: assertion.name,
+                        field: assertion.name.match(/^assert\s+(\S+)/)?.[1] ?? assertion.name,
+                        operator: assertion.name.match(/^assert\s+\S+\s+(\S+)/)?.[1] ?? '',
+                        expected: assertion.expected !== undefined ? String(assertion.expected) : assertion.name.replace(/^assert\s+\S+\s+\S+\s*/, ''),
+                        passed: assertion.passed,
+                        actual: assertion.error ?? (assertion.actual !== undefined ? String(assertion.actual) : undefined),
+                    }));
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ assertions: results, passed: summary.passed, failed: summary.failed, duration: summary.duration }));
+                }
+                catch (error) {
+                    res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+                }
+                return;
+            }
+            if (req.method === 'POST' && path === '/api/block-studio/certifications') {
+                try {
+                    const body = await readJSON(req);
+                    const source = typeof body.source === 'string' ? body.source : '';
+                    const suppliedMetadata = body.metadata && typeof body.metadata === 'object'
+                        ? body.metadata
+                        : {};
+                    const currentPath = typeof body.path === 'string'
+                        ? normalize(body.path).replace(/^\/+/, '').replaceAll('\\', '/')
+                        : undefined;
+                    const expectedSourceFingerprint = typeof body.expectedSourceFingerprint === 'string'
+                        ? body.expectedSourceFingerprint
+                        : undefined;
+                    const idempotencyKey = typeof req.headers['idempotency-key'] === 'string'
+                        ? req.headers['idempotency-key'].trim()
+                        : '';
+                    if (!source.trim()) {
+                        res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({ error: 'source is required' }));
+                        return;
+                    }
+                    if (idempotencyKey) {
+                        const existingId = operationIdempotency.get(idempotencyKey);
+                        const existing = existingId ? operationCoordinator.get(existingId) : null;
+                        if (existing) {
+                            res.writeHead(202, { 'Content-Type': 'application/json; charset=utf-8' });
+                            res.end(serializeJSON({ operation: existing, deduplicated: true }));
+                            return;
+                        }
+                    }
+                    if (currentPath && expectedSourceFingerprint) {
+                        const absoluteCurrentPath = safeJoin(projectRoot, currentPath);
+                        if (!absoluteCurrentPath || !existsSync(absoluteCurrentPath)) {
+                            res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+                            res.end(serializeJSON({ error: 'The block changed or moved. Reopen it before certifying.', code: 'SOURCE_CHANGED' }));
+                            return;
+                        }
+                        const actualFingerprint = createHash('sha256')
+                            .update(readFileSync(absoluteCurrentPath, 'utf-8'))
+                            .digest('hex');
+                        if (actualFingerprint !== expectedSourceFingerprint) {
+                            res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+                            res.end(serializeJSON({ error: 'The block changed after it was opened. Reopen it before certifying.', code: 'SOURCE_CHANGED' }));
+                            return;
+                        }
+                    }
+                    const draftSource = setBlockStudioStatusInSource(source, 'draft');
+                    const parsed = parseBlockSourceMetadata(draftSource);
+                    const name = typeof suppliedMetadata.name === 'string' && suppliedMetadata.name.trim()
+                        ? suppliedMetadata.name.trim()
+                        : parsed.name;
+                    if (!name) {
+                        res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({ error: 'Block name is required.' }));
+                        return;
+                    }
+                    const canonicalPath = currentPath && !isDraftBlockPath(currentPath) ? currentPath : undefined;
+                    const stableSuffix = createHash('sha256')
+                        .update(currentPath ?? `${name}:${draftSource}`)
+                        .digest('hex')
+                        .slice(0, 16);
+                    const draftPath = saveBlockStudioDraftArtifacts(projectRoot, {
+                        currentPath: currentPath && isDraftBlockPath(currentPath) ? currentPath : undefined,
+                        source: draftSource,
+                        name,
+                        domain: typeof suppliedMetadata.domain === 'string' ? suppliedMetadata.domain : parsed.domain,
+                        description: typeof suppliedMetadata.description === 'string' ? suppliedMetadata.description : parsed.description,
+                        owner: typeof suppliedMetadata.owner === 'string' ? suppliedMetadata.owner : parsed.owner,
+                        tags: Array.isArray(suppliedMetadata.tags) ? suppliedMetadata.tags.map(String) : parsed.tags,
+                        lineage: Array.isArray(suppliedMetadata.lineage) ? suppliedMetadata.lineage.map(String) : undefined,
+                        stableSuffix,
+                    });
+                    const operation = operationCoordinator.create({
+                        type: 'block_certification',
+                        scope: `block:${draftPath}`,
+                        resourceRevision: typeof body.clientRevision === 'string'
+                            ? body.clientRevision
+                            : createHash('sha256').update(draftSource).digest('hex'),
+                        message: `Certification queued for ${name}.`,
+                        cancellable: true,
+                    });
+                    if (idempotencyKey) {
+                        operationIdempotency.set(idempotencyKey, operation.id);
+                        while (operationIdempotency.size > 100) {
+                            const oldest = operationIdempotency.keys().next().value;
+                            if (typeof oldest !== 'string')
+                                break;
+                            operationIdempotency.delete(oldest);
+                        }
+                    }
+                    operationCoordinator.run(operation.id, async (signal, report) => {
+                        report({ phase: 'validating', progress: 15, message: 'Validating and running the saved draft once.' });
+                        const result = await certifyBlockStudioSource(draftSource, draftPath, { enterprise: body.enterprise === true });
+                        const blockers = Array.from(new Set(result.checklist.blockers));
+                        if (signal.aborted)
+                            throw Object.assign(new Error('Certification cancelled.'), { code: 'OPERATION_CANCELLED' });
+                        if (!result.certification.certified || blockers.length > 0) {
+                            return {
+                                outcome: 'draft_saved_with_blockers',
+                                oldPath: currentPath ?? draftPath,
+                                draftPath,
+                                blockers,
+                                checklist: result.checklist,
+                                block: openBlockStudioDocument(projectRoot, draftPath, semanticLayer),
+                            };
+                        }
+                        report({ phase: 'publishing', progress: 80, message: 'Publishing the certified block.' });
+                        const certifiedSource = setBlockStudioStatusInSource(draftSource, 'certified');
+                        const certifiedMetadata = parseBlockSourceMetadata(certifiedSource);
+                        const savedPath = saveBlockStudioArtifacts(projectRoot, {
+                            currentPath: canonicalPath ?? draftPath,
+                            source: certifiedSource,
+                            name: certifiedMetadata.name || name,
+                            domain: certifiedMetadata.domain,
+                            description: certifiedMetadata.description,
+                            owner: certifiedMetadata.owner,
+                            tags: certifiedMetadata.tags,
+                        });
+                        if (canonicalPath && draftPath !== savedPath) {
+                            try {
+                                deleteBlockStudioArtifacts(projectRoot, draftPath);
+                            }
+                            catch { /* certified source is already durable */ }
+                        }
+                        // Shared learning remains the same deterministic, advisory write used
+                        // by the synchronous compatibility route. It never gates publication.
+                        try {
+                            const learnedOutputs = Array.isArray(certifiedMetadata.outputs)
+                                ? certifiedMetadata.outputs.filter((output) => typeof output === 'string')
+                                : [];
+                            if (certifiedMetadata.name) {
+                                const memory = new MemoryStore(defaultMemoryPath(projectRoot));
+                                memory.upsert({
+                                    id: `mem_certify_${certifiedMetadata.name}`,
+                                    scope: 'project',
+                                    title: `Certified block: ${certifiedMetadata.name}`,
+                                    content: `Prefer the certified block "${certifiedMetadata.name}" for ${certifiedMetadata.description?.trim() || `questions in the ${certifiedMetadata.domain ?? 'analytics'} domain`}.${certifiedMetadata.grain ? ` Grain: ${certifiedMetadata.grain}.` : ''}${learnedOutputs.length ? ` Outputs: ${learnedOutputs.slice(0, 8).join(', ')}.` : ''} It is the trusted source — reuse it instead of generating new SQL.`,
+                                    tags: [certifiedMetadata.domain, certifiedMetadata.name, ...learnedOutputs.slice(0, 4)].filter((value) => Boolean(value)),
+                                    source: 'certify',
+                                    confidence: 0.95,
+                                    importance: 0.85,
+                                    enabled: true,
+                                });
+                            }
+                        }
+                        catch {
+                            /* best-effort: learning capture must never block certification */
+                        }
+                        const refreshOperation = scheduleProjectRefresh('block-studio-certification');
+                        return {
+                            outcome: 'certified',
+                            oldPath: currentPath ?? draftPath,
+                            draftPath,
+                            newPath: savedPath,
+                            block: openBlockStudioDocument(projectRoot, savedPath, semanticLayer),
+                            checklist: result.checklist,
+                            indexRefresh: { status: 'queued', operationId: refreshOperation.id },
+                        };
+                    });
+                    res.writeHead(202, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({
+                        operation: operationCoordinator.get(operation.id) ?? operation,
+                        draft: openBlockStudioDocument(projectRoot, draftPath, semanticLayer),
                     }));
-                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
-                    res.end(serializeJSON({ assertions: results, passed: summary.passed, failed: summary.failed, duration: summary.duration }));
                 }
                 catch (error) {
-                    res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
-                    res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+                    const code = apiErrorCode(error, 'CERTIFICATION_REQUEST_FAILED');
+                    const status = code === 'SOURCE_CHANGED' || apiErrorMessage(error) === 'BLOCK_EXISTS' ? 409 : 500;
+                    res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: apiErrorMessage(error), code }));
                 }
                 return;
             }
@@ -9807,7 +11071,7 @@ export async function startLocalServer(opts) {
                     catch {
                         /* best-effort: learning capture must never block certification */
                     }
-                    await refreshLocalMetadataCatalog(projectRoot);
+                    const refreshOperation = scheduleProjectRefresh('block-studio-certify');
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({
                         ok: true,
@@ -9818,6 +11082,7 @@ export async function startLocalServer(opts) {
                         metadata: certifiedPayload?.metadata,
                         companionPath: certifiedPayload?.companionPath ?? null,
                         validation: certifiedPayload?.validation ?? result.validation,
+                        lineageRefresh: { status: 'queued', operationId: refreshOperation.id },
                     }));
                 }
                 catch (error) {
@@ -10399,10 +11664,20 @@ export async function startLocalServer(opts) {
                     // of the same 7,500+ object catalog while keeping the route compatible
                     // for older clients.
                     const includeSemantic = url.searchParams.get('includeSemantic') !== 'false';
+                    const dbtManifestPath = resolveDbtManifestPath(projectRoot, cfg);
+                    let databaseTree = [];
+                    if (cfg.manifestVersion === 3 && cfg.modeling?.mode === 'dbt-first' && dbtManifestPath) {
+                        try {
+                            databaseTree = buildDbtDatabaseSchemaTree(projectSnapshot().manifest, 25, physicalDbtRelationIds(dbtManifestPath));
+                        }
+                        catch {
+                            // Keep the rest of Block Studio available while dbt is rebuilt.
+                        }
+                    }
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({
                         semanticTree: includeSemantic && semanticLayer ? buildSemanticTree(semanticLayer, semanticImportManifest) : null,
-                        databaseTree: await buildDatabaseSchemaTree(projectRoot, executor, connection),
+                        databaseTree,
                         connection: {
                             default: defaultKey,
                             current: defaultKey,
@@ -10657,25 +11932,13 @@ export async function startLocalServer(opts) {
                             stableSuffix: metadata.candidateId,
                         })
                         : saveBlockStudioArtifacts(projectRoot, saveOptions);
-                    let compiledManifest;
-                    let lineageRefresh;
-                    try {
-                        compiledManifest = compileBlockStudioManifest(projectRoot, projectConfig);
-                        lineageRefresh = { status: 'ready', compiledAt: new Date().toISOString() };
-                    }
-                    catch (error) {
-                        // The block is already safely stored. Preserve it and report the
-                        // rebuild failure separately instead of turning a successful save
-                        // into a misleading 500 response.
-                        lineageRefresh = {
-                            status: 'failed',
-                            message: error instanceof Error ? error.message : String(error),
-                        };
-                    }
-                    await refreshLocalMetadataCatalog(projectRoot, compiledManifest, semanticLayer);
+                    const refreshOperation = scheduleProjectRefresh('block-studio-save');
                     const payload = {
                         ...openBlockStudioDocument(projectRoot, savedPath, semanticLayer),
-                        lineageRefresh,
+                        lineageRefresh: {
+                            status: 'queued',
+                            operationId: refreshOperation.id,
+                        },
                     };
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON(payload));
@@ -10695,21 +11958,13 @@ export async function startLocalServer(opts) {
                 try {
                     const blockPath = url.searchParams.get('path');
                     const deleted = deleteBlockStudioArtifacts(projectRoot, blockPath ?? '');
-                    let compiledManifest;
-                    let lineageRefresh;
-                    try {
-                        compiledManifest = compileBlockStudioManifest(projectRoot, projectConfig);
-                        lineageRefresh = { status: 'ready', compiledAt: new Date().toISOString() };
-                    }
-                    catch (error) {
-                        lineageRefresh = {
-                            status: 'failed',
-                            message: error instanceof Error ? error.message : String(error),
-                        };
-                    }
-                    await refreshLocalMetadataCatalog(projectRoot, compiledManifest, semanticLayer);
+                    const refreshOperation = scheduleProjectRefresh('block-studio-delete');
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
-                    res.end(serializeJSON({ ok: true, ...deleted, lineageRefresh }));
+                    res.end(serializeJSON({
+                        ok: true,
+                        ...deleted,
+                        lineageRefresh: { status: 'queued', operationId: refreshOperation.id },
+                    }));
                 }
                 catch (error) {
                     const message = error instanceof Error ? error.message : String(error);
@@ -12173,13 +13428,17 @@ export async function startLocalServer(opts) {
             // GET /api/describe-table?table=schema.table — returns columns for a specific table
             if (req.method === 'GET' && path === '/api/describe-table') {
                 try {
-                    const tablePath = url.searchParams.get('table') ?? '';
-                    const schemaName = url.searchParams.get('schema') ?? undefined;
-                    if (!tablePath) {
+                    const requestedRelation = url.searchParams.get('relation')?.trim() ?? '';
+                    const legacyTable = url.searchParams.get('table')?.trim() ?? '';
+                    const legacySchema = url.searchParams.get('schema')?.trim() ?? '';
+                    const relationParts = splitQualifiedRelationIdentifier(requestedRelation || [legacySchema, legacyTable].filter(Boolean).join('.'));
+                    if (!relationParts?.length) {
                         res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
-                        res.end(serializeJSON({ error: 'Missing table parameter' }));
+                        res.end(serializeJSON({ error: 'A safe dbt relation is required.' }));
                         return;
                     }
+                    const tablePath = relationParts.at(-1);
+                    const schemaName = relationParts.length > 1 ? relationParts.slice(0, -1).join('.') : undefined;
                     // Try connector.listColumns() first
                     let columns = [];
                     const activeConnection = connection;
@@ -12188,7 +13447,11 @@ export async function startLocalServer(opts) {
                             throw new Error('No active connection');
                         const connector = await executor.getConnector(activeConnection);
                         if (typeof connector.listColumns === 'function') {
-                            const rawCols = await connector.listColumns(schemaName, tablePath);
+                            // Connector contracts accept one schema plus one table. For a
+                            // three-part dbt relation, the active connection owns the database
+                            // and the final namespace segment is the schema.
+                            const connectorSchema = schemaName?.split('.').filter(Boolean).at(-1);
+                            const rawCols = await connector.listColumns(connectorSchema, tablePath);
                             columns = rawCols.map((c) => ({ name: c.name, type: c.dataType }));
                         }
                     }
@@ -12200,17 +13463,15 @@ export async function startLocalServer(opts) {
                         try {
                             const isFile = /\.(csv|parquet|json)$/i.test(tablePath) || tablePath.startsWith('data/');
                             const safePath = tablePath.replace(/'/g, "''");
-                            const qualifiedIdentifier = tablePath.split('.').map((p) => `"${p.replace(/"/g, '""')}"`).join('.');
+                            if (!activeConnection)
+                                throw new Error('No active connection');
+                            const dialect = getDialect(activeConnection.driver);
+                            const qualifiedIdentifier = relationParts.map((part) => dialect.quoteIdentifier(part)).join('.');
                             const sql = isFile
                                 ? `DESCRIBE SELECT * FROM read_csv_auto('${safePath}') LIMIT 0`
                                 : `DESCRIBE ${qualifiedIdentifier}`;
-                            if (!activeConnection)
-                                throw new Error('No active connection');
                             const result = await executor.executeQuery(sql, [], {}, activeConnection);
-                            columns = result.rows.map((row) => ({
-                                name: String(row['column_name'] ?? row['Field'] ?? ''),
-                                type: String(row['column_type'] ?? row['Type'] ?? ''),
-                            }));
+                            columns = schemaColumnsFromDescribeRows(result.rows);
                         }
                         catch {
                             // empty columns
@@ -12299,6 +13560,214 @@ export async function startLocalServer(opts) {
                 }
                 return;
             }
+            /**
+             * Repair an editable notebook cell without starting Notebook AI research.
+             * The returned source is applied only to the in-memory notebook cell by the
+             * client; this endpoint never writes a block/domain/dbt source file.
+             */
+            if (req.method === 'POST' && path === '/api/notebook/repair-execution') {
+                let body = {};
+                let execContext = null;
+                const start = Date.now();
+                try {
+                    body = await readJSON(req);
+                    execContext = notebookExecutionContext(body.executionContext);
+                    const cell = normalizeNotebookCell(body.cell);
+                    if (!cell || (cell.type !== 'sql' && cell.type !== 'dql')) {
+                        res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({ error: 'An editable SQL or DQL notebook cell is required.' }));
+                        return;
+                    }
+                    if (cell.type === 'dql' && /^\s*@block\(/i.test(cell.source)) {
+                        res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({ error: 'Customize the bound block as a notebook copy before repairing it.' }));
+                        return;
+                    }
+                    const embeddedSourceSql = notebookCellRepairSql(cell);
+                    if (!embeddedSourceSql && (cell.type !== 'dql' || !notebookDqlSourceAllowsBackgroundRepair(cell.source))) {
+                        res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({ error: 'Background repair supports SQL cells and editable custom DQL blocks. Open governed references or semantic definitions in their owning editor.' }));
+                        return;
+                    }
+                    if (cell.type === 'sql' && /\{\{[^}]+\}\}/.test(cell.source)) {
+                        res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({ error: 'Run or repair the referenced upstream cell before repairing this dependent query.' }));
+                        return;
+                    }
+                    const targetConnection = await resolveExecutionConnection(body);
+                    const submittedError = typeof body.error === 'string' ? body.error.trim() : '';
+                    const submittedFailure = body.failure && typeof body.failure === 'object' && !Array.isArray(body.failure)
+                        ? body.failure
+                        : undefined;
+                    const failureCode = typeof submittedFailure?.code === 'string' ? submittedFailure.code : undefined;
+                    if (!notebookFailureAllowsBackgroundRepair({ code: failureCode, message: submittedError })) {
+                        res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({ error: 'This failure needs a data, access, parameter, or notebook dependency change and cannot be auto-fixed safely.' }));
+                        return;
+                    }
+                    const retainedFailure = submittedError
+                        ? normalizeWarehouseSqlFailure({ code: failureCode, message: submittedError }, targetConnection.driver)
+                        : undefined;
+                    if (!analyticalFailureAllowsDeterministicRetry(retainedFailure)) {
+                        res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({
+                            error: 'This failure requires authorized access or a policy change and cannot be repaired in the background.',
+                            warehouseFailure: retainedFailure,
+                        }));
+                        return;
+                    }
+                    const parameters = body.parameters && typeof body.parameters === 'object' && !Array.isArray(body.parameters)
+                        ? body.parameters
+                        : {};
+                    let invocation = null;
+                    let plan = null;
+                    let dqlCompilationError;
+                    if (cell.type === 'dql') {
+                        try {
+                            invocation = prepareBlockInvocation({ source: cell.source, parameters, surface: 'notebook' });
+                            if (invocation.errors.length)
+                                throw boundedRepairError(invocation.errors.join(' '), 409);
+                            if (invocation.unresolvedParameters.length) {
+                                throw boundedRepairError(`Provide required parameter${invocation.unresolvedParameters.length === 1 ? '' : 's'} before retrying: ${invocation.unresolvedParameters.join(', ')}.`, 409);
+                            }
+                            plan = buildExecutionPlan(cell, {
+                                semanticLayer,
+                                driver: targetConnection.driver,
+                                parameters: invocation.values,
+                            });
+                        }
+                        catch (error) {
+                            const repairError = error;
+                            if (repairError.status === 409)
+                                throw error;
+                            dqlCompilationError = repairError.message || String(error);
+                        }
+                    }
+                    const attemptedSql = typeof body.attemptedSql === 'string' && body.attemptedSql.trim()
+                        ? body.attemptedSql.trim()
+                        : embeddedSourceSql;
+                    const executionTarget = executionTargetDescriptor(body);
+                    const targetConnectionName = executionTarget.target === 'connection'
+                        ? executionTarget.connectionName
+                        : executionTarget.target === 'local'
+                            ? 'local'
+                            : projectConfig.defaultConnectionName;
+                    const question = [
+                        `Repair notebook cell ${cell.title?.trim() || cell.id}.`,
+                        submittedError ? `Failure: ${submittedError.slice(0, 1_000)}` : '',
+                    ].filter(Boolean).join(' ');
+                    let repaired;
+                    let repairedSource;
+                    if (cell.type === 'dql' && dqlCompilationError) {
+                        const repairedDql = await executeBoundedDqlRepair({
+                            question,
+                            source: cell.source,
+                            failure: [submittedError, dqlCompilationError].filter(Boolean).join('\n'),
+                            targetConnection,
+                            targetConnectionName,
+                            parameters,
+                            artifactName: cell.title,
+                        });
+                        repaired = repairedDql;
+                        repairedSource = repairedDql.repairedSource;
+                    }
+                    else {
+                        const sourceSql = plan?.sql ?? attemptedSql;
+                        if (!sourceSql?.trim()) {
+                            throw boundedRepairError('DQL could not identify an embedded query to repair.', 422);
+                        }
+                        const sqlParams = plan?.sqlParams ?? [];
+                        repaired = await executeBoundedSqlRepair({
+                            question,
+                            sourceSql,
+                            targetConnection,
+                            targetConnectionName,
+                            sqlParams,
+                            variables: {
+                                ...(plan?.variables ?? {}),
+                                ...(invocation?.values ?? {}),
+                            },
+                        });
+                        if (cell.type === 'dql') {
+                            const originalQuery = notebookCellRepairSql(cell);
+                            const repairedQuery = repaired.repairMode === 'deterministic'
+                                ? applyNotebookRepairRewrites(originalQuery, repaired.rewrites)
+                                : restoreNotebookDqlParameterInterpolations(repaired.repairedSql, sqlParams);
+                            repairedSource = replaceNotebookDqlQueryForRepair(cell.source, repairedQuery);
+                        }
+                        else {
+                            repairedSource = repaired.repairedSql;
+                        }
+                    }
+                    if (!repairedSource) {
+                        throw boundedRepairError('DQL could not safely replace the embedded query in this cell.', 422);
+                    }
+                    // Prove the repaired DQL wrapper still compiles. SQL execution above
+                    // already proved the corrected statement on the selected target.
+                    if (cell.type === 'dql') {
+                        const validationPlan = buildExecutionPlan({ ...cell, source: repairedSource }, {
+                            semanticLayer,
+                            driver: targetConnection.driver,
+                            parameters: invocation?.values ?? parameters,
+                        });
+                        if (!validationPlan?.sql) {
+                            throw boundedRepairError('The repaired SQL ran, but the DQL wrapper no longer compiles.', 422);
+                        }
+                        const beforeParameters = (plan?.sqlParams ?? ('sqlParams' in repaired ? repaired.sqlParams : []))
+                            .map((parameter) => `${parameter.position}:${parameter.name}`);
+                        const afterParameters = validationPlan.sqlParams.map((parameter) => `${parameter.position}:${parameter.name}`);
+                        if (beforeParameters.join('|') !== afterParameters.join('|')) {
+                            throw boundedRepairError('The repaired DQL changed the cell parameter contract, so the update was stopped.', 422);
+                        }
+                    }
+                    if (execContext?.notebookPath) {
+                        recordNotebookQueryRun(projectRoot, {
+                            notebookPath: execContext.notebookPath,
+                            cellId: execContext.cellId ?? cell.id,
+                            cellName: execContext.cellName ?? cell.title,
+                            source: execContext.source ?? (cell.type === 'dql' ? 'notebook_dql_cell' : 'notebook_sql_cell'),
+                            status: 'success',
+                            rowCount: repaired.result.rowCount ?? repaired.result.rows.length,
+                            durationMs: Date.now() - start,
+                            sql: repaired.repairedSql,
+                        });
+                    }
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({
+                        ok: true,
+                        source: repairedSource,
+                        repairedSql: repaired.repairedSql,
+                        repairMode: repaired.repairMode,
+                        result: repaired.result,
+                        executionTarget,
+                        executionContext: notebookExecutionIdentity(execContext, cell.id),
+                        compiledSql: repaired.repairedSql,
+                        executedSql: repaired.result.sql ?? repaired.repairedSql,
+                        executionReceipt: repaired.result.executionReceipt,
+                    }));
+                }
+                catch (error) {
+                    const repairError = error;
+                    if (execContext?.notebookPath) {
+                        recordNotebookQueryRun(projectRoot, {
+                            notebookPath: execContext.notebookPath,
+                            cellId: execContext.cellId,
+                            cellName: execContext.cellName,
+                            source: execContext.source ?? 'notebook_cell_repair',
+                            status: 'error',
+                            durationMs: Date.now() - start,
+                            errorCode: repairError.warehouseFailure?.category ?? repairError.message,
+                            sql: typeof body.attemptedSql === 'string' ? body.attemptedSql : undefined,
+                        });
+                    }
+                    res.writeHead(repairError.status ?? 500, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({
+                        error: repairError.message,
+                        ...(repairError.warehouseFailure ? { warehouseFailure: repairError.warehouseFailure } : {}),
+                    }));
+                }
+                return;
+            }
             if (req.method === 'POST' && path === '/api/query') {
                 let body;
                 let execContext = null;
@@ -13511,6 +14980,22 @@ table: ${table}${tagList}
             })));
         });
     });
+    server.once('close', () => {
+        runtimeClosing = true;
+        for (const watcher of projectWatchers)
+            watcher.close();
+        projectWatchers.length = 0;
+        unsubscribeOperationEvents();
+        projectRefreshCoordinator.close();
+        for (const client of operationSseClients) {
+            try {
+                client.end();
+            }
+            catch { /* connection already closed */ }
+        }
+        operationSseClients.clear();
+        operationCoordinator.close();
+    });
     opts.captureServer?.(server);
     return new Promise((resolvePromise, reject) => {
         let retriedWithRandomPort = false;
@@ -13952,7 +15437,7 @@ function loadAppDashboard(projectRoot, appId, dashboardId) {
         for (const d of findDashboardsForApp(appDir)) {
             const { document: dashboard } = loadDashboardDocument(d);
             if (dashboard?.id === dashboardId)
-                return { app, dashboard };
+                return { app, dashboard, appDir };
         }
     }
     return null;
@@ -16846,6 +18331,60 @@ function normalizeNotebookCell(value) {
         config: candidate.config,
     };
 }
+export function notebookCellRepairSql(cell) {
+    if (cell.type === 'sql')
+        return cell.source.trim() || undefined;
+    if (cell.type !== 'dql')
+        return undefined;
+    const match = /\bquery\s*=\s*"""([\s\S]*?)"""/i.exec(cell.source);
+    return match?.[1]?.trim() || undefined;
+}
+export function notebookDqlSourceAllowsBackgroundRepair(source) {
+    if (/^\s*@block\(/i.test(source) || /\btype\s*=\s*"semantic"/i.test(source))
+        return false;
+    return /\bblock\b/i.test(source) && /\bquery\b/i.test(source);
+}
+export function replaceNotebookDqlQueryForRepair(source, sql) {
+    const queryField = /\b(query\s*=\s*""")([\s\S]*?)(""")/i;
+    if (!queryField.test(source) || !sql.trim())
+        return undefined;
+    return source.replace(queryField, (_match, open, _body, close) => (`${open}\n${sql.trim()}\n  ${close}`));
+}
+const NOTEBOOK_BACKGROUND_REPAIR_BLOCKED_CODES = new Set([
+    'AMBIGUOUS_NOTEBOOK_DEPENDENCY',
+    'CROSS_ENGINE_JOIN_REQUIRED',
+    'EXECUTION_TARGET_MISMATCH',
+    'SEMANTIC_SOURCE_DRIFT',
+    'STALE_CELL_EXECUTION',
+    'UPSTREAM_RESULT_UNAVAILABLE',
+    'UNAUTHORIZED',
+]);
+/**
+ * Notebook background repair is deliberately narrower than conversational
+ * repair. Access, policy, target, parameter, and dependency failures require a
+ * user decision; only query-shape failures may enter the one-attempt loop.
+ * Acceptance: API-006, API-007, UI-012, UI-013, SEC-004, E2E-014.
+ */
+export function notebookFailureAllowsBackgroundRepair(input) {
+    const code = input.code?.trim().toUpperCase();
+    const message = input.message?.trim() ?? '';
+    if (!message)
+        return false;
+    if (code && NOTEBOOK_BACKGROUND_REPAIR_BLOCKED_CODES.has(code))
+        return false;
+    return !/(?:permission|not authorized|unauthori[sz]ed|access denied|authentication|credential|policy|unsafe|read[- ]only|cancel(?:led|ed)|required parameters?|provide required|cross[- ]engine|upstream (?:cell|result)|notebook dependency|target mismatch|source drift|matched more than one schema)/i.test(message);
+}
+export function applyNotebookRepairRewrites(sql, rewrites) {
+    return rewrites.reduce((current, rewrite) => {
+        const pattern = rewrite.from.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        return current.replace(new RegExp(pattern, 'g'), rewrite.to);
+    }, sql);
+}
+export function restoreNotebookDqlParameterInterpolations(sql, parameters) {
+    return [...parameters]
+        .sort((left, right) => right.position - left.position)
+        .reduce((current, parameter) => current.replace(new RegExp(`\\$${parameter.position}\\b`, 'g'), `\${${parameter.name}}`), sql);
+}
 function resolveNotebookBlockReferenceCell(cell, projectRoot) {
     if (cell.type !== 'dql')
         return { cell };
@@ -17039,6 +18578,68 @@ function readUserPrefs(userPrefsPath) {
 function writeUserPrefs(userPrefsPath, prefs) {
     writeFileSync(userPrefsPath, JSON.stringify(prefs, null, 2) + '\n', 'utf-8');
 }
+/** Normalize DESCRIBE output across Snowflake, DuckDB, and PostgreSQL shapes. */
+export function schemaColumnsFromDescribeRows(rows) {
+    return rows.map((row) => ({
+        name: String(row['column_name'] ?? row['COLUMN_NAME'] ?? row['Field'] ?? row['FIELD'] ?? row['name'] ?? row['NAME'] ?? ''),
+        type: String(row['column_type'] ?? row['COLUMN_TYPE'] ?? row['data_type'] ?? row['DATA_TYPE'] ?? row['Type'] ?? row['TYPE'] ?? row['type'] ?? ''),
+    })).filter((column) => Boolean(column.name));
+}
+/** Parse dbt relation strings without letting relation text become SQL syntax. */
+export function splitQualifiedRelationIdentifier(value) {
+    const rawParts = [];
+    let current = '';
+    let quote = null;
+    for (let index = 0; index < value.length; index += 1) {
+        const char = value[index];
+        if (quote) {
+            current += char;
+            if (char === quote) {
+                const next = value[index + 1];
+                if ((quote === '"' || quote === '`') && next === quote) {
+                    current += next;
+                    index += 1;
+                }
+                else {
+                    quote = null;
+                }
+            }
+            continue;
+        }
+        if (char === '"' || char === '`') {
+            quote = char;
+            current += char;
+            continue;
+        }
+        if (char === '[') {
+            quote = ']';
+            current += char;
+            continue;
+        }
+        if (char === '.') {
+            rawParts.push(current);
+            current = '';
+            continue;
+        }
+        current += char;
+    }
+    if (quote)
+        return null;
+    rawParts.push(current);
+    if (rawParts.length === 0 || rawParts.length > 4)
+        return null;
+    const decoded = rawParts.map((raw) => {
+        const token = raw.trim();
+        if (/^"(?:[^"]|"")+"$/.test(token))
+            return token.slice(1, -1).replace(/""/g, '"');
+        if (/^`(?:[^`]|``)+`$/.test(token))
+            return token.slice(1, -1).replace(/``/g, '`');
+        if (/^\[[^\]]+\]$/.test(token))
+            return token.slice(1, -1).replace(/\]\]/g, ']');
+        return /^[A-Za-z_][A-Za-z0-9_$]*$/.test(token) ? token : null;
+    });
+    return decoded.every((part) => Boolean(part)) ? decoded : null;
+}
 async function introspectSchema(executor, connection, options = {}) {
     let tables = [];
     const columnsByPath = new Map();
@@ -17093,77 +18694,93 @@ async function introspectSchema(executor, connection, options = {}) {
     }
     return { tables, columnsByPath };
 }
-function buildDatabaseSchemaTree(projectRoot, executor, connection) {
-    return (async () => {
-        const dataFiles = scanDataFiles(projectRoot);
-        const dbTables = connection
-            ? (await introspectSchema(executor, connection, { limit: 1_000 })).tables
-            : [];
-        const schemaMap = new Map();
-        for (const table of dbTables) {
-            const schemaName = table.schema || 'default';
-            const existing = schemaMap.get(schemaName) ?? [];
-            existing.push({ name: table.name, path: table.path, type: table.type });
-            schemaMap.set(schemaName, existing);
-        }
-        const databaseNodes = Array.from(schemaMap.entries())
-            .sort((a, b) => a[0].localeCompare(b[0]))
-            .map(([schemaName, tables]) => ({
-            id: `db-schema:${schemaName}`,
-            label: schemaName,
-            kind: 'schema',
-            children: tables
-                .sort((a, b) => a.name.localeCompare(b.name))
-                .map((table) => ({
-                id: `db-table:${table.path}`,
-                label: table.name,
-                kind: 'table',
-                path: table.path,
-                type: table.type,
-                // Warehouse columns are loaded lazily for the selected table.
-                children: [],
-            })),
-        }));
-        // Eagerly resolve file columns via DuckDB DESCRIBE
-        if (dataFiles.length > 0) {
-            const fileChildren = [];
-            for (const file of dataFiles) {
-                let columns = [];
-                if (connection) {
-                    try {
-                        const ext = file.name.split('.').pop()?.toLowerCase();
-                        const readFn = ext === 'parquet' ? 'read_parquet' : ext === 'json' ? 'read_json_auto' : 'read_csv_auto';
-                        const descResult = await executor.executeQuery(`DESCRIBE SELECT * FROM ${readFn}('${file.path.replace(/'/g, "''")}') LIMIT 0`, [], {}, connection);
-                        columns = descResult.rows.map((row) => ({
-                            id: `db-column:${file.path}:${String(row['column_name'] ?? '')}`,
-                            label: String(row['column_name'] ?? ''),
-                            kind: 'column',
-                            path: file.path,
-                            type: String(row['column_type'] ?? ''),
-                        }));
-                    }
-                    catch {
-                        // file column discovery failed — empty children is fine
-                    }
-                }
-                fileChildren.push({
-                    id: `db-table:${file.path}`,
-                    label: file.name,
-                    kind: 'table',
-                    path: file.path,
-                    type: 'FILE',
-                    children: columns,
-                });
+const dbtPhysicalRelationCache = new Map();
+/**
+ * Display-only physical relation filter sourced from the raw dbt artifact.
+ * This deliberately does not mutate DQLManifest or the agent metadata/indexes.
+ */
+function physicalDbtRelationIds(manifestPath) {
+    try {
+        const stat = statSync(manifestPath);
+        const version = `${stat.size}:${stat.mtimeMs}`;
+        const cached = dbtPhysicalRelationCache.get(manifestPath);
+        if (cached?.version === version)
+            return cached.ids;
+        const raw = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+        const ids = new Set();
+        for (const collectionName of ['nodes', 'sources']) {
+            const collection = raw[collectionName];
+            if (!collection || typeof collection !== 'object' || Array.isArray(collection))
+                continue;
+            for (const [fallbackId, value] of Object.entries(collection)) {
+                if (!value || typeof value !== 'object' || Array.isArray(value))
+                    continue;
+                const node = value;
+                const resourceType = String(node.resource_type ?? (collectionName === 'sources' ? 'source' : ''));
+                if (resourceType !== 'model' && resourceType !== 'source')
+                    continue;
+                const config = node.config && typeof node.config === 'object' && !Array.isArray(node.config)
+                    ? node.config
+                    : {};
+                if (resourceType === 'model' && String(config.materialized ?? '').toLowerCase() === 'ephemeral')
+                    continue;
+                ids.add(typeof node.unique_id === 'string' ? node.unique_id : fallbackId);
             }
-            databaseNodes.unshift({
-                id: 'db-schema:files',
-                label: 'files',
-                kind: 'schema',
-                children: fileChildren,
-            });
         }
-        return databaseNodes;
-    })();
+        dbtPhysicalRelationCache.set(manifestPath, { version, ids });
+        return ids;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function buildDbtDatabaseSchemaTree(manifest, limit = 25, physicalIds) {
+    // PERF-001 / CTX-005: Block Studio must not enumerate the connected account.
+    // Its initial editor context is the first bounded page of physical relations
+    // declared by the connected dbt artifact; columns remain lazy point-lookups.
+    const boundedLimit = Math.min(100, Math.max(1, Math.floor(limit)));
+    const seen = new Set();
+    const tables = Object.values(manifest.dbtProvenance?.nodes ?? {})
+        .filter((node) => Boolean(node.relation) && (!physicalIds || physicalIds.has(node.uniqueId)))
+        .sort((a, b) => a.uniqueId.localeCompare(b.uniqueId))
+        .flatMap((node) => {
+        const path = node.relation;
+        const key = path.toLowerCase();
+        if (seen.has(key))
+            return [];
+        seen.add(key);
+        const parts = path.split('.').filter(Boolean);
+        return [{
+                schema: parts.length > 1 ? parts.slice(0, -1).join('.') : 'default',
+                name: parts.at(-1) ?? node.name,
+                path,
+                type: node.resourceType === 'source' ? 'DBT_SOURCE' : 'DBT_MODEL',
+            }];
+    })
+        .slice(0, boundedLimit);
+    const bySchema = new Map();
+    for (const table of tables) {
+        const current = bySchema.get(table.schema) ?? [];
+        current.push(table);
+        bySchema.set(table.schema, current);
+    }
+    return Array.from(bySchema.entries())
+        .sort((a, b) => a[0].localeCompare(b[0]))
+        .map(([schema, schemaTables]) => ({
+        id: `db-schema:${schema}`,
+        label: schema,
+        kind: 'schema',
+        children: schemaTables
+            .sort((a, b) => a.name.localeCompare(b.name))
+            .map((table) => ({
+            id: `db-table:${table.path}`,
+            label: table.name,
+            kind: 'table',
+            path: table.path,
+            type: table.type,
+            children: [],
+        })),
+    }));
 }
 export function openBlockStudioDocument(projectRoot, relativePath, semanticLayer) {
     const normalizedPath = normalize(relativePath).replace(/^\/+/, '');
@@ -17188,6 +18805,7 @@ export function openBlockStudioDocument(projectRoot, relativePath, semanticLayer
         owner: parsedMetadata.owner || companion?.owner || '',
         tags: parsedMetadata.tags.length > 0 ? parsedMetadata.tags : companion?.tags ?? [],
         reviewStatus: parsedMetadata.status || companion?.reviewStatus || 'draft',
+        sourceFingerprint: createHash('sha256').update(source).digest('hex'),
     };
     return {
         path: normalizedPath,
@@ -18752,6 +20370,45 @@ function formatBlockStudioExpected(expected) {
         return String(normalized);
     return JSON.stringify(normalized);
 }
+function evaluateBlockStudioTests(tests, rows, columns, startedAt) {
+    if (tests.length === 0) {
+        return { passed: 0, failed: 0, skipped: 0, duration: Date.now() - startedAt, assertions: [], runAt: new Date() };
+    }
+    const assertions = [];
+    let passed = 0;
+    let failed = 0;
+    for (const test of tests) {
+        const name = `assert ${test.field} ${test.operator} ${formatBlockStudioExpected(test.expected)}`;
+        let actual;
+        if (test.field === 'row_count') {
+            actual = rows.length;
+        }
+        else if (!columns.includes(test.field)) {
+            assertions.push({ name, passed: false, expected: test.expected, error: `Column '${test.field}' not found in results` });
+            failed += 1;
+            continue;
+        }
+        else {
+            actual = rows[0]?.[test.field];
+        }
+        const ok = compareBlockStudioValues(actual, test.operator, test.expected);
+        if (ok) {
+            assertions.push({ name, passed: true, actual, expected: test.expected });
+            passed += 1;
+        }
+        else {
+            assertions.push({
+                name,
+                passed: false,
+                actual,
+                expected: test.expected,
+                error: `${String(actual)} ${test.operator} ${formatBlockStudioExpected(test.expected)} is false`,
+            });
+            failed += 1;
+        }
+    }
+    return { passed, failed, skipped: 0, duration: Date.now() - startedAt, assertions, runAt: new Date() };
+}
 function buildBlockStudioCertificationChecklist(input) {
     const parsed = parseBlockSourceMetadata(input.source);
     const sql = extractBlockStudioSql(input.source) ?? '';
@@ -23842,6 +25499,46 @@ function mergeAgentSchemaContexts(...contexts) {
     }
     return Array.from(byRelation.values()).slice(0, 16);
 }
+function agentRelationMatchKey(relation) {
+    return relation
+        .replace(/["`\[\]]/g, '')
+        .split('.')
+        .filter(Boolean)
+        .slice(-2)
+        .join('.')
+        .toLowerCase();
+}
+/**
+ * Keep dbt descriptions and semantic meaning, but make a complete live point
+ * lookup authoritative for executable column names on the selected connection.
+ * No fuzzy aliases are invented: a stale `customer_name` declaration disappears
+ * when the live relation exposes only `name`.
+ */
+export function reconcileAgentSchemaContextWithLive(catalog, live) {
+    const liveByRelation = new Map(live
+        .filter((table) => table.columns.length > 0)
+        .map((table) => [agentRelationMatchKey(table.relation), table]));
+    return catalog.map((table) => {
+        const verified = liveByRelation.get(agentRelationMatchKey(table.relation));
+        if (!verified)
+            return table;
+        const metadataColumns = new Map(table.columns.map((column) => [column.name.toLowerCase(), column]));
+        return {
+            ...table,
+            source: 'dbt metadata verified against live runtime schema',
+            columnCompleteness: 'complete',
+            columns: verified.columns.map((column) => {
+                const metadata = metadataColumns.get(column.name.toLowerCase());
+                return {
+                    ...column,
+                    type: column.type ?? metadata?.type,
+                    description: metadata?.description,
+                    sampleValues: metadata?.sampleValues,
+                };
+            }),
+        };
+    });
+}
 function mergeAgentSchemaSampleValues(snapshot, enriched) {
     const samples = new Map();
     for (const table of enriched) {