cascade-ai 0.75.0 → 0.76.0

package/dist/index.d.ts

@@ -136,6 +136,29 @@ declare class ResumeStore {
  */
 declare function summarizeCompleted(completed: readonly CompletedNode[], perNodeChars?: number): string;
 
+/** One thing the reviewer says is missing. */
+interface ReviewGap {
+    /** A single sentence naming the gap. */
+    title: string;
+    /** Optional elaboration, when the reviewer gave one. */
+    detail?: string;
+    /** Section titles this gap was found in, when the reviewer attributed it. */
+    sections?: string[];
+}
+/** What a review pass concluded. */
+interface ReviewVerdict {
+    approved: boolean;
+    /** One line, safe to put in a status field. Absent when approved. */
+    summary?: string;
+    gaps: ReviewGap[];
+    /**
+     * The verdict as prose, for the correction prompt — which needs the full
+     * detail, not the summary. Assembled from the parts rather than kept
+     * separately so the two cannot disagree.
+     */
+    reason?: string;
+}
+
 type ProviderType = 'anthropic' | 'openai' | 'gemini' | 'azure' | 'openai-compatible' | 'ollama';
 interface ModelInfo {
     id: string;
@@ -240,6 +263,13 @@ interface TokenUsage {
      */
     costUnknown?: boolean;
 }
+/**
+ * The kind of work a prompt represents, as the heuristic analyser classifies
+ * it. Declared here rather than in the router because routing evidence, per-call
+ * options and the performance tracker all key on it; `task-analyzer.ts`
+ * re-exports it so existing imports keep working.
+ */
+type TaskType = 'code' | 'analysis' | 'creative' | 'data' | 'mixed';
 interface GenerateOptions {
     messages: ConversationMessage[];
     systemPrompt?: string;
@@ -259,6 +289,13 @@ interface GenerateOptions {
     model?: ModelInfo;
     /** Name/tag of the current sub-feature (e.g. T2 section title) for cost accounting. */
     featureTag?: string;
+    /**
+     * The task type the per-call `model` was selected under, when Cascade Auto
+     * chose it. Carried so routing evidence lands on the exact selection that
+     * ran: a tier can select the same model for two kinds of work in one run,
+     * and only the one that reaches a provider should be credited.
+     */
+    selectionTaskType?: TaskType;
     /**
      * Privacy-tier constraint: when set, the call must resolve to a LOCAL model
      * (never a cloud provider). The router errors if no local model is available
@@ -271,6 +308,21 @@ interface GenerateResult {
     usage: TokenUsage;
     toolCalls?: ToolCall[];
     finishReason: 'stop' | 'length' | 'tool_use';
+    /**
+     * The model that actually produced this result.
+     *
+     * Not always the one that was asked for: the router fails over mid-call on a
+     * rate limit, a dead model id, or an exhausted account, and the caller has
+     * no other way to find out. Callers that REPORT a model — `tier:status`,
+     * which the hosted server persists onto the assistant message and which
+     * `/why` and thumbs feedback then read — must use this rather than the model
+     * they passed in, or the credit goes to a model that never ran and the
+     * performance history learns something untrue about both.
+     */
+    servedBy?: {
+        provider: ProviderType;
+        id: string;
+    };
 }
 interface ConversationMessage {
     role: 'user' | 'assistant' | 'system' | 'tool';
@@ -327,6 +379,21 @@ interface ToolCall {
     id: string;
     name: string;
     input: Record<string, unknown>;
+    /**
+     * An opaque token the provider attached to this call, to be echoed back
+     * verbatim when the call is replayed as history.
+     *
+     * Normalized types usually strip provider specifics, and this one cannot be:
+     * Gemini's thinking models sign each `functionCall` part, and a follow-up
+     * turn that replays the call without its signature is rejected outright —
+     * `400 Bad Request`, "missing thought signature". Dropping it therefore does
+     * not degrade a reply, it prevents one, and only on the multi-turn tool-use
+     * path where every worker lives.
+     *
+     * Opaque on purpose: nothing here may interpret it, and a provider that
+     * issues no such token simply leaves it unset.
+     */
+    signature?: string;
 }
 interface ToolResult {
     toolCallId: string;
@@ -464,6 +531,12 @@ interface StatusUpdate {
     currentAction: string;
     status: 'IN_PROGRESS' | 'BLOCKED' | 'ESCALATING';
     output?: string;
+    /**
+     * A review verdict, when this update is one. Carried as data rather than
+     * folded into `currentAction`, which is a one-line field every surface
+     * truncates — see core/tiers/review.ts.
+     */
+    review?: ReviewVerdict | null;
 }
 interface T2Result {
     sectionId: string;
@@ -1133,6 +1206,19 @@ declare class ModelSelector {
      * A model is usable for AUTO selection when its provider is available AND —
      * if that provider was validated — the id is one the provider confirmed.
      */
+    /**
+     * Per-MODEL exclusion, for verdicts finer-grained than a provider.
+     *
+     * `availableProviders` can only say "all of Azure is out", which is wrong
+     * when each Azure deployment carries its own resource and key. The router
+     * sets this to the failover manager's permanent-verdict check, so a
+     * deployment that ran out of credit stops being selected while its healthy
+     * siblings stay eligible. Routed through isUsable() so every selection path
+     * — selectForTier, getNextFallback, the widening fallbacks — honours it,
+     * rather than each having to remember.
+     */
+    private modelVeto?;
+    setModelVeto(veto: (model: ModelInfo) => boolean): void;
     private isUsable;
     /**
      * Permanently drop a model from the available set for this session. Used by
@@ -1165,11 +1251,30 @@ declare class ModelSelector {
     private resolveDynamicModel;
 }
 
+/** Beta(α, β). α counts success-weight, β failure-weight, both incl. the prior. */
+interface BetaPosterior {
+    alpha: number;
+    beta: number;
+}
+/** Uniform source in [0,1). Injected so every test here is deterministic. */
+type Rng = () => number;
+
 interface ModelStat {
+    /**
+     * Success and failure EVIDENCE, weighted — not observation counts.
+     *
+     * An explicit thumbs-up is worth more than "the HTTP call did not error",
+     * and that difference is expressed here, in the evidence, where a Beta
+     * posterior can read it. It used to be expressed by recording the same
+     * observation three times, which also tripled `sampleCount` — so the one
+     * number everything else treats as "how much do we know about this model"
+     * was inflated by a factor of three every time somebody clicked a thumb.
+     */
     successCount: number;
     failureCount: number;
     totalRetries: number;
     totalCostUsd: number;
+    /** How many times this model was actually OBSERVED. Confidence, not score. */
     sampleCount: number;
     /** Sum of input/context tokens across samples — so we can see whether a
      *  model tends to fail on larger contexts and route less to it accordingly. */
@@ -1197,19 +1302,97 @@ declare class ModelPerformanceTracker {
     });
     load(): Promise<void>;
     save(): Promise<void>;
-    record(modelId: string, taskType: TaskType, outcome: 'success' | 'failure', retries?: number, costUsd?: number, contextTokens?: number): void;
+    record(modelId: string, taskType: TaskType, outcome: 'success' | 'failure', retries?: number, costUsd?: number, contextTokens?: number, 
+    /**
+     * How much this observation counts as EVIDENCE. One for an automatic
+     * outcome; more for a signal we trust further. It never touches
+     * sampleCount: one thing happened, however much it tells us.
+     */
+    weight?: number): void;
     recordFeatureCost(featureTag: string, costUsd: number): void;
     /**
-     * Record an explicit user rating (good/bad). Counts as 3 automatic samples
-     * so user feedback carries significantly more weight than auto-detected outcomes.
+     * Weight an explicit rating carries relative to an automatic outcome.
+     *
+     * An automatic outcome says only that the call completed; a person saying
+     * "this was good" is about the thing routing actually cares about. Three is
+     * the ratio this has always used — kept, now that it is expressed honestly.
+     */
+    static readonly EXPLICIT_RATING_WEIGHT = 3;
+    /**
+     * Record an explicit user rating (good/bad), worth EXPLICIT_RATING_WEIGHT
+     * automatic outcomes.
+     *
+     * ONE observation carrying that weight, not three observations. Recording it
+     * three times also tripled `sampleCount` — the count of how many times this
+     * model was actually run, which the exploration note reports and the
+     * lifecycle states will read. One click claimed three runs' worth of
+     * history that never happened.
+     *
+     * The weight is spent on belief, relative to the evidence it competes with;
+     * it does not buy confidence. A lone thumbs-up moves the score exactly as
+     * far as a lone successful run (0.5 → 0.6) — what it buys is winning the
+     * argument against automatic outcomes that disagree with it.
      */
     recordExplicit(modelId: string, taskType: TaskType, rating: 'good' | 'bad', costUsd?: number): void;
     /** Returns all stats keyed by "modelId:taskType" — used by `cascade stats`. */
     getAll(): Map<string, ModelStat>;
     getAllFeatures(): Map<string, FeatureStat>;
     /**
-     * Returns 0.05–1.0; defaults to 0.5 (neutral prior) when no history exists.
-     * High retry counts penalise the score.
+     * Whether outcomes recorded here go anywhere.
+     *
+     * A read-only tracker (routing.learnFromOutcomes = false) reads the shared
+     * scores but drops every observation — not just the write to disk, the
+     * in-memory update too. Anything whose correctness depends on evidence
+     * accumulating has to know that: see TaskAnalyzer.perfFor, where sampling a
+     * posterior that can never narrow means exploring forever.
+     */
+    learnsFromOutcomes(): boolean;
+    /**
+     * The Beta posterior over this model's success rate for this task type.
+     *
+     * Exposed as the posterior rather than a number so callers can ask the two
+     * different questions it answers: what we believe (the mean, for ranking)
+     * and how little we know (the spread, for deciding whether to explore).
+     * Collapsing it to a scalar here is what made those inseparable.
+     */
+    posteriorFor(modelId: string, taskType: TaskType): BetaPosterior;
+    /**
+     * The observed success rate, 0–1 — what actually happened, unshrunk.
+     *
+     * For display (`cascade stats`), not for routing: routing wants
+     * `performanceScore`, which is shrunk toward 0.5 by how little is known.
+     *
+     * Lives here rather than at the call site because the denominator is not
+     * obvious and getting it wrong is silent. It is the EVIDENCE total, not
+     * `sampleCount`: an explicit rating contributes 3 units of evidence on 1
+     * observation, so dividing by the observation count renders a single
+     * thumbs-up as "300%" — and anything sorting on that column then ranks the
+     * impossible rates first.
+     */
+    observedSuccessRate(modelId: string, taskType: TaskType): number;
+    /** How many times this model was observed on this task type. */
+    sampleCountFor(modelId: string, taskType: TaskType): number;
+    /**
+     * The retry cost as a multiplier in (0.6, 1] — 1.0 when a model never
+     * retries, 0.6 when it retries three times or more on average.
+     *
+     * Exposed separately because it is genuinely a separate quantity from the
+     * success rate, and because the alternative — recovering it by dividing
+     * `performanceScore` by `posteriorMean` — silently stops being the retry
+     * penalty at all once the score floor engages. See perfFor().
+     */
+    retryFactorFor(modelId: string, taskType: TaskType): number;
+    /**
+     * Believed success rate, 0–1, shrunk toward 0.5 by how little is known.
+     *
+     * Replaces a raw successCount/sampleCount. That rate read one failure as 0%
+     * — floored to 0.05, a 10x penalty against a benchmark range spanning about
+     * 1.5x — so a single bad moment outweighed every measured quality difference
+     * in the catalogue, and with nothing exploring, the model was never tried
+     * again to find out otherwise. See bayes.ts for the numbers.
+     *
+     * The retry penalty survives unchanged: retries are a real cost that a
+     * success/failure verdict does not capture.
      */
     performanceScore(modelId: string, taskType: TaskType): number;
     /**
@@ -1236,9 +1419,28 @@ interface FeedbackCounts {
  */
 type FeedbackSource = (modelId: string) => FeedbackCounts | undefined;
 
-type TaskType = 'code' | 'analysis' | 'creative' | 'data' | 'mixed';
 /** Cascade Auto cost/quality trade-off bias. See CascadeConfig.autoBias. */
 type AutoBias = 'balanced' | 'quality' | 'cost';
+/** Options shared by both selection entry points. */
+interface SelectOptions {
+    requiresToolUse?: boolean;
+}
+/** A routing choice, plus why it might not be the obvious one. */
+interface Selection {
+    model: ModelInfo | null;
+    /**
+     * The task type this choice was made under — the other half of the
+     * selection's identity, since one tier can select the same model for two
+     * different kinds of work in one run and only one of them may run.
+     */
+    taskType: TaskType;
+    /**
+     * Set only when the draw beat the belief — i.e. this is an experiment, not
+     * the evidence's own answer. Null on an ordinary pick, so a caller can print
+     * it unconditionally.
+     */
+    note: string | null;
+}
 interface TaskProfile {
     type: TaskType;
     /** 1 = trivial, 5 = research-grade */
@@ -1255,7 +1457,19 @@ declare class TaskAnalyzer {
     private feedback?;
     private bias;
     private lastProfile;
-    /** Models chosen by the run currently in flight. Cleared when it completes. */
+    /**
+     * Models used per tier this run — a LIST, each carrying its own task type.
+     *
+     * A tier can legitimately run several models now that selection samples: two
+     * T3 subtasks in one run may draw differently. Every one of them has to
+     * receive the run's outcome, or the explored model records nothing and
+     * exploration cannot learn from its own experiment.
+     *
+     * And each carries the task type IT was chosen for, because subtasks within
+     * one run are not all the same type. Crediting them all to the last
+     * selection's profile teaches the router that whichever model happened to
+     * write the closing paragraph is good at code.
+     */
     private currentRunSelections;
     /**
      * Immutable snapshot of the last COMPLETED run: its selections AND the task
@@ -1273,7 +1487,14 @@ declare class TaskAnalyzer {
      * false: the 3x-weighted user signal never reached the tracker at all.
      */
     private lastCompletedRun?;
+    /**
+     * Uniform source for Thompson draws. Injectable so a test can pin the
+     * exploration decision instead of asserting on chance.
+     */
+    private rng;
     constructor(tracker?: ModelPerformanceTracker, bias?: AutoBias);
+    /** Replace the RNG behind exploration (tests). */
+    setRng(rng: Rng): void;
     /**
      * Supply per-model rating counts. Optional by design: a host that collects no
      * feedback (the CLI, a fresh install) scores exactly as it did before, since
@@ -1295,9 +1516,39 @@ declare class TaskAnalyzer {
      * Scores tier-eligible models using cost efficiency + historical performance.
      * Falls back to the priority-list default when no candidates have history.
      */
-    selectModel(prompt: string, tier: TierRole, selector: ModelSelector, opts?: {
-        requiresToolUse?: boolean;
-    }): Promise<ModelInfo | null>;
+    selectModel(prompt: string, tier: TierRole, selector: ModelSelector, opts?: SelectOptions): Promise<ModelInfo | null>;
+    /**
+     * Select a model AND say whether the choice was exploratory.
+     *
+     * The note is returned rather than left on the instance for the caller to
+     * collect afterwards. That looks like an over-careful API for one string,
+     * and it is not: `Cascade.run` selects every tier CONCURRENTLY
+     * (`Promise.all` over the tiers in play, cascade.ts), all against this one
+     * analyzer. A field would be written by three interleaved calls and read by
+     * three continuations in an order nothing establishes — /why would attribute
+     * one tier's exploration to another, and lose the rest. Clearing the field
+     * per call does not fix that; it only removes the staleness across
+     * SEQUENTIAL calls. Ownership is what is actually needed, and a return value
+     * is what ownership looks like.
+     */
+    select(prompt: string, tier: TierRole, selector: ModelSelector, opts?: SelectOptions): Promise<Selection>;
+    /**
+     * Mark a selected model as having actually been sent a request on this tier.
+     *
+     * Called at the provider-call boundary, which is the only place that knows a
+     * request was really made and which model made it. Everything upstream knows
+     * only what was CHOSEN.
+     *
+     * Called BEFORE the request is awaited, deliberately. Hanging it off the
+     * success path looks tidier and quietly discards every failure: a run that
+     * died recorded nothing about the model that killed it, so its posterior
+     * never moved and sampling kept picking it.
+     *
+     * A model that runs without having been selected here — an explicitly pinned
+     * tier, a failover replacement — has no entry and is ignored, which matches
+     * the existing contract that this analyzer rates only its own choices.
+     */
+    noteAttempted(tier: TierRole, modelId: string, taskType?: TaskType): void;
     /**
      * Record the outcome of a completed run across all tiers that were selected
      * during this session and persist stats to disk.
@@ -1317,7 +1568,23 @@ declare class TaskAnalyzer {
      * that reports false, which is what "rate this run" should mean.
      */
     recordExplicitRating(rating: 'good' | 'bad'): boolean;
+    /**
+     * @param perfMode `mean` scores on what we believe; `sample` draws from the
+     *        posterior. Everything else in the score is a deterministic lookup —
+     *        the benchmark, the price, the specialization match — so this is the
+     *        only term where exploration could live.
+     */
     private scoreModel;
+    /**
+     * The one stochastic term in the score.
+     *
+     * The retry penalty is applied to a DRAW the same way performanceScore()
+     * applies it to the mean, so exploring cannot smuggle a model past a cost it
+     * has actually been shown to carry.
+     */
+    private perfFor;
+    /** One line for /why, naming what was tried and how little is known about it. */
+    private describeExploration;
     private costEfficiency;
     private taskMatchScore;
     /** Clear the analysis cache (call between sessions). */
@@ -1882,6 +2149,18 @@ declare class CascadeRouter extends EventEmitter {
     private liveData?;
     /** Snapshot of configured/default tier models, taken before Cascade Auto overrides them. */
     private originalTierModels?;
+    /**
+     * Tiers repointed because their model's credential went out for the run, and
+     * the model each was displaced from.
+     *
+     * Clearing the verdict at the run boundary makes the provider SELECTABLE
+     * again, which is not the same as being used: generate() resolves
+     * `tierModels.get(tier)` before it ever consults the selector, so a tier
+     * still holding the fallback keeps charging the fallback account for every
+     * later default-routed run. Restoring the binding is what actually gives a
+     * topped-up account its traffic back.
+     */
+    private permanentRepoints;
     /** The current run's abort signal — injected into every provider call so a cancel aborts in-flight requests. */
     private runSignal?;
     /** Thrown when the configured budget is exceeded. */
@@ -1974,7 +2253,7 @@ declare class CascadeRouter extends EventEmitter {
      * Used by TaskAnalyzer to inject task-optimal models before execution.
      * The override is valid for the current task only — restored by restoreTierModels().
      */
-    overrideTierModel(tier: TierRole, model: ModelInfo): void;
+    overrideTierModel(tier: TierRole, model: ModelInfo, taskType?: TaskType): void;
     /**
      * Restore tier models to the configured/default baseline captured before the
      * first Cascade Auto override. Called at the end of each run so `/why`, the
@@ -2019,7 +2298,10 @@ declare class CascadeRouter extends EventEmitter {
      */
     selectModelForSubtask(tier: TierRole, text: string, opts?: {
         requiresToolUse?: boolean;
-    }): Promise<ModelInfo | null>;
+    }): Promise<{
+        model: ModelInfo;
+        taskType?: TaskType;
+    } | null>;
     getStats(): RouterStats;
     /**
      * What did delegation save? Compares actual spend against the
@@ -2094,6 +2376,74 @@ declare class CascadeRouter extends EventEmitter {
     private discoverOllamaModels;
     /** Returns true when at least one real model was discovered from the endpoint. */
     private discoverOpenAICompatibleModels;
+    /**
+     * The credential a failure on this model is actually about.
+     *
+     * Resolves an Azure deployment to its RESOURCE (endpoint), because that is
+     * what the key and the bill belong to — see failureScopeOf. Everything else
+     * is already one credential per provider.
+     */
+    /**
+     * Note the tier's binding before a permanent verdict repoints it.
+     *
+     * Records `tierModels.get(tier)` — the tier's own baseline — and NOT the
+     * model that happened to fail. Those differ whenever the call carried a
+     * per-call override (Cascade Auto picks one per subtask), and saving the
+     * override would have beginRun() install a one-off subtask model as the
+     * tier's baseline, leaving every later default-routed call on a model the
+     * tier was never configured to use.
+     *
+     * Nothing to restore if the tier had no binding, and the first repoint wins
+     * so a second failover in the same run cannot overwrite the true baseline.
+     */
+    private rememberRepoint;
+    /**
+     * Both scopes a failure on this model could belong to, widest first.
+     *
+     * Azure needs two, because the two systemic failures have different blast
+     * radii on the same deployment:
+     *
+     *   · billing quota belongs to the RESOURCE — deployments on one endpoint
+     *     draw on the same subscription, so a spent quota covers all of them
+     *     even when they carry different keys;
+     *   · a rejected credential belongs to the KEY — two deployments on one
+     *     endpoint can be configured with separate keys, and a 401 on a rotated
+     *     one says nothing about the other.
+     *
+     * Recording uses whichever matches the failure (scopeForFailure); anything
+     * asking "is this model out?" has to consult both, or a verdict filed under
+     * one would be invisible to the other.
+     */
+    private scopesFor;
+    /** True when ANY scope this model belongs to is out for the run. */
+    private isModelOut;
+    /** The first explanation among this model's scopes, for a refusal message. */
+    private outReason;
+    /**
+     * The scope a failure of this KIND should be filed under. A credential
+     * rejection is about the key; everything else about the resource.
+     */
+    private scopeForFailure;
+    /** `azure:<resource>` for an Azure model, or undefined for anything else. */
+    private azureScope;
+    /**
+     * `azure:<resource>#k<n>`, so two different keys on one resource differ.
+     *
+     * `n` is the position of the FIRST configured Azure entry using this same
+     * key, which makes it stable for the run and identical for every deployment
+     * sharing that credential — the grouping an auth verdict needs, since a 401
+     * on one of them is a fact about all of them.
+     *
+     * Deliberately neither of the two obvious alternatives. credentialIdentity()
+     * rotates to a fresh UUID after DISCOVERY_TTL_MS, so a long run would stop
+     * finding its own verdict and go back to a credential it had just been told
+     * was rejected. And hashing the key — even with a strong digest — is a
+     * password hash by CodeQL's reading and by any reasonable one: there is no
+     * reason to derive anything from a secret when its POSITION already
+     * identifies it uniquely and reveals nothing.
+     */
+    private azureKeyScope;
+    private scopeFor;
     private ensureProvider;
     private getProvider;
     private createProvider;
@@ -2111,6 +2461,25 @@ declare class CascadeRouter extends EventEmitter {
      * totals and a session-wide budget halt are deliberately preserved; only the
      * per-task ceiling is cleared so the next task starts with a fresh allowance.
      */
+    /**
+     * The task type each tier's Cascade Auto default was selected under.
+     *
+     * A call that does not carry its own `selectionTaskType` is using the tier
+     * default, and its evidence belongs to the selection that established that
+     * default rather than to any other selection of the same model.
+     */
+    private tierSelectionTaskTypes;
+    /**
+     * Exploration notes for selections that have not yet reached a provider,
+     * keyed by the selection's identity.
+     *
+     * Held rather than emitted so /why only ever claims an experiment that was
+     * actually run. Cleared by beginRun() along with everything else run-scoped;
+     * a note whose call never happens is simply dropped, which is the point.
+     */
+    private pendingExplorationNotes;
+    /** Announce an exploratory pick, once, at the moment its call goes out. */
+    private flushExplorationNote;
     beginRun(): void;
     /**
      * Refuse a call whose input alone cannot fit what is left of the run budget.
@@ -2343,6 +2712,11 @@ declare class ToolRegistry extends EventEmitter {
 }
 
 declare abstract class BaseTier extends EventEmitter {
+    /**
+     * Declared here so generateTracked() can reach it. Each tier owns its own
+     * instance; this only states that one exists.
+     */
+    protected abstract router: CascadeRouter;
     readonly id: string;
     readonly role: TierRole;
     protected status: TierStatus;
@@ -2419,6 +2793,32 @@ declare abstract class BaseTier extends EventEmitter {
      */
     getServingModel(): string | undefined;
     protected setServingModel(model: string | undefined): void;
+    /**
+     * Run a generation and record which model actually answered it.
+     *
+     * Tiers set servingModel from the model they SELECTED, before the call. The
+     * router can fail over mid-call — a rate limit, a dead id, an exhausted
+     * account — and then the tier's terminal status names a model that never
+     * ran. cloud/server persists that value onto the assistant message, and
+     * `/why` and thumbs feedback read it back, so the credit (or the blame) goes
+     * to the wrong model and the performance history learns something untrue
+     * about two models at once.
+     *
+     * Every tier call goes through here rather than `router.generate` directly,
+     * so a new call site cannot quietly reintroduce the mis-attribution.
+     */
+    /**
+     * Run a generation whose model must NOT become this tier's attribution.
+     *
+     * Graders, critics and extractors run beside the answer, often on a
+     * deliberately different model — the T2 critic exists precisely so a model
+     * is not marking its own work. Routing those through generateTracked() made
+     * the last grading call overwrite servingModel, so the subtask's output, its
+     * terminal status and the feedback history all named the grader rather than
+     * the model that wrote the answer.
+     */
+    protected generateAuxiliary(...args: Parameters<CascadeRouter['generate']>): Promise<Awaited<ReturnType<CascadeRouter['generate']>>>;
+    protected generateTracked(...args: Parameters<CascadeRouter['generate']>): Promise<Awaited<ReturnType<CascadeRouter['generate']>>>;
     protected setLabel(label: string): void;
     setSystemPromptOverride(prompt: string): void;
     setHierarchyContext(context: string): void;
@@ -2629,7 +3029,7 @@ interface PlanApprovalMeta {
     critique?: string;
 }
 declare class T1Administrator extends BaseTier {
-    private router;
+    protected router: CascadeRouter;
     private toolRegistry;
     private config;
     private t2Managers;
@@ -2766,7 +3166,7 @@ declare class CurrentPageTool extends BaseTool {
 /** One entry in the per-run orchestration decision trail (see /why). */
 interface DecisionLogEntry {
     at: string;
-    kind: 'complexity' | 'model' | 'failover' | 'escalation' | 'context';
+    kind: 'complexity' | 'model' | 'failover' | 'escalation' | 'context' | 'provider-exhausted';
     detail: string;
 }
 declare class Cascade extends EventEmitter {
@@ -3245,10 +3645,17 @@ declare class PeerBus extends EventEmitter {
 }
 
 declare class T2Manager extends BaseTier {
-    private router;
+    protected router: CascadeRouter;
     private toolRegistry;
     private assignment?;
     private sectionModel?;
+    /**
+     * The task type `sectionModel` was selected under. Carried into every call
+     * that uses it so routing evidence lands on this exact selection — one tier
+     * can select the same model for two kinds of work in a run, and only the one
+     * that reaches a provider should be credited.
+     */
+    private sectionTaskType?;
     private t3Workers;
     private escalations;
     private peerSyncBuffer;
@@ -3351,7 +3758,7 @@ declare class T2Manager extends BaseTier {
 }
 
 declare class T3Worker extends BaseTier {
-    private router;
+    protected router: CascadeRouter;
     private toolRegistry;
     private context;
     private assignment?;
@@ -3644,11 +4051,35 @@ interface AcceptanceProbe {
     /** utf-8 contents, or null when unreadable (missing, binary, too large). */
     read(path: string): Promise<string | null>;
 }
+interface AcceptanceOptions {
+    /**
+     * Whether the worker being graded had ANY tool that could put a file on
+     * disk. Defaults to true, which is every caller that does not say otherwise.
+     *
+     * When false, a file-shaped criterion is `undecidable` rather than `failed`.
+     * `stat` still answers correctly — the file really is absent — but the
+     * verdict is a judgement about the WORKER, and "you did not write the file"
+     * is the wrong judgement when nothing in the run could write one. A hosted
+     * chat run enables `web_search`/`web_fetch` only (cloud/server/src/runs.ts),
+     * while T1 and T2 are asked for acceptance criteria phrased as "file exists
+     * / contains X" — so the planner names a file, the worker answers in prose
+     * because prose is all it can produce, and this rung failed it for that.
+     * correctOutput then re-ran, the file was still absent, and the subtask
+     * ESCALATED carrying a perfectly good answer.
+     *
+     * This is the same guard `shouldRequireArtifact()` applies one rung up (see
+     * t3-worker.ts); the artifact rung got it in #151 and this rung, added
+     * afterwards, never inherited it. Deferring keeps the module's governing
+     * rule: the criterion still reaches selfTest(), which judges the OUTPUT and
+     * can actually tell whether the work was done.
+     */
+    workerCanWriteFiles?: boolean;
+}
 /**
  * Evaluate acceptance criteria, deciding only the mechanically checkable ones.
  * Order and length of the result always match `criteria`.
  */
-declare function evaluateAcceptance(criteria: readonly string[], ownedFiles: readonly string[], probe: AcceptanceProbe): Promise<AcceptanceResult[]>;
+declare function evaluateAcceptance(criteria: readonly string[], ownedFiles: readonly string[], probe: AcceptanceProbe, options?: AcceptanceOptions): Promise<AcceptanceResult[]>;
 /** The criteria that still need a model's judgement. */
 declare function undecided(results: readonly AcceptanceResult[]): string[];
 /** Failure messages, phrased so correctOutput can act on them directly. */
@@ -5361,6 +5792,16 @@ interface Slide {
     body: string[];
     images: ImageRef[];
     charts: ChartSpec[];
+    /**
+     * Real tables, laid out as a grid on the slide.
+     *
+     * PowerPoint holds a genuine table shape, so a Markdown table has somewhere
+     * to go. Before this existed, `parseSlide` had no branch for a `|…|` line
+     * and every row fell through to the bullet path — a deck rendered
+     * `|---|---|` as literal text where Word, from the same Markdown, showed a
+     * proper table.
+     */
+    tables: string[][][];
 }
 /** Split a Markdown deck into slides: on `---` rules, else on top-level headings. */
 declare function splitSlides(md: string): Slide[];
@@ -5380,6 +5821,23 @@ declare function extractCharts(source: string): {
     rest: string;
 };
 
+/** How a deck reveals itself. */
+interface AnimationScheme {
+    /** Slide-to-slide transition. 'none' writes no `p:transition` at all. */
+    transition: 'none' | 'fade' | 'push' | 'wipe' | 'split';
+    /** How a slide's own shapes arrive. 'none' writes no `p:timing` at all. */
+    entrance: 'none' | 'fade' | 'appear' | 'fly';
+    /**
+     * Whether shapes arrive on their own or wait for a click.
+     *
+     * Auto suits a deck that plays unattended; click suits a person presenting
+     * and is what PowerPoint's own defaults do, so it is the default here.
+     */
+    advance: 'click' | 'auto';
+    /** Entrance duration, milliseconds. Ignored when `entrance` is 'none'. */
+    durationMs: number;
+}
+
 /** Office formats we can render into a real binary. */
 type DocumentFormat = 'docx' | 'pptx' | 'xlsx';
 declare const DOCUMENT_MIME: Record<DocumentFormat, string>;
@@ -5395,6 +5853,12 @@ interface RenderOptions {
     loadImageBytes?: ImageByteLoader;
     /** Target file name — only used to pick the CSV vs TSV delimiter for xlsx. */
     name?: string;
+    /**
+     * Host-level animation defaults for `.pptx`. A deck's own `animation:`
+     * directive overrides these, because it lives in the document the user is
+     * looking at.
+     */
+    animation?: Partial<AnimationScheme>;
 }
 /**
  * CSV → a real `.xlsx` workbook.
@@ -5992,4 +6456,4 @@ declare function gatherSyncBundle(config: CascadeConfig): SyncBundle;
 /** Merge a pulled bundle into a config, returning the updated config to persist. */
 declare function applySyncBundle(bundle: SyncBundle, config: CascadeConfig, cleanup?: RetiredProviderCleanup): CascadeConfig;
 
-export { AZURE_BASE_MODELS, AZURE_BASE_URL_TEMPLATE, type AcceptanceProbe, type AcceptanceResult, type AcceptanceVerdict, type ApprovalRequest, type ApprovalResponse, type AuditEntry, AuditLogger, type AzureDeploymentInput, type BenchmarksConfig, type Block, type BudgetConfig, CASCADE_AUDIT_FILE, CASCADE_CONFIG_DIR, CASCADE_CONFIG_FILE, CASCADE_DASHBOARD_SECRET_FILE, CASCADE_DB_FILE, CASCADE_IGNORE_FILE, CASCADE_KEYSTORE_FILE, CASCADE_MD_FILE, CASCADE_VERSION, CHARS_PER_TOKEN, COMPLEXITY_T2_COUNT, Cascade, CascadeCancelledError, type CascadeConfig, type CascadeEvent, type CascadeEventType, CascadeIgnore, type CascadeMessage, CascadeRouter, type CascadeRunOptions, type CascadeRunResult, type CascadeThemeName, CascadeToolError, type ChartSeries, type ChartSpec, type Chunk, type ChunkOptions, CloudClient, type CloudConversation, type CloudMessage, type CloudSession, type CloudSessionStore, type CloudTurnInput, type CloudUser, type CodeChunkOptions, type CodeChunker, CodeSearchTool, type CompileTaskGraphOptions, type CompiledTaskGraph, type CompleteFn, type CompletedNode, ConfigManager, type ConversationMessage, type CredentialDisposition, type CredentialEndpoint, type CredentialWriteOutcome, type CurrentPageProvider, type CurrentPageSnapshot, CurrentPageTool, DEFAULT_API_PORT, DEFAULT_APPROVAL_REQUIRED, DEFAULT_AUTO_SUMMARIZE_AT, DEFAULT_CLOUD_URL, DEFAULT_CONTEXT_LIMIT, DEFAULT_DASHBOARD_PORT, DEFAULT_MAX_SESSION_MESSAGES, DEFAULT_RETENTION_DAYS, DEFAULT_THEME, DOCUMENT_MIME, type DashboardConfig, DashboardServer, DependencyScheduler, type DeviceStart, type DiscoveredMcpTool, type DistilledFact, type ChartKind as DocumentChartKind, type DocumentFormat, type Embedder, type EncryptedBlob, type EscalationDecision, type EscalationPayload, type ExtendedContextConfig, type FileManifest, FileMcpOAuthStore, GLOBAL_CONFIG_DIR, GLOBAL_CREDENTIALS_FILE, GLOBAL_DB_FILE, GLOBAL_KEYSTORE_FILE, GLOBAL_RUNTIME_DB_FILE, GenerateDocumentTool, type GenerateOptions, type GenerateResult, type GraphFactSource, GraphRetriever, type GraphSearchOptions, GraphSearchTool, type HookDefinition, type HooksConfig, HooksRunner, type Identity, type ImageAttachment, type ImageByteLoader, type ImageInfo, type ImageRef, type InlineRun, Keystore, LLMReranker, LM_STUDIO_BASE_URL, type LegacyThemeName, type LoadedImage, MAX_PAGE_TEXT_CHARS, MCP_TOOL_PREFIX, MODELS, type ManifestDiff, McpClient, type McpDiscoveryResult, McpOAuthProvider, type McpOAuthState, type McpOAuthStore, type McpServerConfig$1 as McpServerConfig, type McpServerRename, type MemoryConfig, MemoryStore, type Message, type MessageContent, type MessagePayload, type MessageStatus, type MessageType, type ModelInfo, type ModelOverrides, type NativeProvider, OLLAMA_BASE_URL, OpenAICompatibleEmbedder, type OpenAIEmbedderOptions, PROVIDER_DISPLAY_NAMES, type PeerMessage, type PeerMessageEvent, type PeerSyncPayload, type PeerSyncType, type PermissionDecision, type PermissionDecisionPayload, type PermissionRequest, type PermissionTrailEntry, type PlanReviewConfig, type ProviderConfig, type ProviderType, RESUME_SCHEMA_VERSION, type RankedFact, type RefreshResult, type RenderOptions, type Reranker, type ResumeCheckpoint, type ResumeReason, ResumeStore, type ResumeStoreOptions, type RetrievalContext, type RetrievalMode, type RetrievalPlan, Retriever, type RetrieverSearchOptions, type RuntimeNode, type RuntimeNodeLog, type RuntimeRefreshPayload, type RuntimeScope, type RuntimeSession, type RuntimeSnapshotPayload, type ScheduledTask, type SchedulerExecutionMode, type SchedulerHooks, type SchedulerOptions, type SchedulerResult, type ScoredChunk, type SearchOptions, type Session, type SessionCheckpoint, type SessionMetadata, type SessionSubscriptionPayload, type SettingsCommitResult, type SettingsCredentialResult, type SettingsPayload, type SettingsSnapshot, type Slide, SqliteVectorStore, type StatusUpdate, type StoredMessage, type StreamChunk, type SyncBundle, T1Administrator, type T1ToT2Assignment, T1_MODEL_PRIORITY, T2Manager, type T2Result, type T2ToT3Assignment, T2_MODEL_PRIORITY, type T3Result, type T3ResultPayload, type T3SubtaskSpec, T3Worker, T3_MODEL_PRIORITY, THEME_NAMES, TOOL_NAMES, type TaskComplexity, type TaskGraph, type TaskGraphInputNode, type TaskGraphIssue, type TaskGraphIssueCode, type TaskGraphNode, type TaskGraphNodeKind, TaskGraphValidationError, type TaskGraphValidationMode, TaskScheduler, Telemetry, type TelemetryConfig, type Theme, type ThemeColors, type ThemeName, type TierConfig, type TierLimits, type TierRole, type TierStatus, type TokenUsage, type ToolCall, type ToolDefinition, type ToolExecuteOptions, ToolRegistry, type ToolResult, type ToolsConfig, VISION_MODEL_PRIORITY, type VectorStore, type WebSearchConfig, type WebhookConfig, type WorkspaceConfig, type WorkspaceFileReader, WorkspaceIndex, type WorkspaceIndexOptions, applyEndpointEdit, applyProviderApiKey, applyProviderCredential, applySettingsCredentials, applySettingsPayload, applySyncBundle, azureModelForDeployment, beginMcpOAuth, buildDocumentTools, buildManifest, buildSessionTranscript, bytesToBase64, cagCharBudget, chartKind, chartToTableRows, chatCompleterFromProviders, chunkCode, chunkText, commitSettings, compileSectionGraph, compileSubtaskGraph, compileTaskGraph, completeMcpOAuth, connectMcpWithLoopbackOAuth, createCascade, credentialDispositionForEdit, credentialEndpointIdentity, decryptJSON as decryptSyncBlob, diffManifest, disambiguateMcpServerNames, discoverMcpAuthServer, discoverMcpTools, distillSessionFacts, embedderFromProviders, encryptJSON as encryptSyncBlob, endpointFromSettingsPayload, evaluateAcceptance, explainRefusal, extractCharts, failures, fileExt, fileOAuthProvider, gatherSyncBundle, hasDefaultEndpoint, hasProviderCredential, hasUsableProvider, hashContent, heuristicCodeChunker, inferAzureBaseModel, inlineRuns, isDocumentFormat, isMcpToolName, matchImageLine, mcpServerPrefix, mcpToolName, nodeHttpFetch, normalizeEndpoint, parseBlocks, parseChartSpec, parseDelimited, parseRankOrder, parseSlide, planRetrieval, preferIpv4Host, priorAzureRow, reciprocalRankFusion, refreshMcpToken, removeMcpServerDenials, renderDocument, renderDocx, renderPptx, renderXlsx, runCascade, sameAzureEndpoint, sameCredentialEndpoint, sameEndpoint, sessionWorthRemembering, settingsSnapshot, sniffImage, splitSlides, streamCascade, stripInline, summarizeCompleted, undecided, uniqueMcpServerName };
+export { AZURE_BASE_MODELS, AZURE_BASE_URL_TEMPLATE, type AcceptanceOptions, type AcceptanceProbe, type AcceptanceResult, type AcceptanceVerdict, type ApprovalRequest, type ApprovalResponse, type AuditEntry, AuditLogger, type AzureDeploymentInput, type BenchmarksConfig, type Block, type BudgetConfig, CASCADE_AUDIT_FILE, CASCADE_CONFIG_DIR, CASCADE_CONFIG_FILE, CASCADE_DASHBOARD_SECRET_FILE, CASCADE_DB_FILE, CASCADE_IGNORE_FILE, CASCADE_KEYSTORE_FILE, CASCADE_MD_FILE, CASCADE_VERSION, CHARS_PER_TOKEN, COMPLEXITY_T2_COUNT, Cascade, CascadeCancelledError, type CascadeConfig, type CascadeEvent, type CascadeEventType, CascadeIgnore, type CascadeMessage, CascadeRouter, type CascadeRunOptions, type CascadeRunResult, type CascadeThemeName, CascadeToolError, type ChartSeries, type ChartSpec, type Chunk, type ChunkOptions, CloudClient, type CloudConversation, type CloudMessage, type CloudSession, type CloudSessionStore, type CloudTurnInput, type CloudUser, type CodeChunkOptions, type CodeChunker, CodeSearchTool, type CompileTaskGraphOptions, type CompiledTaskGraph, type CompleteFn, type CompletedNode, ConfigManager, type ConversationMessage, type CredentialDisposition, type CredentialEndpoint, type CredentialWriteOutcome, type CurrentPageProvider, type CurrentPageSnapshot, CurrentPageTool, DEFAULT_API_PORT, DEFAULT_APPROVAL_REQUIRED, DEFAULT_AUTO_SUMMARIZE_AT, DEFAULT_CLOUD_URL, DEFAULT_CONTEXT_LIMIT, DEFAULT_DASHBOARD_PORT, DEFAULT_MAX_SESSION_MESSAGES, DEFAULT_RETENTION_DAYS, DEFAULT_THEME, DOCUMENT_MIME, type DashboardConfig, DashboardServer, DependencyScheduler, type DeviceStart, type DiscoveredMcpTool, type DistilledFact, type ChartKind as DocumentChartKind, type DocumentFormat, type Embedder, type EncryptedBlob, type EscalationDecision, type EscalationPayload, type ExtendedContextConfig, type FileManifest, FileMcpOAuthStore, GLOBAL_CONFIG_DIR, GLOBAL_CREDENTIALS_FILE, GLOBAL_DB_FILE, GLOBAL_KEYSTORE_FILE, GLOBAL_RUNTIME_DB_FILE, GenerateDocumentTool, type GenerateOptions, type GenerateResult, type GraphFactSource, GraphRetriever, type GraphSearchOptions, GraphSearchTool, type HookDefinition, type HooksConfig, HooksRunner, type Identity, type ImageAttachment, type ImageByteLoader, type ImageInfo, type ImageRef, type InlineRun, Keystore, LLMReranker, LM_STUDIO_BASE_URL, type LegacyThemeName, type LoadedImage, MAX_PAGE_TEXT_CHARS, MCP_TOOL_PREFIX, MODELS, type ManifestDiff, McpClient, type McpDiscoveryResult, McpOAuthProvider, type McpOAuthState, type McpOAuthStore, type McpServerConfig$1 as McpServerConfig, type McpServerRename, type MemoryConfig, MemoryStore, type Message, type MessageContent, type MessagePayload, type MessageStatus, type MessageType, type ModelInfo, type ModelOverrides, type NativeProvider, OLLAMA_BASE_URL, OpenAICompatibleEmbedder, type OpenAIEmbedderOptions, PROVIDER_DISPLAY_NAMES, type PeerMessage, type PeerMessageEvent, type PeerSyncPayload, type PeerSyncType, type PermissionDecision, type PermissionDecisionPayload, type PermissionRequest, type PermissionTrailEntry, type PlanReviewConfig, type ProviderConfig, type ProviderType, RESUME_SCHEMA_VERSION, type RankedFact, type RefreshResult, type RenderOptions, type Reranker, type ResumeCheckpoint, type ResumeReason, ResumeStore, type ResumeStoreOptions, type RetrievalContext, type RetrievalMode, type RetrievalPlan, Retriever, type RetrieverSearchOptions, type RuntimeNode, type RuntimeNodeLog, type RuntimeRefreshPayload, type RuntimeScope, type RuntimeSession, type RuntimeSnapshotPayload, type ScheduledTask, type SchedulerExecutionMode, type SchedulerHooks, type SchedulerOptions, type SchedulerResult, type ScoredChunk, type SearchOptions, type Session, type SessionCheckpoint, type SessionMetadata, type SessionSubscriptionPayload, type SettingsCommitResult, type SettingsCredentialResult, type SettingsPayload, type SettingsSnapshot, type Slide, SqliteVectorStore, type StatusUpdate, type StoredMessage, type StreamChunk, type SyncBundle, T1Administrator, type T1ToT2Assignment, T1_MODEL_PRIORITY, T2Manager, type T2Result, type T2ToT3Assignment, T2_MODEL_PRIORITY, type T3Result, type T3ResultPayload, type T3SubtaskSpec, T3Worker, T3_MODEL_PRIORITY, THEME_NAMES, TOOL_NAMES, type TaskComplexity, type TaskGraph, type TaskGraphInputNode, type TaskGraphIssue, type TaskGraphIssueCode, type TaskGraphNode, type TaskGraphNodeKind, TaskGraphValidationError, type TaskGraphValidationMode, TaskScheduler, type TaskType, Telemetry, type TelemetryConfig, type Theme, type ThemeColors, type ThemeName, type TierConfig, type TierLimits, type TierRole, type TierStatus, type TokenUsage, type ToolCall, type ToolDefinition, type ToolExecuteOptions, ToolRegistry, type ToolResult, type ToolsConfig, VISION_MODEL_PRIORITY, type VectorStore, type WebSearchConfig, type WebhookConfig, type WorkspaceConfig, type WorkspaceFileReader, WorkspaceIndex, type WorkspaceIndexOptions, applyEndpointEdit, applyProviderApiKey, applyProviderCredential, applySettingsCredentials, applySettingsPayload, applySyncBundle, azureModelForDeployment, beginMcpOAuth, buildDocumentTools, buildManifest, buildSessionTranscript, bytesToBase64, cagCharBudget, chartKind, chartToTableRows, chatCompleterFromProviders, chunkCode, chunkText, commitSettings, compileSectionGraph, compileSubtaskGraph, compileTaskGraph, completeMcpOAuth, connectMcpWithLoopbackOAuth, createCascade, credentialDispositionForEdit, credentialEndpointIdentity, decryptJSON as decryptSyncBlob, diffManifest, disambiguateMcpServerNames, discoverMcpAuthServer, discoverMcpTools, distillSessionFacts, embedderFromProviders, encryptJSON as encryptSyncBlob, endpointFromSettingsPayload, evaluateAcceptance, explainRefusal, extractCharts, failures, fileExt, fileOAuthProvider, gatherSyncBundle, hasDefaultEndpoint, hasProviderCredential, hasUsableProvider, hashContent, heuristicCodeChunker, inferAzureBaseModel, inlineRuns, isDocumentFormat, isMcpToolName, matchImageLine, mcpServerPrefix, mcpToolName, nodeHttpFetch, normalizeEndpoint, parseBlocks, parseChartSpec, parseDelimited, parseRankOrder, parseSlide, planRetrieval, preferIpv4Host, priorAzureRow, reciprocalRankFusion, refreshMcpToken, removeMcpServerDenials, renderDocument, renderDocx, renderPptx, renderXlsx, runCascade, sameAzureEndpoint, sameCredentialEndpoint, sameEndpoint, sessionWorthRemembering, settingsSnapshot, sniffImage, splitSlides, streamCascade, stripInline, summarizeCompleted, undecided, uniqueMcpServerName };