@duckcodeailabs/dql-agent 1.13.4 → 1.14.0

package/dist/agent-run-engine.js

@@ -1,20 +1,22 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
+import { normalizeProviderEgressReceiptV1, } from '@duckcodeailabs/dql-core';
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { classifyConversationalTurn, decideAgentAction, } from "./intent-controller.js";
+import { classifyConversationalTurn, decideAgentAction, looksLikeComposeApp, } from "./intent-controller.js";
 import { selectCascadeRunRoute } from "./cascade/route-policy.js";
 import { canUseEngineEscalation, canUseLaneRepair, cascadeBudgetTrace, createCascadeBudgetState, recordEngineEscalation, recordLaneRepair, } from "./cascade/budgets.js";
+import { buildAnalysisQuestionPlan } from "./metadata/analysis-planner.js";
 import { conversationHistoryFromContext, isLikelyClarificationReply, } from "./conversation/snapshot.js";
 /** Routes a stakeholder may never land on (analyst authoring lives in the Notebook). */
 const ANALYST_ONLY_ROUTES = new Set(["sql_cell", "dql_block_draft", "modeling_draft", "skill_draft"]);
 /**
- * Compare the pre-execution plan with the legacy route without changing the
- * route. This is the R3 shadow-mode cutover signal used before R4 enforcement.
+ * Compare the pre-execution plan with the selected route without changing it.
+ * Authoritative plans never emit or persist this migration-only diagnostic.
  * Acceptance: AGT-013, API-006.
  */
 export function compareResolvedPlanShadow(decision, actualRoute) {
     const plan = decision.resolvedAnalyticalPlan;
-    if (!plan)
+    if (!plan || plan.mode !== 'shadow')
         return undefined;
     const plannedRoute = decision.action === 'investigate'
         ? 'research'
@@ -35,7 +37,70 @@ export function compareResolvedPlanShadow(decision, actualRoute) {
         matches: plannedRoute === actualRoute,
     };
 }
+/** Stable host-issued reason for a user cancellation. Provider AbortErrors do
+ * not carry this code and therefore remain distinguishable executor failures. */
+export const AGENT_RUN_USER_CANCEL_CODE = "RUN_CANCELLED";
+export function createAgentRunCancellationError() {
+    return Object.assign(new Error("Stopped by user."), { code: AGENT_RUN_USER_CANCEL_CODE });
+}
+export function isAgentRunUserCancellation(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    return error.code === AGENT_RUN_USER_CANCEL_CODE;
+}
 const DEFAULT_MAX_STEPS = 4;
+export function agentRouteDeadlineMs(route) {
+    if (route === 'certified_answer' || route === 'semantic_answer')
+        return 5_000;
+    if (route === 'clarify')
+        return 10_000;
+    // Generation may now take a genuine tool round (look something up, then use
+    // it) instead of a single blind shot, so the discovery window has to cover it.
+    // Subscription-CLI providers cost roughly 10-15s per dispatch, so a window
+    // under ~30s silently reduces the loop back to a single blind attempt.
+    if (route === 'generated_answer')
+        return 30_000;
+    if (route === 'research')
+        return 120_000;
+    return undefined;
+}
+/** The request envelope starts before retrieval/routing, so a stuck router can
+ * never evade the route-specific deadline that is selected later. */
+export function agentRequestDeadlineMs(requestedMode) {
+    return requestedMode === 'research' ? 120_000 : 45_000;
+}
+/** Create the one request-ingress deadline authority used by every stage. */
+export function createAgentRunBudget(input) {
+    const nowMs = input.nowMs ?? Date.now;
+    const startedAtMs = input.startedAtMs ?? nowMs();
+    const mode = input.requestedMode === 'research' ? 'research' : 'ask';
+    const hardDeadlineMs = mode === 'research' ? 120_000 : 45_000;
+    const timeout = (input.timeoutSignal ?? AbortSignal.timeout)(hardDeadlineMs);
+    const hardSignal = input.inheritedSignal
+        ? AbortSignal.any([input.inheritedSignal, timeout])
+        : timeout;
+    const elapsedMs = () => Math.max(0, nowMs() - startedAtMs);
+    const softTargetMs = (route) => {
+        if (mode === 'research')
+            return 90_000;
+        return agentRouteDeadlineMs(route) ?? 15_000;
+    };
+    // Narration must still be reachable after a full generation window, and must
+    // leave the hard deadline (45s ask / 120s research) room to land.
+    const narrationSoftTargetMs = () => (mode === 'research' ? 100_000 : 38_000);
+    return Object.freeze({
+        startedAtMs,
+        hardDeadlineMs,
+        hardSignal,
+        mode,
+        elapsedMs,
+        remainingMs: () => Math.max(0, hardDeadlineMs - elapsedMs()),
+        softTargetMs,
+        mayStartDiscovery: (route) => !hardSignal.aborted && elapsedMs() < softTargetMs(route),
+        narrationSoftTargetMs,
+        mayStartNarration: () => !hardSignal.aborted && elapsedMs() < narrationSoftTargetMs(),
+    });
+}
 /**
  * Routes whose gate failure is better answered by switching routes than by
  * re-running the same executor (repair can't add what the route can't produce).
@@ -250,7 +315,7 @@ export function escalationRouteFor(route, audience) {
     if (!target)
         return undefined;
     if (audience === "stakeholder" && ANALYST_ONLY_ROUTES.has(target))
-        return "research";
+        return "generated_answer";
     return target;
 }
 /** The handoff action shown on a stakeholder's review-required output. */
@@ -369,6 +434,7 @@ export class AgentRunEngine {
     now;
     budgetModel;
     maxSteps;
+    routeTimeoutSignal;
     constructor(options = {}) {
         this.executors = options.executors ?? {};
         this.gates = options.gates ?? {};
@@ -386,6 +452,7 @@ export class AgentRunEngine {
             engineEscalations: options.maxEngineEscalations ?? options.budgets?.engineEscalations,
         };
         this.maxSteps = Math.max(1, options.maxSteps ?? DEFAULT_MAX_STEPS);
+        this.routeTimeoutSignal = options.routeTimeoutSignal ?? ((durationMs) => AbortSignal.timeout(durationMs));
     }
     /**
      * Decide the high-level action. A forced `requestedMode` bypasses routing.
@@ -406,7 +473,8 @@ export class AgentRunEngine {
                 if (request.requestedMode === "ask"
                     && routed.action !== "converse"
                     && routed.action !== "compose_app"
-                    && routed.requiresClarification !== true) {
+                    && routed.requiresClarification !== true
+                    && !routed.terminalOutcome) {
                     return { ...routed, action: "answer" };
                 }
                 return routed;
@@ -440,7 +508,16 @@ export class AgentRunEngine {
         }
         const runId = request.runId ?? this.idGenerator();
         const startedAt = this.timestamp();
+        const runStartedAtMs = Date.parse(startedAt);
         const requestedMode = request.requestedMode ?? "auto";
+        const runBudget = request.runBudget ?? createAgentRunBudget({
+            requestedMode,
+            startedAtMs: runStartedAtMs,
+            inheritedSignal: request.signal,
+            timeoutSignal: this.routeTimeoutSignal,
+            nowMs: () => this.now().getTime(),
+        });
+        request = { ...request, runBudget, signal: runBudget.hardSignal };
         const events = [];
         let plan;
         const executedSteps = [];
@@ -550,15 +627,22 @@ export class AgentRunEngine {
                     followsUp: true,
                     source: "heuristic",
                 }
-                : await this.decideRoute(request);
+                : await awaitWithAbort(this.decideRoute(request), request.signal);
+            routeDecision = enforceOrdinaryAnalyticalPlanBoundary(request, routeDecision);
             const defaultRoute = answerAnywayRoute(constrainRouteForAudience(selectRoute(request, routeDecision), audience), request, audience, routeDecision);
-            plan = await this.planner.plan({
+            const authoritativeAsk = routeDecision.resolvedAnalyticalPlan?.mode === 'authoritative'
+                && requestedMode !== 'research';
+            const activePlanner = authoritativeAsk
+                ? createDeterministicAgentRunPlanner()
+                : this.planner;
+            const planningSignal = request.runBudget?.hardSignal ?? request.signal;
+            plan = await awaitWithAbort(Promise.resolve(activePlanner.plan({
                 request,
                 routeDecision,
                 defaultRoute,
                 maxSteps: this.maxSteps,
                 audience,
-            });
+            })), planningSignal);
             emit({
                 type: "plan.created",
                 message: plan.rationale,
@@ -643,6 +727,11 @@ export class AgentRunEngine {
                         emitAnswerDelta: onAnswerDelta,
                     });
                     result = consumeRepeatedClarificationSelection(request, routeDecision, result);
+                    if (result.analyticalTurnPlan)
+                        progress.analyticalTurnPlan = result.analyticalTurnPlan;
+                    if (result.analyticalTaskOutcomes)
+                        progress.analyticalTaskOutcomes = result.analyticalTaskOutcomes;
+                    persistProgress();
                     evaluations = this.evaluate({ route, request, routeDecision, result, attempt });
                     for (const evaluation of evaluations) {
                         emit({
@@ -662,6 +751,13 @@ export class AgentRunEngine {
                         stepStatus = attempt > 0 ? "repaired" : "passed";
                         break;
                     }
+                    // A frozen analytical plan has one route and no downstream planner,
+                    // rematch, route escalation, or whole-answer regeneration authority.
+                    // Typed server-issued repair is a separate derived run.
+                    if (authoritativeAsk) {
+                        stepStatus = 'needs_review';
+                        break;
+                    }
                     const currentStep = {
                         id: stepId,
                         index: stepCount,
@@ -674,7 +770,7 @@ export class AgentRunEngine {
                         evaluations,
                         artifacts: result.artifacts ?? [],
                     };
-                    const decision = await this.planner.replan({
+                    const decision = await activePlanner.replan({
                         request,
                         plan,
                         currentStep,
@@ -779,7 +875,7 @@ export class AgentRunEngine {
                     });
                     continue;
                 }
-                const outcome = computeStepOutcome(route, result, evaluations, request, isClarify, clarifyQuestion);
+                const outcome = computeStepOutcome(route, result, evaluations, request, isClarify, clarifyQuestion, routeDecision.terminalOutcome?.message);
                 const step = {
                     id: stepId,
                     index: stepCount,
@@ -862,15 +958,102 @@ export class AgentRunEngine {
             run.completedAt = this.timestamp();
             run.lifecycle = terminalLifecycle(progress.lifecycle, run.status === "blocked" ? "run.failed" : "run.completed", run.completedAt, events.length);
             run.diagnosticReceipt = diagnosticReceiptForRun(run);
-            run.artifacts = attachDiagnosticReceipt(run.artifacts, run.diagnosticReceipt);
+            run.diagnosticReceiptV2 = diagnosticReceiptV2ForRun(run);
+            run.artifacts = attachDiagnosticReceipt(run.artifacts, run.diagnosticReceipt, run.diagnosticReceiptV2);
             await checkpointQueue;
             await this.store?.save(run);
             return run;
         }
         catch (err) {
-            const message = err instanceof Error && err.name === "TimeoutError"
-                ? "This analytical run reached its time limit before it finished. A timeout alone does not prove a cross-model join or semantic-modeling problem. Open Trust & Steps to see the last recorded phase; retry the same bounded question or use Research for a longer budget. No result was accepted."
-                : err instanceof Error ? err.message : String(err);
+            const dispatchEvidence = providerDispatchEvidenceFromError(err);
+            const userCancelled = isAgentRunUserCancellation(request.signal?.reason) || isAgentRunUserCancellation(err);
+            if (userCancelled) {
+                const message = "Stopped by user.";
+                const cancelledRoute = progress.route ?? "cancelled";
+                const cancelledPhase = progress.lifecycle.phase;
+                emit({
+                    type: "run.cancelled",
+                    message,
+                    route: cancelledRoute,
+                    status: "cancelled",
+                    trustState: "not_applicable",
+                });
+                const completedAt = this.timestamp();
+                const failure = {
+                    code: AGENT_RUN_USER_CANCEL_CODE,
+                    phase: cancelledPhase,
+                    message,
+                    recoverable: false,
+                    safeActions: [],
+                };
+                const evaluations = [
+                    ...progress.evaluations,
+                    {
+                        id: "run-cancelled",
+                        label: "Run cancelled",
+                        passed: true,
+                        severity: "info",
+                        message,
+                    },
+                ];
+                const receipt = {
+                    version: 1,
+                    runId,
+                    phase: failure.phase,
+                    route: cancelledRoute,
+                    plan,
+                    steps: executedSteps,
+                    artifacts: progress.artifacts,
+                    evaluations,
+                    failure,
+                };
+                const run = {
+                    id: runId,
+                    question: submittedQuestion,
+                    requestedMode,
+                    route: cancelledRoute,
+                    status: "cancelled",
+                    trustState: "not_applicable",
+                    stopReason: "cancelled",
+                    startedAt,
+                    completedAt,
+                    selectedObject: request.selectedObject,
+                    executionTarget: request.executionTarget,
+                    routeDecision,
+                    plan,
+                    steps: executedSteps,
+                    summary: message,
+                    artifacts: progress.artifacts,
+                    evaluations,
+                    events,
+                    nextActions: [],
+                    repairAttempts: 0,
+                    escalationAttempts: 0,
+                    budgetUsage: cascadeBudgetTrace(createCascadeBudgetState(this.budgetModel)),
+                    diagnosticReceipt: receipt,
+                    ...(dispatchEvidence.providerEgressReceipts.length
+                        ? { providerEgressReceipts: dispatchEvidence.providerEgressReceipts }
+                        : {}),
+                    telemetry: {
+                        ...emptyRunTelemetry(durationBetweenMs(startedAt, completedAt), "cancelled"),
+                        providerRoundTrips: dispatchEvidence.providerRoundTrips,
+                        toolCalls: dispatchEvidence.toolCalls,
+                        sqlExecutions: dispatchEvidence.sqlExecutions,
+                        repairs: dispatchEvidence.repairs,
+                        egressReceipts: dispatchEvidence.providerEgressReceipts.length,
+                    },
+                    lifecycle: terminalLifecycle(progress.lifecycle, "run.cancelled", completedAt, events.length),
+                };
+                run.diagnosticReceiptV2 = diagnosticReceiptV2ForRun(run);
+                await checkpointQueue;
+                await this.store?.save(run);
+                return run;
+            }
+            const message = isOrchestrationBudgetExhausted(err)
+                ? 'Ask could not complete within its bounded orchestration. Nothing was executed; narrow the metric or dimension and retry.'
+                : err instanceof Error && err.name === "TimeoutError"
+                    ? "This analytical run reached its time limit before it finished. A timeout alone does not prove a cross-model join or semantic-modeling problem. Open Trust & Steps to see the last recorded phase; retry the same bounded question or use Research for a longer budget. No result was accepted."
+                    : err instanceof Error ? err.message : String(err);
             const failedRoute = progress.route;
             const failedPhase = progress.lifecycle.phase;
             emit({
@@ -931,8 +1114,21 @@ export class AgentRunEngine {
                 escalationAttempts: 0,
                 budgetUsage: cascadeBudgetTrace(createCascadeBudgetState(this.budgetModel)),
                 diagnosticReceipt: receipt,
+                ...(dispatchEvidence.providerEgressReceipts.length
+                    ? { providerEgressReceipts: dispatchEvidence.providerEgressReceipts }
+                    : {}),
+                telemetry: {
+                    ...emptyRunTelemetry(durationBetweenMs(startedAt, completedAt), dispatchEvidence.fallbackReason),
+                    providerRoundTrips: dispatchEvidence.providerRoundTrips,
+                    toolCalls: dispatchEvidence.toolCalls,
+                    sqlExecutions: dispatchEvidence.sqlExecutions,
+                    repairs: dispatchEvidence.repairs,
+                    egressReceipts: dispatchEvidence.providerEgressReceipts.length,
+                },
                 lifecycle: terminalLifecycle(progress.lifecycle, "run.failed", completedAt, events.length),
             };
+            run.diagnosticReceiptV2 = diagnosticReceiptV2ForRun(run);
+            run.artifacts = attachDiagnosticReceipt(retainedArtifacts, receipt, run.diagnosticReceiptV2);
             await checkpointQueue;
             await this.store?.save(run);
             return run;
@@ -985,8 +1181,12 @@ export class AgentRunEngine {
         // If the final step produced no user-facing answer (e.g. it only drafted an
         // artifact), fall back to the last step that DID answer so the run never
         // drops a data answer an earlier step already computed.
-        const finalHasAnswer = typeof finalResult.answer === "string" && finalResult.answer.trim().length > 0;
+        const finalHasAnswer = finalOutcome.status !== "blocked"
+            && typeof finalResult.answer === "string" && finalResult.answer.trim().length > 0;
         const answerSource = finalHasAnswer ? finalResult : (input.bestAnswerResult ?? finalResult);
+        const acceptedAnswer = finalOutcome.status === "blocked"
+            ? finalOutcome.summary
+            : input.clarifyOutcome?.question ?? answerSource.answer;
         return {
             id: input.runId,
             question: input.request.question,
@@ -1003,7 +1203,7 @@ export class AgentRunEngine {
             plan: input.plan,
             steps: input.steps,
             summary: finalOutcome.summary,
-            answer: input.clarifyOutcome?.question ?? answerSource.answer,
+            answer: acceptedAnswer,
             answerKind: answerSource.answerKind ?? "governed",
             artifacts,
             evaluations: finalStep.evaluations,
@@ -1014,8 +1214,16 @@ export class AgentRunEngine {
                 ? { clarificationOptions: finalResult.clarificationOptions ?? input.routeDecision.clarificationOptions }
                 : {}),
             repairAttempts: finalResult.repairAttempts ?? repairAttempts,
+            ...(finalResult.providerEgressReceipts?.length
+                ? { providerEgressReceipts: finalResult.providerEgressReceipts }
+                : {}),
+            ...(finalResult.telemetry ? {
+                telemetry: withTotalDuration(finalResult.telemetry, durationBetweenMs(input.startedAt, completedAt)),
+            } : {}),
             escalationAttempts,
             budgetUsage: input.budgetUsage,
+            ...(finalResult.analyticalTurnPlan ? { analyticalTurnPlan: finalResult.analyticalTurnPlan } : {}),
+            ...(finalResult.analyticalTaskOutcomes ? { analyticalTaskOutcomes: finalResult.analyticalTaskOutcomes } : {}),
             ...authoringDerivationFromRequest(input.request),
         };
     }
@@ -1028,14 +1236,229 @@ export class AgentRunEngine {
     }
     async executeRoute(context) {
         const executor = this.executors[context.route];
-        if (executor)
-            return executor(context);
+        if (executor) {
+            const frozenPlan = context.routeDecision?.resolvedAnalyticalPlan?.mode === 'authoritative';
+            const startsAnalyticalWork = context.route === 'certified_answer'
+                || context.route === 'semantic_answer'
+                || context.route === 'generated_answer'
+                || context.route === 'research';
+            if (startsAnalyticalWork
+                && !frozenPlan
+                && context.request.runBudget
+                && !context.request.runBudget.mayStartDiscovery(context.route)) {
+                return softBoundaryResult(context.route, context.request.runBudget);
+            }
+            const signal = context.request.runBudget?.hardSignal ?? context.request.signal;
+            if (signal?.aborted)
+                throw signal.reason ?? routeTimeoutError();
+            const execution = Promise.resolve(executor({
+                ...context,
+                request: { ...context.request, ...(signal ? { signal } : {}) },
+            }));
+            return awaitWithAbort(execution, signal);
+        }
         return defaultExecutorResult(context.route, context.request, context.routeDecision);
     }
+    absoluteDeadlineSignal(deadlineMs, runStartedAtMs, inherited) {
+        const elapsedMs = Math.max(0, this.now().getTime() - runStartedAtMs);
+        const remainingMs = deadlineMs - elapsedMs;
+        const deadlineSignal = remainingMs <= 0
+            ? alreadyAbortedSignal(routeTimeoutError())
+            : this.routeTimeoutSignal(remainingMs);
+        return inherited ? AbortSignal.any([inherited, deadlineSignal]) : deadlineSignal;
+    }
     timestamp() {
         return this.now().toISOString();
     }
 }
+/**
+ * Ordinary analytical Ask cannot delegate meaning to the legacy answer
+ * generator. Retrieval/meaning must first produce the immutable RAP consumed by
+ * every later compiler and executor. This host-side gate protects callers that
+ * inject or deserialize an older router decision as well as the canonical
+ * router producer.
+ */
+function enforceOrdinaryAnalyticalPlanBoundary(request, decision) {
+    const ordinaryAsk = request.requestedMode === undefined
+        || request.requestedMode === 'auto'
+        || request.requestedMode === 'ask';
+    const terminal = decision.action === 'clarify'
+        || decision.action === 'block'
+        || decision.requiresClarification === true
+        || Boolean(decision.terminalOutcome);
+    // A modeling/coverage gap is a pre-freeze discovery result, not permission to
+    // terminate an ordinary Ask. Keep the diagnostic as a typed reason in the
+    // route decision, clear the blocked RAP, and let the answer executor continue
+    // through the governed relational and review-required generated lanes. Policy
+    // blocks and genuine user ambiguity remain terminal. This is the key
+    // governed-first-but-not-governed-only boundary (AGT-028, EXP-001).
+    if (ordinaryAsk
+        && decision.terminalOutcome?.kind === 'modeling_gap'
+        && decision.requiresClarification !== true
+        && !request.selectedEvidenceId) {
+        return {
+            ...decision,
+            action: 'answer',
+            confidence: Math.min(decision.confidence, 0.55),
+            reason: `${decision.terminalOutcome.message} Continuing through DBT-grounded relational and review-required generated analysis before asking for a modeling change.`,
+            terminalOutcome: undefined,
+            resolvedAnalyticalPlan: undefined,
+            requiresClarification: false,
+        };
+    }
+    const exactSemanticContinuation = Boolean(request.selectedEvidenceId
+        && decision.meaningResolution?.recommendedRoute === 'semantic'
+        && decision.meaningResolution.recommendedExecutionId === request.selectedEvidenceId);
+    if (!ordinaryAsk
+        || terminal
+        || exactSemanticContinuation
+        || decision.resolvedAnalyticalPlan?.mode === 'authoritative')
+        return decision;
+    const explicitAuthoring = looksLikeComposeApp(request.question)
+        || /\b(sql\s+(?:notebook\s+)?cell|notebook\s+cell|write a select|generate a query|dql block|block draft|draft block|create[^.?!]*block|turn[^.?!]*into[^.?!]*block)\b/i.test(request.question);
+    if (explicitAuthoring)
+        return decision;
+    const history = request.history?.length
+        ? request.history
+        : conversationHistoryFromContext(request.conversationContext);
+    const questionPlan = buildAnalysisQuestionPlan(request.question);
+    const conversationalKind = classifyConversationalTurn(request.question, history.length > 0 || Boolean(request.conversationContext && Object.keys(request.conversationContext).length > 0));
+    const definitionOnly = questionPlan.mode === 'definition'
+        && questionPlan.requestedShape.dimensions.length === 0
+        && questionPlan.requestedShape.filters.length === 0
+        && questionPlan.timeTerms.length === 0;
+    // Router category/action are advisory and may be absent or forged. A
+    // deterministic host parse owns the no-data lanes too, so a forged
+    // `data_analysis` cannot turn "hi" into SQL and a forged `answer` cannot
+    // turn a glossary definition into an analytical execution.
+    if (ordinaryAsk && (conversationalKind || definitionOnly)) {
+        return {
+            ...decision,
+            action: 'converse',
+            category: 'conversational',
+            ...(conversationalKind ? { conversationalKind } : {}),
+            confidence: 1,
+            reason: definitionOnly
+                ? 'This requests a definition, not a warehouse result, so no analytical execution is needed.'
+                : 'This is a conversational turn and does not request governed data.',
+            requiresClarification: false,
+        };
+    }
+    const analyticalIntents = new Set([
+        'exact_certified_lookup',
+        'ad_hoc_ranking',
+        'driver_breakdown',
+        'diagnose_change',
+        'segment_compare',
+        'entity_drilldown',
+        'anomaly_investigation',
+    ]);
+    const analyticalIntent = analyticalIntents.has(questionPlan.routeIntent)
+        || Boolean(request.intent && analyticalIntents.has(request.intent));
+    const analyticalShape = questionPlan.mode !== 'clarify'
+        && questionPlan.mode !== 'definition'
+        && (questionPlan.requestedShape.measures.length > 0
+            || questionPlan.requestedShape.dimensions.length > 0
+            || questionPlan.requestedShape.filters.length > 0
+            || questionPlan.timeTerms.length > 0
+            || questionPlan.requestedShape.rankingDirection !== undefined);
+    const governedEvidence = (decision.retrievalEvidence?.candidateCount ?? 0) > 0
+        || (decision.meaningResolution?.selectedConceptIds.length ?? 0) > 0;
+    const analytical = analyticalIntent || analyticalShape || governedEvidence;
+    if (!analytical)
+        return decision;
+    const message = 'DQL could not freeze an exact analytical plan for the requested metric, grain, filters, ordering, and outputs. Choose a governed identifier or model the missing capability before retrying.';
+    return {
+        ...decision,
+        action: 'block',
+        confidence: 1,
+        reason: message,
+        requiresClarification: false,
+        terminalOutcome: {
+            kind: 'modeling_gap',
+            code: 'ANALYTICAL_MODELING_GAP',
+            message,
+            candidateIds: decision.retrievalEvidence?.candidateIds ?? [],
+        },
+    };
+}
+function softBoundaryResult(route, budget) {
+    const seconds = Math.round(budget.softTargetMs(route) / 1_000);
+    return {
+        resolvedRoute: 'clarify',
+        status: 'needs_clarification',
+        trustState: 'blocked',
+        stopReason: 'needs_clarification',
+        summary: `The ${seconds}-second discovery target elapsed before an analytical plan was frozen. No new provider, tool, or retrieval branch was started.`,
+        answer: budget.mode === 'research'
+            ? 'Research stopped starting new branches at 90 seconds. Refine the question or retry; any already validated partial findings remain available.'
+            : 'The discovery window ended before DQL could freeze an exact analytical plan. Refine the metric or grain, or retry the same bounded question.',
+        artifacts: [],
+        evaluations: [],
+        nextActions: [{ id: 'retry-after-soft-target', label: 'Retry the same question' }],
+    };
+}
+function providerDispatchEvidenceFromError(error) {
+    const empty = {
+        providerEgressReceipts: [],
+        providerRoundTrips: 0,
+        toolCalls: 0,
+        sqlExecutions: 0,
+        repairs: 0,
+        fallbackReason: 'executor_failure',
+    };
+    if (!error || typeof error !== 'object')
+        return empty;
+    const value = error.providerDispatchEvidence;
+    if (!value || typeof value !== 'object')
+        return empty;
+    const record = value;
+    const count = (key) => Number.isInteger(record[key]) && Number(record[key]) >= 0 ? Number(record[key]) : 0;
+    return {
+        providerEgressReceipts: Array.isArray(record.providerEgressReceipts)
+            ? record.providerEgressReceipts.flatMap((receipt) => {
+                const normalized = normalizeProviderEgressReceiptV1(receipt);
+                return normalized ? [normalized] : [];
+            })
+            : [],
+        providerRoundTrips: count('providerRoundTrips'),
+        toolCalls: count('toolCalls'),
+        sqlExecutions: count('sqlExecutions'),
+        repairs: count('repairs'),
+        fallbackReason: typeof record.fallbackReason === 'string' ? record.fallbackReason : 'executor_failure',
+    };
+}
+function alreadyAbortedSignal(reason) {
+    const controller = new AbortController();
+    controller.abort(reason);
+    return controller.signal;
+}
+function routeTimeoutError() {
+    return new DOMException('The absolute agent route deadline elapsed.', 'TimeoutError');
+}
+function awaitWithAbort(work, signal) {
+    if (!signal)
+        return work;
+    if (signal.aborted) {
+        // The callee may already have started before its cancellation state was
+        // observed. Consume any eventual rejection while refusing its result.
+        void work.catch(() => undefined);
+        return Promise.reject(signal.reason ?? new DOMException('The operation was aborted.', 'AbortError'));
+    }
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (callback) => {
+            if (settled)
+                return;
+            settled = true;
+            signal.removeEventListener('abort', onAbort);
+            callback();
+        };
+        const onAbort = () => finish(() => reject(signal.reason ?? new DOMException('The operation was aborted.', 'AbortError')));
+        signal.addEventListener('abort', onAbort, { once: true });
+        work.then((value) => finish(() => resolve(value)), (error) => finish(() => reject(error)));
+    });
+}
 function authoringDerivationFromRequest(request) {
     if (request.requestedMode !== 'modeling' && request.requestedMode !== 'skill')
         return {};
@@ -1073,6 +1496,15 @@ function diagnosticFailureFromError(error, phase) {
     const name = error instanceof Error ? error.name : "";
     const message = error instanceof Error ? error.message : String(error);
     const lower = `${name} ${message}`.toLowerCase();
+    if (isOrchestrationBudgetExhausted(error)) {
+        return {
+            code: 'orchestration_budget_exhausted',
+            phase,
+            message: 'Ask exhausted its bounded orchestration before a final answer was available.',
+            recoverable: false,
+            safeActions: ['inspect_failure'],
+        };
+    }
     if (name === "TimeoutError" || lower.includes("time limit") || lower.includes("timeout")) {
         return {
             code: "TIMEOUT",
@@ -1082,13 +1514,13 @@ function diagnosticFailureFromError(error, phase) {
             safeActions: ["retry_same_plan"],
         };
     }
-    if (lower.includes("stopped by user") || lower.includes("cancel")) {
+    if (isAgentRunUserCancellation(error)) {
         return {
             code: "RUN_CANCELLED",
             phase,
-            message,
-            recoverable: true,
-            safeActions: ["retry_same_request"],
+            message: "Stopped by user.",
+            recoverable: false,
+            safeActions: [],
         };
     }
     return {
@@ -1099,6 +1531,14 @@ function diagnosticFailureFromError(error, phase) {
         safeActions: ["retry_same_request", "inspect_failure"],
     };
 }
+function isOrchestrationBudgetExhausted(error) {
+    if (!error || typeof error !== 'object')
+        return false;
+    if (error.code === 'PROVIDER_DISPATCH_BUDGET_EXHAUSTED')
+        return true;
+    const message = error instanceof Error ? error.message : String(error);
+    return /(?:run-wide provider dispatch|orchestration) budget exhausted/i.test(message);
+}
 function diagnosticReceiptForRun(run) {
     const failureEvaluation = run.evaluations.find((evaluation) => !evaluation.passed && evaluation.severity === "blocking");
     const analyticalFailure = run.artifacts
@@ -1118,7 +1558,7 @@ function diagnosticReceiptForRun(run) {
     return {
         version: 1,
         runId: run.id,
-        phase: run.lifecycle?.phase ?? (run.status === "blocked" ? "run.failed" : "run.completed"),
+        phase: run.lifecycle?.phase ?? (run.status === "blocked" ? "run.failed" : run.status === "cancelled" ? "run.cancelled" : "run.completed"),
         route: run.route,
         ...(run.routeDecision?.resolvedAnalyticalPlan
             ? { resolvedAnalyticalPlan: run.routeDecision.resolvedAnalyticalPlan }
@@ -1127,20 +1567,59 @@ function diagnosticReceiptForRun(run) {
         steps: run.steps,
         artifacts: run.artifacts,
         evaluations: run.evaluations,
-        ...(run.status === "blocked"
+        ...(run.repairCapability ? { repairCapability: run.repairCapability } : {}),
+        ...(run.providerEgressReceipts?.length ? { providerEgressReceipts: run.providerEgressReceipts } : {}),
+        ...(run.status === "blocked" || run.status === "cancelled"
             ? {
                 failure: {
-                    code: failureCode,
-                    phase: run.lifecycle?.phase ?? "run.failed",
-                    message: failureEvaluation?.message ?? run.summary,
-                    recoverable: Boolean(run.nextActions.length),
-                    safeActions: run.nextActions.map((action) => action.id),
+                    code: run.status === "cancelled" ? AGENT_RUN_USER_CANCEL_CODE : failureCode,
+                    phase: run.lifecycle?.phase ?? (run.status === "cancelled" ? "run.cancelled" : "run.failed"),
+                    message: run.status === "cancelled" ? "Stopped by user." : failureEvaluation?.message ?? run.summary,
+                    recoverable: run.status === "cancelled" ? false : Boolean(run.nextActions.length),
+                    safeActions: run.status === "cancelled" ? [] : run.nextActions.map((action) => action.id),
                 },
             }
             : {}),
     };
 }
-function attachDiagnosticReceipt(artifacts, receipt) {
+function diagnosticReceiptV2ForRun(run) {
+    const telemetry = run.telemetry ?? emptyRunTelemetry(durationBetweenMs(run.startedAt, run.completedAt), 'not_recorded');
+    return {
+        version: 2,
+        runId: run.id,
+        route: run.route,
+        status: run.status,
+        telemetry,
+        providerEgressReceiptFingerprints: (run.providerEgressReceipts ?? []).map(receiptFingerprint),
+        ...(run.repairCapability ? { repairCapabilityFingerprint: receiptFingerprint(run.repairCapability) } : {}),
+    };
+}
+function emptyRunTelemetry(total, fallbackReason) {
+    return {
+        version: 1,
+        stageDurationsMs: { total },
+        providerRoundTrips: 0,
+        toolCalls: 0,
+        sqlExecutions: 0,
+        repairs: 0,
+        egressReceipts: 0,
+        fallbackReason,
+    };
+}
+function withTotalDuration(telemetry, total) {
+    return {
+        ...telemetry,
+        stageDurationsMs: { ...telemetry.stageDurationsMs, total },
+    };
+}
+function durationBetweenMs(startedAt, completedAt) {
+    const duration = Date.parse(completedAt) - Date.parse(startedAt);
+    return Number.isFinite(duration) && duration >= 0 ? Math.min(86_400_000, duration) : 0;
+}
+function receiptFingerprint(value) {
+    return createHash('sha256').update(JSON.stringify(value)).digest('hex');
+}
+function attachDiagnosticReceipt(artifacts, receipt, receiptV2) {
     if (artifacts.length === 0) {
         if (!receipt.failure)
             return artifacts;
@@ -1149,7 +1628,7 @@ function attachDiagnosticReceipt(artifacts, receipt) {
                 kind: "answer",
                 title: "Agent run diagnostics",
                 trustState: "blocked",
-                payload: { diagnosticReceipt: receipt },
+                payload: { diagnosticReceipt: receipt, ...(receiptV2 ? { diagnosticReceiptV2: receiptV2 } : {}) },
             }];
     }
     const preferredIndex = Math.max(0, artifacts.findIndex((artifact) => artifact.kind === "answer"));
@@ -1164,11 +1643,12 @@ function attachDiagnosticReceipt(artifacts, receipt) {
             payload: {
                 ...payload,
                 diagnosticReceipt: receipt,
+                ...(receiptV2 ? { diagnosticReceiptV2: receiptV2 } : {}),
             },
         };
     });
 }
-function computeStepOutcome(route, result, evaluations, request, isClarify, clarifyQuestion) {
+function computeStepOutcome(route, result, evaluations, request, isClarify, clarifyQuestion, terminalOutcomeMessage) {
     const fallback = defaultOutcome(route);
     if (isClarify) {
         return {
@@ -1195,10 +1675,21 @@ function computeStepOutcome(route, result, evaluations, request, isClarify, clar
         trustState,
         artifacts,
         stopReason,
-        summary: result.summary ?? fallback.summary,
+        summary: status === "blocked"
+            ? terminalOutcomeMessage ?? blockingOutcomeSummary(evaluations, fallback.summary)
+            : result.summary ?? fallback.summary,
         ...(result.answerTier ? { terminalTier: result.answerTier } : {}),
     };
 }
+function blockingOutcomeSummary(evaluations, fallback) {
+    const messages = evaluations
+        .filter((evaluation) => !evaluation.passed && evaluation.severity === 'blocking')
+        .map((evaluation) => evaluation.message.trim())
+        .filter(Boolean);
+    return messages[0] ?? (fallback.includes('Answered')
+        ? 'The analytical result did not pass its required validation and was not accepted.'
+        : fallback);
+}
 function consumeRepeatedClarificationSelection(request, routeDecision, result) {
     const selectedEvidenceId = request.selectedEvidenceId;
     if (!selectedEvidenceId || result.status !== 'needs_clarification')
@@ -1282,7 +1773,7 @@ export function createDeterministicAgentRunPlanner() {
             // Honor an explicit escalate target, else the route's default — then clamp for the audience.
             const rawEscalation = requested ?? AGENT_RUN_ESCALATION_MAP[currentStep.route];
             const escalationRoute = rawEscalation
-                ? (audience === "stakeholder" && ANALYST_ONLY_ROUTES.has(rawEscalation) ? "research" : rawEscalation)
+                ? (audience === "stakeholder" && ANALYST_ONLY_ROUTES.has(rawEscalation) ? "generated_answer" : rawEscalation)
                 : undefined;
             const hint = action?.hint ?? failing.suggestedRepair ?? "Revise and retry.";
             if (action?.kind === "escalate" && escalationRoute) {
@@ -1376,6 +1867,19 @@ function requestedModeToAction(mode) {
 export function selectRoute(request, decision) {
     if (decision.meaningResolutionErrorCode === 'invalid_evidence_reference')
         return 'blocked';
+    if (decision.action === 'block')
+        return 'blocked';
+    const authoritativePlan = decision.resolvedAnalyticalPlan?.mode === 'authoritative'
+        ? decision.resolvedAnalyticalPlan
+        : undefined;
+    // Producer invariant: the immutable plan is the authority. A caller cannot
+    // combine an answer decision with blocked capability and suppress both the
+    // typed clarification and modeling/policy diagnostic.
+    if (authoritativePlan?.capability === 'blocked') {
+        if (decision.requiresClarification === true)
+            return 'clarify';
+        return 'blocked';
+    }
     const explicitMode = request.requestedMode;
     if (explicitMode === 'modeling')
         return 'modeling_draft';
@@ -1384,9 +1888,21 @@ export function selectRoute(request, decision) {
     if (explicitMode && explicitMode !== 'auto' && explicitMode !== 'ask') {
         return selectCascadeRunRoute(request, decision);
     }
+    const plan = decision.resolvedAnalyticalPlan;
+    // Research is an explicit request mode, never a phrase/category/depth
+    // inference. Diagnosis and bounded exploration in ordinary Ask stay on the
+    // review-required generated route over the same frozen plan.
+    if (decision.action === 'investigate') {
+        if (plan?.capability === 'certified_execution')
+            return 'certified_answer';
+        if (plan?.capability === 'semantic_execution')
+            return 'semantic_answer';
+        if (plan?.capability === 'governed_relational' || plan?.capability === 'bounded_exploration')
+            return 'generated_answer';
+        return decision.requiresClarification ? 'clarify' : 'blocked';
+    }
     if (decision.action !== 'answer')
         return selectCascadeRunRoute(request, decision);
-    const plan = decision.resolvedAnalyticalPlan;
     if (plan?.mode === 'authoritative' && decision.requiresClarification !== true) {
         if (plan.capability === 'certified_execution')
             return 'certified_answer';
@@ -1395,7 +1911,7 @@ export function selectRoute(request, decision) {
         if (plan.capability === 'governed_relational')
             return 'generated_answer';
         if (plan.capability === 'bounded_exploration')
-            return 'research';
+            return 'generated_answer';
         return 'blocked';
     }
     // Retrieval + meaning resolution already established a compatible execution
@@ -1412,8 +1928,9 @@ export function selectRoute(request, decision) {
 }
 function defaultExecutorResult(route, request, decision) {
     const fallback = defaultOutcome(route);
+    const terminalMessage = route === 'blocked' ? decision?.terminalOutcome?.message : undefined;
     return {
-        summary: fallback.summary,
+        summary: terminalMessage ?? fallback.summary,
         answer: route === "clarify" ? decision?.clarifyingQuestion : undefined,
         evaluations: defaultEvaluations(route, request, decision),
         artifacts: defaultArtifacts(route, {}, request),
@@ -1594,6 +2111,8 @@ function defaultArtifacts(route, result, request) {
     }
 }
 function stopReasonFor(route, status, trustState, artifacts) {
+    if (status === "cancelled")
+        return "cancelled";
     if (status === "blocked" || trustState === "blocked")
         return "blocked";
     if (route === "conversation")
@@ -1611,7 +2130,7 @@ function stopReasonFor(route, status, trustState, artifacts) {
     return "generated_review_required";
 }
 function defaultNextActions(route, status) {
-    if (status === "blocked")
+    if (status === "blocked" || status === "cancelled")
         return [];
     if (route === "certified_answer") {
         return [