@duckcodeailabs/dql-cli 1.12.11 → 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);
                     },
                 });
             }
@@ -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
@@ -3912,83 +4113,365 @@ export async function startLocalServer(opts) {
         }
         return { result, repairedSql, repairMode, firstFailure, rewrites };
     };
-    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.');
+    /**
+     * 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 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: [{
+        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,
@@ -4106,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,
@@ -4156,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,
@@ -4178,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) {
@@ -4204,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 ?? []),
@@ -4212,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,
@@ -4259,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,
@@ -4294,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
@@ -4334,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 : []),
@@ -4344,6 +4857,7 @@ export async function startLocalServer(opts) {
             }) ?? run;
         }
         catch (error) {
+            rethrowIfCancelled(error, input.signal);
             return storage.updateRun(run.id, {
                 domain,
                 owner,
@@ -4570,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}`;
@@ -4594,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') {
@@ -4616,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 {
@@ -4652,6 +5164,7 @@ export async function startLocalServer(opts) {
                         }
                     }).catch(() => { });
                 });
+                projectWatchers.push(watcher);
             }
             catch { /* dbt artifact directory not watchable */ }
         }
@@ -4734,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
@@ -4783,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) => {
@@ -4875,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 = {
@@ -5032,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;
     };
@@ -5059,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.' }));
@@ -5094,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);
@@ -6018,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;
@@ -6050,12 +6580,27 @@ export async function startLocalServer(opts) {
                         : projectConfig.defaultConnectionName;
                 let repaired;
                 try {
-                    repaired = await executeBoundedSqlRepair({
-                        question: sourceRun.question,
-                        sourceSql,
-                        targetConnection,
-                        targetConnectionName,
-                    });
+                    // 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) {
                     const repairError = error;
@@ -6078,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',
@@ -6085,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 },
@@ -6274,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)
@@ -6316,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' });
@@ -7989,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,
@@ -8079,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)
@@ -8122,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) {
@@ -8156,6 +9010,11 @@ export async function startLocalServer(opts) {
                             });
                             continue;
                         }
+                        let blockSource;
+                        let blockTargetConnection;
+                        let blockPlan;
+                        let blockFilterApplication;
+                        let blockInvocation;
                         try {
                             assertAppAccess({
                                 app: loaded.app,
@@ -8163,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',
@@ -8220,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',
@@ -8237,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) {
@@ -8265,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),
+                                        },
+                                    } : {}),
                                 });
                             }
                         }
@@ -8304,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,
@@ -8355,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,
                     });
@@ -8531,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 }));
                 }
@@ -9844,6 +10829,179 @@ export async function startLocalServer(opts) {
                 }
                 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),
+                    }));
+                }
+                catch (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;
+            }
             if (req.method === 'POST' && path === '/api/block-studio/certify') {
                 try {
                     const body = await readJSON(req);
@@ -9913,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,
@@ -9924,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) {
@@ -10773,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));
@@ -10811,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);
@@ -12445,9 +13584,9 @@ export async function startLocalServer(opts) {
                         return;
                     }
                     const embeddedSourceSql = notebookCellRepairSql(cell);
-                    if (!embeddedSourceSql) {
+                    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 DQL cells with an embedded query. Edit this semantic DQL definition directly.' }));
+                        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)) {
@@ -12480,31 +13619,33 @@ export async function startLocalServer(opts) {
                     const parameters = body.parameters && typeof body.parameters === 'object' && !Array.isArray(body.parameters)
                         ? body.parameters
                         : {};
-                    const invocation = cell.type === 'dql'
-                        ? prepareBlockInvocation({ source: cell.source, parameters, surface: 'notebook' })
-                        : null;
-                    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);
+                    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 plan = cell.type === 'dql'
-                        ? buildExecutionPlan(cell, {
-                            semanticLayer,
-                            driver: targetConnection.driver,
-                            parameters: invocation?.values,
-                        })
-                        : null;
                     const attemptedSql = typeof body.attemptedSql === 'string' && body.attemptedSql.trim()
                         ? body.attemptedSql.trim()
                         : embeddedSourceSql;
-                    const sourceSql = plan?.sql ?? attemptedSql;
-                    const sqlParams = plan?.sqlParams ?? [];
-                    const variables = {
-                        ...(plan?.variables ?? {}),
-                        ...(invocation?.values ?? {}),
-                    };
                     const executionTarget = executionTargetDescriptor(body);
                     const targetConnectionName = executionTarget.target === 'connection'
                         ? executionTarget.connectionName
@@ -12515,24 +13656,48 @@ export async function startLocalServer(opts) {
                         `Repair notebook cell ${cell.title?.trim() || cell.id}.`,
                         submittedError ? `Failure: ${submittedError.slice(0, 1_000)}` : '',
                     ].filter(Boolean).join(' ');
-                    const repaired = await executeBoundedSqlRepair({
-                        question,
-                        sourceSql,
-                        targetConnection,
-                        targetConnectionName,
-                        sqlParams,
-                        variables,
-                    });
+                    let repaired;
                     let repairedSource;
-                    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);
+                    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 {
-                        repairedSource = repaired.repairedSql;
+                        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);
@@ -12543,12 +13708,13 @@ export async function startLocalServer(opts) {
                         const validationPlan = buildExecutionPlan({ ...cell, source: repairedSource }, {
                             semanticLayer,
                             driver: targetConnection.driver,
-                            parameters: invocation?.values,
+                            parameters: invocation?.values ?? parameters,
                         });
                         if (!validationPlan?.sql) {
                             throw boundedRepairError('The repaired SQL ran, but the DQL wrapper no longer compiles.', 422);
                         }
-                        const beforeParameters = sqlParams.map((parameter) => `${parameter.position}:${parameter.name}`);
+                        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);
@@ -13814,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;
@@ -14255,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;
@@ -17157,6 +18339,11 @@ export function notebookCellRepairSql(cell) {
     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())
@@ -17618,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,
@@ -19182,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) ?? '';
@@ -24272,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) {