@duckcodeailabs/dql-agent 1.13.5 → 1.14.1

package/dist/agent-run-engine.js

@@ -2,11 +2,13 @@ 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, looksLikeComposeApp, } from "./intent-controller.js";
+import { classifyConversationalTurn, looksLikeDefinitionalAboutNamedObject, 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";
+import { buildCoverageGap } from './analytical-orchestration.js';
+import { evaluateAnalyticalRequestPolicy } from './analytical-request-policy.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"]);
 /**
@@ -37,6 +39,17 @@ 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')
@@ -53,30 +66,60 @@ export function agentRouteDeadlineMs(route) {
         return 120_000;
     return undefined;
 }
+/** Default request-ingress deadlines. */
+const DEFAULT_ASK_DEADLINE_MS = 45_000;
+const DEFAULT_RESEARCH_DEADLINE_MS = 120_000;
+/** Ceiling on any override, so a typo cannot hang a run indefinitely. */
+const MAX_DEADLINE_MS = 600_000;
+/**
+ * A deadline multiplier for slow providers.
+ *
+ * The 45s Ask budget assumes a hosted model. A local Ollama model needs ~7s for
+ * a one-word reply, so the meaning call alone can exhaust the whole window and
+ * every question comes back "The discovery window ended before an exact plan was
+ * frozen" — which makes a local model unusable at the default, and DQL is
+ * local-first by design.
+ *
+ * Deliberately a MULTIPLIER rather than an absolute: the relationship between
+ * the Ask and Research budgets, and between each and its soft targets, is
+ * load-bearing, so scaling keeps them proportional instead of letting one
+ * setting invert them.
+ */
+export function deadlineScale(env = process.env) {
+    const raw = Number(env.DQL_AGENT_DEADLINE_SCALE);
+    if (!Number.isFinite(raw) || raw <= 0)
+        return 1;
+    // Bounded: below 1 would tighten a safety deadline someone is relying on.
+    return Math.min(Math.max(raw, 1), 20);
+}
 /** 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;
+    const base = requestedMode === 'research' ? DEFAULT_RESEARCH_DEADLINE_MS : DEFAULT_ASK_DEADLINE_MS;
+    return Math.min(base * deadlineScale(), MAX_DEADLINE_MS);
 }
 /** 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 scale = deadlineScale();
+    const hardDeadlineMs = Math.min((mode === 'research' ? DEFAULT_RESEARCH_DEADLINE_MS : DEFAULT_ASK_DEADLINE_MS) * scale, MAX_DEADLINE_MS);
     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;
+        const base = mode === 'research' ? 90_000 : (agentRouteDeadlineMs(route) ?? 15_000);
+        // Scaled with the hard deadline: a soft target that stayed fixed while the
+        // ceiling moved would stop new work long before the run was actually out of
+        // time, which is the same dead end by a different route.
+        return Math.min(base * scale, hardDeadlineMs);
     };
     // 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);
+    const narrationSoftTargetMs = () => Math.min((mode === 'research' ? 100_000 : 38_000) * scale, hardDeadlineMs);
     return Object.freeze({
         startedAtMs,
         hardDeadlineMs,
@@ -602,6 +645,119 @@ export class AgentRunEngine {
                 ...(clarificationContinuation ? { clarificationResolved: true } : {}),
             },
         });
+        // This check is intentionally before route selection.  A restricted direct
+        // disclosure must not be embedded, retrieved, sent to a provider, value
+        // probed, or compiled merely to explain why it cannot be answered.
+        const ingressPolicy = evaluateAnalyticalRequestPolicy(submittedQuestion);
+        if (!ingressPolicy.allowed) {
+            const routeDecision = {
+                action: 'answer',
+                confidence: 1,
+                reason: 'The request is unavailable under the Ask data-safety policy.',
+                followsUp: false,
+                source: 'heuristic',
+                terminalOutcome: {
+                    kind: 'policy_blocked',
+                    code: 'ANALYTICAL_POLICY_BLOCKED',
+                    message: ingressPolicy.message,
+                    candidateIds: [],
+                },
+            };
+            const coverageGap = buildCoverageGap({
+                code: 'POLICY_BLOCKED',
+                phase: 'retrieval',
+                message: ingressPolicy.message,
+                searchedSources: [],
+                attemptedRoutes: [],
+                missing: [],
+                recoverable: false,
+                planFrozen: false,
+                nextActions: ingressPolicy.nextActions,
+            });
+            const evaluation = {
+                id: 'request-policy',
+                label: 'Ask request policy',
+                passed: false,
+                severity: 'blocking',
+                message: ingressPolicy.message,
+            };
+            const artifact = {
+                id: `${runId}:policy`,
+                kind: 'answer',
+                title: 'Ask request unavailable',
+                trustState: 'blocked',
+                payload: {
+                    analyticalCoverageGap: coverageGap,
+                    analyticalFailure: {
+                        code: 'POLICY_BLOCKED',
+                        phase: 'request_policy',
+                        message: ingressPolicy.message,
+                        recoverable: false,
+                        safeActions: ingressPolicy.nextActions,
+                    },
+                },
+            };
+            emit({
+                type: 'route.decided',
+                message: routeDecision.reason,
+                route: 'blocked',
+                payload: routeDecision,
+            });
+            emit({
+                type: 'evaluation.recorded',
+                message: evaluation.message,
+                route: 'blocked',
+                payload: evaluation,
+            });
+            emit({
+                type: 'artifact.created',
+                message: 'Created answer artifact.',
+                route: 'blocked',
+                trustState: 'blocked',
+                payload: artifact,
+            });
+            emit({
+                type: 'run.failed',
+                message: ingressPolicy.message,
+                route: 'blocked',
+                status: 'blocked',
+                trustState: 'blocked',
+            });
+            const completedAt = this.timestamp();
+            const run = {
+                id: runId,
+                question: submittedQuestion,
+                requestedMode,
+                route: 'blocked',
+                status: 'blocked',
+                trustState: 'blocked',
+                stopReason: 'blocked',
+                startedAt,
+                completedAt,
+                selectedObject: request.selectedObject,
+                executionTarget: request.executionTarget,
+                routeDecision,
+                steps: [],
+                summary: ingressPolicy.message,
+                answer: ingressPolicy.message,
+                answerKind: 'governed',
+                artifacts: [artifact],
+                evaluations: [evaluation],
+                events,
+                nextActions: ingressPolicy.nextActions.map((id) => ({ id, label: id === 'ask_for_an_approved_aggregate' ? 'Ask for an approved aggregate' : 'Inspect data policy' })),
+                repairAttempts: 0,
+                escalationAttempts: 0,
+                budgetUsage: cascadeBudgetTrace(createCascadeBudgetState(this.budgetModel)),
+                telemetry: emptyRunTelemetry(durationBetweenMs(startedAt, completedAt), 'policy_blocked'),
+                lifecycle: terminalLifecycle(progress.lifecycle, 'run.failed', completedAt, events.length),
+            };
+            run.diagnosticReceipt = diagnosticReceiptForRun(run);
+            run.diagnosticReceiptV2 = diagnosticReceiptV2ForRun(run);
+            run.artifacts = attachDiagnosticReceipt(run.artifacts, run.diagnosticReceipt, run.diagnosticReceiptV2);
+            await checkpointQueue;
+            await this.store?.save(run);
+            return run;
+        }
         const audience = resolveAudience(request);
         // Initialize a deterministic decision so router/provider timeouts can still
         // be persisted as a complete blocked run with an inspectable trace. The old
@@ -711,11 +867,17 @@ export class AgentRunEngine {
                         attempt,
                         stepGoal: planned.goal,
                         priorEvaluations,
+                        priorArtifacts: progress.artifacts,
                         repairHint,
                         emit,
                         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({
@@ -742,23 +904,6 @@ export class AgentRunEngine {
                         stepStatus = 'needs_review';
                         break;
                     }
-                    // Ordinary generated Ask freezes one analytical attempt. A failed
-                    // attempt is terminal review/manual-action work; it cannot hand
-                    // authority back to an injected LLM replanner for another physical
-                    // provider send. Explicit Research and authoring modes retain their
-                    // separately budgeted planner behavior.
-                    const ordinaryGeneratedAsk = route === 'generated_answer'
-                        && (requestedMode === 'ask' || requestedMode === 'auto');
-                    if (ordinaryGeneratedAsk) {
-                        stepStatus = 'needs_review';
-                        emit({
-                            type: 'replan.decided',
-                            message: 'Ordinary Ask kept the frozen analytical attempt and stopped for review without replanning.',
-                            route,
-                            payload: { decision: 'accept', authority: 'deterministic_fail_closed' },
-                        });
-                        break;
-                    }
                     const currentStep = {
                         id: stepId,
                         index: stepCount,
@@ -967,6 +1112,89 @@ export class AgentRunEngine {
         }
         catch (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"
@@ -1138,8 +1366,13 @@ export class AgentRunEngine {
             ...(finalResult.telemetry ? {
                 telemetry: withTotalDuration(finalResult.telemetry, durationBetweenMs(input.startedAt, completedAt)),
             } : {}),
+            ...(finalResult.narrationIntegrityReceipt ? {
+                narrationIntegrityReceipt: finalResult.narrationIntegrityReceipt,
+            } : {}),
             escalationAttempts,
             budgetUsage: input.budgetUsage,
+            ...(finalResult.analyticalTurnPlan ? { analyticalTurnPlan: finalResult.analyticalTurnPlan } : {}),
+            ...(finalResult.analyticalTaskOutcomes ? { analyticalTaskOutcomes: finalResult.analyticalTaskOutcomes } : {}),
             ...authoringDerivationFromRequest(input.request),
         };
     }
@@ -1162,7 +1395,7 @@ export class AgentRunEngine {
                 && !frozenPlan
                 && context.request.runBudget
                 && !context.request.runBudget.mayStartDiscovery(context.route)) {
-                return softBoundaryResult(context.route, context.request.runBudget);
+                return softBoundaryResult(context.route, context.request.runBudget, context.priorArtifacts);
             }
             const signal = context.request.runBudget?.hardSignal ?? context.request.signal;
             if (signal?.aborted)
@@ -1194,6 +1427,112 @@ export class AgentRunEngine {
  * inject or deserialize an older router decision as well as the canonical
  * router producer.
  */
+/** An ordinary Ask turn (not Research, App Build, or another explicit mode). */
+function isOrdinaryAskRequest(request) {
+    return request.requestedMode === undefined
+        || request.requestedMode === 'auto'
+        || request.requestedMode === 'ask';
+}
+/**
+ * A modeling/coverage gap is a pre-freeze DISCOVERY result, not permission to
+ * terminate an ordinary Ask. Keep the diagnostic as a typed reason, clear the
+ * blocked RAP, and let the answer executor continue through the governed
+ * relational and review-required generated lanes (AGT-028, EXP-001).
+ *
+ * `requireGovernedEvidence` separates the two callers, and it is what keeps the
+ * analytical-RAP safety boundary intact:
+ *
+ *   - A gap the ROUTER reported is already proof that discovery ran and found a
+ *     modelling limit, so it is rescued unconditionally (the original AGT-028
+ *     behaviour).
+ *   - A block this module SYNTHESIZES only means "nothing froze here". That is
+ *     also what an absent, LLM-authored, or forged router decision looks like,
+ *     so it is rescued only when retrieval actually surfaced governed
+ *     candidates. With no evidence at all it must still fail closed — a forged
+ *     `converse`/`answer` must never bypass the boundary on an analytical
+ *     question.
+ *
+ * Returns `undefined` when the decision is not a rescuable modeling gap, so
+ * callers can fall through to their own handling.
+ */
+function rescueModelingGapForOrdinaryAsk(request, decision, options = {}) {
+    if (!isOrdinaryAskRequest(request))
+        return undefined;
+    if (decision.terminalOutcome?.kind !== 'modeling_gap')
+        return undefined;
+    // A missing modeled dimension is a factual coverage result, not an invitation
+    // to retry the same question through generated SQL or Research.  The router
+    // already searched the governed sources and attached the exact field; keep it
+    // terminal so the UI can render the typed modeling action.
+    if (decision.meaningResolution?.compatibilityFailures?.some((failure) => failure.code === 'MISSING_DIMENSION'))
+        return undefined;
+    // Genuine user-facing ambiguity and an explicit evidence pick stay terminal.
+    if (decision.requiresClarification === true)
+        return undefined;
+    if (request.selectedEvidenceId)
+        return undefined;
+    if (options.requireGovernedEvidence) {
+        const governedEvidence = (decision.retrievalEvidence?.candidateCount ?? 0) > 0
+            || (decision.meaningResolution?.selectedConceptIds.length ?? 0) > 0;
+        if (!governedEvidence)
+            return undefined;
+    }
+    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,
+        // The premise of this rescue is that NO governed plan froze, so the turn
+        // must not take `selectRoute`'s certified/semantic shortcut — that path
+        // stamps `certified`/`governed` trust off a bare RECOMMENDATION, which is a
+        // suggestion, not a bound execution contract. Keep the meaning evidence for
+        // citations and downgrade the route to governed SQL, which is review-required.
+        ...(decision.meaningResolution
+            ? {
+                meaningResolution: {
+                    ...decision.meaningResolution,
+                    recommendedRoute: 'governed_sql',
+                },
+            }
+            : {}),
+    };
+}
+/**
+ * Has this exact clarification already been asked in this thread?
+ *
+ * The reported loop: "who are the top customers for BCM" returned "Top by which
+ * governed metric?", the user answered in prose, and the IDENTICAL question came
+ * back. Their reply reads as a complete new question — which is a defensible
+ * classification — so it re-entered the cascade fresh, retrieved the same
+ * evidence, and produced the same clarification. Nothing in the loop noticed it
+ * had already been there.
+ *
+ * Asking twice is proof the question does not work: the user has already seen it
+ * and responded, and a third identical prompt cannot produce a different reply.
+ * Whatever the best available interpretation is, committing to it and saying so
+ * beats asking again.
+ */
+function clarificationAlreadyAsked(clarifyingQuestion, history) {
+    const asking = clarifyingQuestion?.replace(/\s+/g, ' ').trim().toLowerCase();
+    if (!asking || !history?.length)
+        return false;
+    let sawAssistantAsk = false;
+    for (const turn of history) {
+        if (turn.role !== 'assistant')
+            continue;
+        if (turn.text.replace(/\s+/g, ' ').trim().toLowerCase().includes(asking))
+            sawAssistantAsk = true;
+    }
+    if (!sawAssistantAsk)
+        return false;
+    // Only a loop once the user has actually replied to it. A clarification still
+    // waiting for its first answer is not a repeat.
+    const lastAsk = [...history].reverse().findIndex((turn) => turn.role === 'assistant' && turn.text.replace(/\s+/g, ' ').trim().toLowerCase().includes(asking));
+    return lastAsk > 0;
+}
 function enforceOrdinaryAnalyticalPlanBoundary(request, decision) {
     const ordinaryAsk = request.requestedMode === undefined
         || request.requestedMode === 'auto'
@@ -1202,6 +1541,52 @@ function enforceOrdinaryAnalyticalPlanBoundary(request, decision) {
         || decision.action === 'block'
         || decision.requiresClarification === true
         || Boolean(decision.terminalOutcome);
+    const inboundRescue = rescueModelingGapForOrdinaryAsk(request, decision);
+    if (inboundRescue)
+        return inboundRescue;
+    // A clarification the user has already seen and answered cannot be asked
+    // again. Checked before the `terminal` guard for the same reason as the
+    // definitional case: the gate has already set `action: 'clarify'` by here.
+    if (ordinaryAsk
+        && decision.action === 'clarify'
+        && clarificationAlreadyAsked(decision.clarifyingQuestion, request.history?.length ? request.history : conversationHistoryFromContext(request.conversationContext))) {
+        return {
+            ...decision,
+            action: 'answer',
+            confidence: Math.min(decision.confidence, 0.6),
+            reason: `This clarification was already asked and answered in this thread, so DQL proceeded with the best supported interpretation instead of repeating it: ${decision.clarifyingQuestion ?? ''}`.trim(),
+            requiresClarification: false,
+            clarifyingQuestion: undefined,
+            terminalOutcome: undefined,
+            resolvedAnalyticalPlan: undefined,
+        };
+    }
+    // A DEFINITIONAL question about an artifact it names is not an analytical
+    // request, and must be caught before the `terminal` guard below — the
+    // ambiguity gate has already set `action: 'clarify'` by this point, so any
+    // check placed after it is unreachable.
+    //
+    // Without this, "what is food_vs_drink_revenue?" is answered with "Which
+    // governed meaning should DQL bind: food_vs_drink_revenue or …?" — asking the
+    // user to disambiguate the one artifact they just named. The plan cannot see
+    // it because it reads the artifact's OWN NAME as analytical intent: that name
+    // contains "vs", so the mode comes back `comparison`.
+    if (ordinaryAsk
+        && !request.selectedEvidenceId
+        && looksLikeDefinitionalAboutNamedObject(request.question, decision.retrievalEvidence?.candidateIds ?? [])) {
+        return {
+            ...decision,
+            action: 'converse',
+            category: 'conversational',
+            confidence: 1,
+            reason: 'This asks what a governed artifact means, so it is answered from its definition rather than by running a query.',
+            requiresClarification: false,
+            clarifyingQuestion: undefined,
+            clarificationOptions: undefined,
+            terminalOutcome: undefined,
+            resolvedAnalyticalPlan: undefined,
+        };
+    }
     const exactSemanticContinuation = Boolean(request.selectedEvidenceId
         && decision.meaningResolution?.recommendedRoute === 'semantic'
         && decision.meaningResolution.recommendedExecutionId === request.selectedEvidenceId);
@@ -1264,7 +1649,7 @@ function enforceOrdinaryAnalyticalPlanBoundary(request, decision) {
     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 {
+    const blocked = {
         ...decision,
         action: 'block',
         confidence: 1,
@@ -1277,9 +1662,40 @@ function enforceOrdinaryAnalyticalPlanBoundary(request, decision) {
             candidateIds: decision.retrievalEvidence?.candidateIds ?? [],
         },
     };
+    // The block synthesized HERE is a modeling gap too, so it must face the same
+    // rescue as one arriving from the router. Without this, the rescue above
+    // silently did not apply to the most common way an ordinary Ask gets blocked:
+    // retrieval found governed candidates, no exact tuple froze, and the run
+    // dead-ended instead of continuing to the generated lane.
+    return rescueModelingGapForOrdinaryAsk(request, blocked, { requireGovernedEvidence: true }) ?? blocked;
 }
-function softBoundaryResult(route, budget) {
+function softBoundaryResult(route, budget, priorArtifacts = []) {
     const seconds = Math.round(budget.softTargetMs(route) / 1_000);
+    // Admission control must never turn work that already validated into a
+    // refusal. A run that established findings and then ran out of clock has
+    // something true to say; answering `blocked` discards it and asks the user
+    // to start the same investigation over. Partial and labelled beats nothing.
+    const established = priorArtifacts.filter((artifact) => artifact.trustState !== "blocked" && artifact.trustState !== "not_applicable");
+    if (established.length > 0) {
+        const titles = established.map((artifact) => artifact.title).filter((title) => Boolean(title));
+        const named = titles.length === 1
+            ? titles[0]
+            : `${titles.slice(0, -1).join(", ")} and ${titles[titles.length - 1]}`;
+        const plural = established.length === 1;
+        return {
+            resolvedRoute: route,
+            status: "needs_review",
+            trustState: "review_required",
+            stopReason: "human_review_required",
+            summary: `The ${seconds}-second discovery target elapsed. Returning what was established rather than discarding it.`,
+            answer: titles.length > 0
+                ? `The discovery window ended before the whole question was covered, so this is partial: ${named}. ${plural ? "It was" : "They were"} validated before the clock ran out; nothing beyond ${plural ? "it" : "them"} was investigated. Continue to pick up from here.`
+                : `The discovery window ended before the whole question was covered. ${established.length} validated finding${plural ? "" : "s"} from this run ${plural ? "is" : "are"} attached; nothing beyond ${plural ? "it" : "them"} was investigated.`,
+            artifacts: [...established],
+            evaluations: [],
+            nextActions: [{ id: "continue-after-soft-target", label: "Continue the investigation" }],
+        };
+    }
     return {
         resolvedRoute: 'clarify',
         status: 'needs_clarification',
@@ -1410,13 +1826,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 {
@@ -1454,7 +1870,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 }
@@ -1465,14 +1881,14 @@ function diagnosticReceiptForRun(run) {
         evaluations: run.evaluations,
         ...(run.repairCapability ? { repairCapability: run.repairCapability } : {}),
         ...(run.providerEgressReceipts?.length ? { providerEgressReceipts: run.providerEgressReceipts } : {}),
-        ...(run.status === "blocked"
+        ...(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),
                 },
             }
             : {}),
@@ -2007,6 +2423,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")
@@ -2024,7 +2442,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 [