cascade-ai 0.67.0 → 0.69.0

package/dist/index.d.cts

@@ -5,6 +5,137 @@ import { OAuthClientInformationMixed, OAuthTokens, OAuthClientMetadata, OAuthCli
 export { OAuthClientInformationMixed, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
 import Database from 'better-sqlite3';
 
+/**
+ * Durable resume checkpoints.
+ *
+ * Before this, a stopped run was recoverable only through an in-memory field on
+ * the Cascade instance, set on exactly one path (the budget cap). So the two
+ * interruptions people actually hit — a crash, and Ctrl-C — lost every finished
+ * section, and even a budget stop was lost the moment the process exited. The
+ * work was on disk; the knowledge of what had been done was not.
+ *
+ * A checkpoint records the finished nodes of a run so a resume can restore them
+ * instead of paying to produce them a second time. Design constraints, in the
+ * order that shaped the code:
+ *
+ * - **A crash is one of the triggers.** Writes are atomic (temp file + rename),
+ *   because the process dying mid-write is a case this store must survive, not
+ *   an edge case. A half-written checkpoint that parses as valid JSON would be
+ *   worse than none at all.
+ * - **A corrupt or foreign checkpoint must never break the caller.** Listing
+ *   skips anything unreadable, unparseable, or written by a schema version this
+ *   build doesn't know. Resume is a convenience; it may degrade, never throw.
+ * - **Checkpoints hold the user's prompt and partial output.** They are pruned
+ *   by both count and age so that content does not accumulate in the workspace
+ *   indefinitely.
+ */
+/** Bump when the on-disk shape changes incompatibly. Older files are ignored. */
+declare const RESUME_SCHEMA_VERSION = 1;
+type ResumeReason = 'budget' | 'cancelled' | 'error' | 'breaker';
+/** A node whose work is done and must not be re-run on resume. */
+interface CompletedNode {
+    /** Stable id from the compiled task graph. */
+    id: string;
+    title: string;
+    status: 'COMPLETED' | 'PARTIAL';
+    output: string;
+}
+interface ResumeCheckpoint {
+    version: number;
+    taskId: string;
+    prompt: string;
+    /** ISO-8601. */
+    createdAt: string;
+    reason: ResumeReason;
+    /** Why the run stopped, in the words the user would see. */
+    detail?: string;
+    partialOutput: string;
+    completed: CompletedNode[];
+}
+interface ResumeStoreOptions {
+    /** Directory checkpoints live in (created on demand). */
+    dir: string;
+    /** Keep at most this many, newest first. Default 5. */
+    maxCheckpoints?: number;
+    /** Discard checkpoints older than this. Default 7 days. */
+    maxAgeMs?: number;
+    /** Injectable clock, for tests. */
+    now?: () => number;
+    /** How long a claim may be held before it is considered abandoned. */
+    claimTimeoutMs?: number;
+}
+declare class ResumeStore {
+    private readonly dir;
+    private readonly maxCheckpoints;
+    private readonly maxAgeMs;
+    private readonly now;
+    private readonly claimTimeoutMs;
+    constructor(options: ResumeStoreOptions);
+    /**
+     * Persist a checkpoint and prune.
+     *
+     * Never throws — failing to save a resume file must not turn a recoverable
+     * stop into a crash — but DOES report whether the atomic rename landed.
+     * Callers decide whether an original claim is safe to discard based on that
+     * answer, so "I swallowed the error" and "the checkpoint is on disk" must not
+     * look alike to them.
+     *
+     * @returns true only when the checkpoint is durably on disk.
+     */
+    save(checkpoint: Omit<ResumeCheckpoint, 'version' | 'createdAt'> & {
+        createdAt?: string;
+    }): Promise<boolean>;
+    /** Valid, unexpired checkpoints, newest first. */
+    list(): Promise<ResumeCheckpoint[]>;
+    /** The most recent resumable run, or null. */
+    latest(): Promise<ResumeCheckpoint | null>;
+    /**
+     * Claim a checkpoint for a resume attempt.
+     *
+     * This used to DELETE the file and return it, which opened a window with no
+     * recovery record at all: between preparing the continuation and the resumed
+     * run writing its own checkpoint, a crash lost the only copy — and a crash is
+     * precisely what this store exists to survive. Deleting on read optimised for
+     * "never resume twice" at the cost of "never lose the work", which is the
+     * wrong trade for a recovery mechanism.
+     *
+     * Instead the file is RENAMED to `.claimed`, which still hides it from
+     * `list()` (so a concurrent resume cannot take the same work) but keeps it on
+     * disk. The caller then either `release`s it — restoring it for another
+     * attempt — or `settle`s it once the resumed run is safely under way. A claim
+     * abandoned by a dead process is reclaimed after `claimTimeoutMs`.
+     */
+    claim(taskId?: string): Promise<{
+        checkpoint: ResumeCheckpoint;
+        claimId: string;
+    } | null>;
+    /** Give a claim back, so the work stays recoverable after a failed start. */
+    release(claimId: string): Promise<void>;
+    /** Discard a claim for good — the resumed run has taken ownership. */
+    settle(claimId: string): Promise<void>;
+    /**
+     * Claim-and-discard in one step. Kept for callers that genuinely want the old
+     * semantics; prefer claim/settle so a crash mid-resume stays recoverable.
+     */
+    consume(taskId?: string): Promise<ResumeCheckpoint | null>;
+    /**
+     * Return claims abandoned by a process that died mid-resume. Without this a
+     * crash between claim and settle would strand the checkpoint invisibly —
+     * trading one loss window for another.
+     */
+    reclaimStale(): Promise<number>;
+    /** Remove every checkpoint for a task id. */
+    delete(taskId: string): Promise<void>;
+    /** Drop expired checkpoints, then any beyond the newest `maxCheckpoints`. */
+    prune(): Promise<void>;
+}
+/**
+ * Render restored work for a correction planner: enough for the model to know
+ * what exists and not redo it, without pasting entire artifacts back into the
+ * prompt (which is what the token budget was being spent on in the first place).
+ */
+declare function summarizeCompleted(completed: readonly CompletedNode[], perNodeChars?: number): string;
+
 type ProviderType = 'anthropic' | 'openai' | 'gemini' | 'azure' | 'openai-compatible' | 'ollama' | 'github-models';
 interface ModelInfo {
     id: string;
@@ -244,7 +375,17 @@ interface ToolExecuteOptions {
     }>;
 }
 type TierRole = 'T1' | 'T2' | 'T3';
-type TierStatus = 'IDLE' | 'ACTIVE' | 'COMPLETED' | 'FAILED' | 'ESCALATED';
+/**
+ * A tier's lifecycle state.
+ *
+ * BLOCKED is terminal like COMPLETED and FAILED — the tier will never run,
+ * because work it depended on failed first. It is NOT the same word as
+ * `MessageStatus.BLOCKED` below, which means "running but stuck": one describes
+ * a tier that never started, the other a tier that started and cannot finish.
+ * Anything rendering a status label should treat BLOCKED as "skipped", not as
+ * an error and not as in-progress.
+ */
+type TierStatus = 'IDLE' | 'ACTIVE' | 'COMPLETED' | 'FAILED' | 'ESCALATED' | 'BLOCKED';
 type TaskComplexity = 'Simple' | 'Moderate' | 'Complex' | 'Highly Complex';
 interface TierConfig {
     role: TierRole;
@@ -317,10 +458,27 @@ interface StatusUpdate {
 interface T2Result {
     sectionId: string;
     sectionTitle: string;
-    status: 'COMPLETED' | 'PARTIAL' | 'FAILED' | 'ESCALATED';
+    /**
+     * BLOCKED is not a kind of FAILED. A failed section was attempted and did not
+     * work; a blocked one was never attempted, because something it depended on
+     * failed first — so it spent no tokens and says nothing about whether it
+     * would have worked. Reporting it as FAILED (which is what happened until
+     * now) tells the user their work broke when in fact the scheduler protected
+     * them from paying for work that could not succeed yet.
+     */
+    status: 'COMPLETED' | 'PARTIAL' | 'FAILED' | 'ESCALATED' | 'BLOCKED';
     t3Results: T3Result[];
     sectionSummary: string;
     issues: string[];
+    /**
+     * Set only on BLOCKED sections: which upstream work stopped this one, by
+     * title and by id. Structured rather than flattened into `issues`, so a UI
+     * can link a skipped section back to its cause instead of parsing prose.
+     */
+    blockedBy?: {
+        ids: string[];
+        titles: string[];
+    };
     /**
      * Set when this section reached PARTIAL because the user was asked about an
      * escalation and chose "skip" — not because a T2/T3 pipeline shortfall left
@@ -1087,7 +1245,24 @@ declare class TaskAnalyzer {
     private feedback?;
     private bias;
     private lastProfile;
-    private lastSelectedModels;
+    /** Models chosen by the run currently in flight. Cleared when it completes. */
+    private currentRunSelections;
+    /**
+     * Immutable snapshot of the last COMPLETED run: its selections AND the task
+     * type they were chosen for.
+     *
+     * The task type has to travel WITH the selections. `lastProfile` is overwritten
+     * by the next analyze(), so if run B started before the user rated run A, A's
+     * models were credited under B's task type — teaching the router that a coding
+     * model is good at creative writing, from a rating that never said so.
+     *
+     * Explicit ratings arrive after the run finishes — rateLastRun() is by nature
+     * a reaction to a finished answer — but the run finalizer calls
+     * recordRunOutcome() first, and that used to clear the only map there was. So
+     * every explicit rating iterated an empty map, recorded nothing, and returned
+     * false: the 3x-weighted user signal never reached the tracker at all.
+     */
+    private lastCompletedRun?;
     constructor(tracker?: ModelPerformanceTracker, bias?: AutoBias);
     /**
      * Supply per-model rating counts. Optional by design: a host that collects no
@@ -1119,9 +1294,17 @@ declare class TaskAnalyzer {
      */
     recordRunOutcome(outcome: 'success' | 'failure', costByTier: Record<string, number>, contextTokens?: number): void;
     /**
-     * Record an explicit user rating (good/bad) for the last run's selected models.
+     * Record an explicit user rating (good/bad) for the last COMPLETED run's models.
      * Explicit ratings carry 3× the weight of auto-detected outcomes.
-     * Does NOT clear lastSelectedModels — the auto record already did that.
+     *
+     * Reads the completed-run snapshot, not the in-flight map: by the time a user
+     * can rate an answer, the finalizer has already run and the in-flight map is
+     * empty.
+     *
+     * The snapshot is CONSUMED. recordExplicit() weights a rating 3x by recording
+     * three samples, so a double submit would inject six — a stutter on the
+     * button would count as two opinions. Consuming makes a second call a no-op
+     * that reports false, which is what "rate this run" should mean.
      */
     recordExplicitRating(rating: 'good' | 'bad'): boolean;
     private scoreModel;
@@ -2058,9 +2241,49 @@ declare abstract class BaseTier extends EventEmitter {
      * which node (Cockpit node panel / Why panel).
      */
     protected servingModel?: string;
+    /**
+     * This tier's identity IN THE TASK GRAPH — the section or subtask id the
+     * planner assigned — plus where it sat in the dependency order.
+     *
+     * `id` and `graphNodeId` are deliberately different id spaces, and both are
+     * needed. `id` identifies this tier INSTANCE ("T2_a1b2c3d4", minted per
+     * construction); `graphNodeId` identifies the WORK ("s1"), which is what
+     * dependency edges point at. Without the distinction a graph view cannot be
+     * drawn at all: `dependsOn` lists section ids, while every running tier
+     * reports a generated tier id, so every edge would name a node that never
+     * appears in the stream.
+     */
+    protected graphNodeId?: string;
+    protected graphDependsOn?: readonly string[];
+    protected graphWave?: number;
     constructor(role: TierRole, id?: string, parentId?: string);
     /** Mark this tier as the run's presenter (root tier). */
     setPresenter(on?: boolean): void;
+    /**
+     * Record where this tier sits in the compiled task graph.
+     *
+     * Called by whichever tier scheduled this one: the id and edges are known at
+     * construction, the wave only once the scheduler reaches it, so the fields
+     * are set independently rather than all at once.
+     */
+    setGraphPosition(position: {
+        nodeId?: string;
+        dependsOn?: readonly string[];
+        wave?: number;
+    }): void;
+    /**
+     * The graph fields, for spreading into a status payload.
+     *
+     * One helper rather than two literals because `tier:status` is emitted from
+     * two different call sites with two different payload shapes; adding a field
+     * to only one of them makes it arrive intermittently, which is worse for a
+     * consumer than never arriving at all.
+     */
+    protected graphFields(): {
+        nodeId?: string;
+        dependsOn?: string[];
+        waveId?: number;
+    };
     getStatus(): TierStatus;
     protected setStatus(status: TierStatus, output?: string): void;
     /** Record the model serving this tier; future status events carry it. */
@@ -2344,7 +2567,20 @@ declare class T1Administrator extends BaseTier {
     private validatePlan;
     private dispatchT2Managers;
     /**
-     * Runs T2 managers respecting dependsOn declarations using Kahn's algorithm.
+     * Runs T2 managers respecting dependsOn declarations.
+     *
+     * Graph construction, validation and cycle repair now live in
+     * compileSectionGraph (orchestration/adapters.ts), and wave execution in
+     * DependencyScheduler — the same pair T2 uses for its subtasks, so a plan is
+     * ordered by one implementation rather than two that drifted.
+     *
+     * The hand-rolled Kahn pass this replaces treated every node it could not
+     * reach as part of a cycle. That set also contains everything DOWNSTREAM of a
+     * cycle, whose in-degree can never fall to zero while its dependency is stuck,
+     * so breaking a cycle here also cut the dependencies of innocent later
+     * sections and started them immediately — before the sections they consume.
+     * compileTaskGraph uses strongly connected components, so only real cycle
+     * members are touched.
      */
     private runT2sWithDependencies;
     private compileFinalOutput;
@@ -2419,8 +2655,35 @@ declare class Cascade extends EventEmitter {
     /** Orchestration decisions for the CURRENT run — cleared on each run(). */
     private decisionLog;
     private initialized;
-    /** Last task that stopped at the budget cap — powers /continue (resumeRun). */
+    /**
+     * Last interrupted task — powers /continue (resumeRun). Kept in memory as a
+     * fast path for the same-process case; the durable copy lives in `resumeStore`
+     * so a crash or an exit no longer throws away everything already finished.
+     */
     private lastInterruptedRun?;
+    /** Durable resume checkpoints. See core/orchestration/resume-store.ts. */
+    private resumeStore?;
+    /** Claim held by an in-flight resume, settled once the run owns the work. */
+    private claimedResumeId?;
+    /**
+     * Facts inherited from the checkpoint this run is resuming, so its own
+     * checkpoint is cumulative rather than only covering this attempt.
+     */
+    private resumedFrom?;
+    /** Whether THIS run persisted a checkpoint of its own. Drives settle-vs-release. */
+    private wroteCheckpointThisRun;
+    /**
+     * Whether the run reached the end of its normal path.
+     *
+     * NOT the same as `runError == null`: the cancellation and budget handlers
+     * both null `runError` deliberately (an intentional stop is not a telemetry
+     * error) and the breaker path never sets it at all. Treating that as success
+     * meant an immediate cancel — no output, no replacement checkpoint — deleted
+     * the original claim and the finished sections with it.
+     */
+    private completedNormally;
+    /** Section results of the CURRENT run, so an interruption can checkpoint them. */
+    private currentRunCompleted;
     private initPromise?;
     private store?;
     private audit?;
@@ -2583,8 +2846,24 @@ declare class Cascade extends EventEmitter {
      * see core/router/feedback-prior.ts.
      */
     setFeedbackSource(source: FeedbackSource): void;
-    /** True when a task stopped at the budget cap and can be resumed via /continue. */
+    /**
+     * Write a durable checkpoint for an interrupted run.
+     *
+     * Best-effort throughout: a run is already ending badly on every path that
+     * calls this, and failing to record a resume file must not make that ending
+     * worse. Nothing here is allowed to throw.
+     */
+    private checkpointRun;
+    /** True when a task can be resumed via /continue (this process or a previous one). */
     hasResumableRun(): boolean;
+    /**
+     * True when a checkpoint from ANY process is resumable. Async because the
+     * durable check touches disk; `hasResumableRun` remains the sync in-memory
+     * answer for callers already on a hot path.
+     */
+    hasDurableResume(): Promise<boolean>;
+    /** Interrupted runs available to resume, newest first. */
+    listResumableRuns(): Promise<ResumeCheckpoint[]>;
     /**
      * Raise the per-run token budget for a resume and return the continuation
      * prompt (or null when nothing is resumable). Consumes the interrupted-run
@@ -2594,6 +2873,39 @@ declare class Cascade extends EventEmitter {
     prepareResume(opts?: {
         maxTokens?: number;
     }): string | null;
+    /**
+     * Durable counterpart to prepareResume: recovers a run interrupted in ANY
+     * process, including one that crashed before it could return. Consumes the
+     * checkpoint, so the same finished work is never restored into two runs.
+     */
+    prepareDurableResume(opts?: {
+        maxTokens?: number;
+        taskId?: string;
+    }): Promise<string | null>;
+    /**
+     * Discard the claimed checkpoint once the resumed run has taken ownership of
+     * the work (it has produced its own checkpoint, or finished). Called by the
+     * run loop; safe to call when nothing is claimed.
+     */
+    private settleClaimedResume;
+    /**
+     * Hand back a claim taken by prepareDurableResume() when the caller never
+     * gets as far as run(). The REPL prepares the continuation and submits it
+     * separately, so a failure in between would otherwise strand the checkpoint
+     * for the whole lease timeout before reclaimStale() could recover it.
+     */
+    releaseClaimedResume(): Promise<void>;
+    /** A resume gets a bigger budget — the previous attempt exhausted the old one. */
+    private raiseBudgetForResume;
+    /**
+     * The resume prompt. Completed sections are named explicitly rather than
+     * gestured at: "do not recreate the files" is an instruction a planner can
+     * only guess at, whereas a list of what is already done, and what it produced,
+     * is something it can act on. That difference is the entire reason node
+     * results are kept — a re-plan that cannot see the finished work will plan the
+     * finished work again, and the user pays for it a second time.
+     */
+    private buildResumePrompt;
     /**
      * Resume the last budget-capped task with a raised budget (SDK/headless).
      * Returns null when there is nothing to resume.
@@ -2899,14 +3211,6 @@ declare class T2Manager extends BaseTier {
      *     then reduce in-degrees of their dependents and repeat.
      */
     private runWithDependencies;
-    /**
-     * Detects cyclic dependencies using Kahn's algorithm and breaks them
-     * by removing back-edges. Returns a sanitized copy of assignments.
-     *
-     * A cycle like t1→t2→t3→t1 is broken at the last edge (t3→t1),
-     * meaning t3 will start without waiting for t1, preventing deadlock.
-     */
-    private breakCycles;
     private retryT3;
     private publishSectionOutput;
     private aggregateResults;
@@ -2997,6 +3301,11 @@ declare class T3Worker extends BaseTier {
      * needed. Best-effort: any parse/error just keeps the current output.
      */
     private reflectAndImprove;
+    /**
+     * Run the acceptance criteria that can be settled by looking at the workspace.
+     * Reads go through the same workspace-relative resolution verifyArtifacts uses.
+     */
+    private checkAcceptance;
     private selfTest;
     /**
      * world-state v2: distill a completed subtask's output into durable
@@ -3018,6 +3327,193 @@ declare class T3Worker extends BaseTier {
     private isFileOperation;
 }
 
+type TaskGraphNodeKind = 'section' | 'subtask';
+type TaskGraphValidationMode = 'strict' | 'repair';
+interface TaskGraphInputNode<TPayload> {
+    id: string;
+    title: string;
+    kind: TaskGraphNodeKind;
+    dependsOn?: readonly string[];
+    payload: TPayload;
+}
+interface TaskGraphNode<TPayload> {
+    id: string;
+    title: string;
+    kind: TaskGraphNodeKind;
+    dependsOn: readonly string[];
+    payload: TPayload;
+    /** Stable source order used to keep execution deterministic. */
+    ordinal: number;
+}
+interface TaskGraph<TPayload> {
+    nodes: readonly TaskGraphNode<TPayload>[];
+}
+type TaskGraphIssueCode = 'INVALID_NODE' | 'DUPLICATE_NODE_ID' | 'SELF_DEPENDENCY' | 'UNKNOWN_DEPENDENCY' | 'CYCLE_EDGE_REMOVED';
+interface TaskGraphIssue {
+    code: TaskGraphIssueCode;
+    message: string;
+    nodeId?: string;
+    dependencyId?: string;
+}
+interface CompiledTaskGraph<TPayload> {
+    graph: TaskGraph<TPayload>;
+    issues: readonly TaskGraphIssue[];
+}
+interface CompileTaskGraphOptions {
+    /**
+     * strict: reject malformed LLM plans.
+     * repair: preserve today's graceful-degradation behaviour by dropping only
+     * invalid dependency edges and duplicate/invalid nodes.
+     */
+    mode?: TaskGraphValidationMode;
+}
+declare class TaskGraphValidationError extends Error {
+    readonly issues: readonly TaskGraphIssue[];
+    constructor(issues: readonly TaskGraphIssue[]);
+}
+/**
+ * Compile untrusted planner output into a deterministic, schedulable graph.
+ * The compiler is the trust boundary between LLM-authored JSON and execution.
+ */
+declare function compileTaskGraph<TPayload>(inputNodes: readonly TaskGraphInputNode<TPayload>[], options?: CompileTaskGraphOptions): CompiledTaskGraph<TPayload>;
+
+type SchedulerExecutionMode = 'parallel' | 'sequential';
+/**
+ * How a finished node turned out.
+ *
+ * The scheduler used to know only "the promise resolved", which is not the same
+ * question. T1 catches worker errors into an ordinary `T2Result { status:
+ * 'FAILED' }` so one dead section cannot crash the run — a resolved value. The
+ * scheduler saw success and released the dependents anyway, so "run the
+ * integration tests" would start after "implement the API" had failed outright,
+ * and then fail too, and bill for the privilege.
+ *
+ * `partial` deliberately does NOT block: partial output is usable, and treating
+ * it as failure would cancel work that a degraded-but-real result can support.
+ */
+type NodeOutcome = 'succeeded' | 'partial' | 'failed';
+/** What to do with the dependents of a failed node. */
+type UpstreamFailurePolicy = 
+/** Run them anyway — the historical behaviour, kept as the default. */
+'continue'
+/** Skip them, transitively, and report why. */
+ | 'block';
+/** Why a node never ran. */
+interface BlockedNode {
+    /**
+     * Ids of the failed ancestors responsible, nearest first. Stable and
+     * machine-readable — use these to link a blocked node back to its cause.
+     */
+    blockedBy: string[];
+    /**
+     * The same ancestors by title, in the same order. Node ids are internal
+     * ("s1", "s2"); anything a person reads should use these instead.
+     */
+    blockedByTitles: string[];
+    /** A sentence naming the cause, written with titles rather than ids. */
+    reason: string;
+}
+interface SchedulerHooks<TPayload, TResult> {
+    execute(node: TaskGraphNode<TPayload>): Promise<TResult>;
+    onWaveStart?(nodes: readonly TaskGraphNode<TPayload>[], wave: number): void | Promise<void>;
+    onNodeComplete?(node: TaskGraphNode<TPayload>, result: TResult): void | Promise<void>;
+    /**
+     * Decide whether a result counts as success. Omit it and every result counts
+     * as `succeeded`, which is exactly the previous behaviour — so adding failure
+     * awareness to a caller is opt-in and cannot silently change an existing one.
+     */
+    classify?(node: TaskGraphNode<TPayload>, result: TResult): NodeOutcome;
+    /**
+     * A node that will never run because an ancestor failed. Callers use this to
+     * synthesize a result for it, so downstream reporting still sees every node.
+     */
+    onNodeBlocked?(node: TaskGraphNode<TPayload>, blocked: BlockedNode): void | Promise<void>;
+}
+interface SchedulerOptions {
+    mode?: SchedulerExecutionMode;
+    /** Defaults to 'continue' so existing callers behave exactly as before. */
+    onUpstreamFailure?: UpstreamFailurePolicy;
+}
+interface SchedulerResult<TResult> {
+    results: ReadonlyMap<string, TResult>;
+    waves: readonly (readonly string[])[];
+    /** Nodes skipped because an ancestor failed. Empty under 'continue'. */
+    blocked: ReadonlyMap<string, BlockedNode>;
+}
+/**
+ * Shared deterministic dependency scheduler for T1 sections and T2 subtasks.
+ * Graph validation/repair belongs in compileTaskGraph; this class only executes
+ * a valid DAG in stable source order.
+ */
+declare class DependencyScheduler<TPayload, TResult> {
+    private readonly graph;
+    private readonly hooks;
+    private readonly options;
+    constructor(graph: TaskGraph<TPayload>, hooks: SchedulerHooks<TPayload, TResult>, options?: SchedulerOptions);
+    run(): Promise<SchedulerResult<TResult>>;
+}
+
+declare function compileSectionGraph(sections: readonly T1ToT2Assignment[]): CompiledTaskGraph<T1ToT2Assignment>;
+/**
+ * The subtask fields the graph actually needs. Generic over the whole record so
+ * both the planner's `T3SubtaskSpec` and T2's richer `T2ToT3Assignment` compile
+ * without a cast — they carry the same identity and dependency fields, and the
+ * payload comes back out at its original type.
+ */
+interface SubtaskGraphInput {
+    subtaskId: string;
+    subtaskTitle: string;
+    dependsOn?: string[];
+}
+declare function compileSubtaskGraph<TSubtask extends SubtaskGraphInput>(subtasks: readonly TSubtask[]): CompiledTaskGraph<TSubtask>;
+
+/**
+ * The deterministic rung of the verification ladder.
+ *
+ * T1 asks the planner for acceptance criteria that are "1-3 checks a reviewer
+ * could verify mechanically (file exists / contains X / command exits 0)", and
+ * the planner obliges — but nothing ever checked them mechanically. Every
+ * criterion went to selfTest(), an LLM call, which is both slower and a worse
+ * judge of "does this file exist" than `stat` is. A grader that hallucinates a
+ * pass on a file that was never written is exactly the failure the criteria
+ * were introduced to prevent.
+ *
+ * So: decide here what can be decided by looking, and hand the rest to the
+ * model unchanged. The governing rule is that **deferring is always safe and
+ * deciding wrongly is not**, so every pattern below is deliberately narrow.
+ * A criterion this module cannot confidently parse comes back `undecidable`
+ * and the LLM grader sees it exactly as it does today.
+ *
+ * Shell criteria ("command exits 0") are deliberately NOT executed. Acceptance
+ * text is LLM-authored and reaches this code as free prose; running it would
+ * turn a plan into an arbitrary command execution channel. Those stay
+ * undecidable.
+ */
+type AcceptanceVerdict = 'passed' | 'failed' | 'undecidable';
+interface AcceptanceResult {
+    criterion: string;
+    verdict: AcceptanceVerdict;
+    /** Human-readable reason, present for passed/failed. */
+    detail?: string;
+}
+interface AcceptanceProbe {
+    /** null when the path does not exist or is not a regular file. */
+    stat(path: string): Promise<{
+        size: number;
+    } | null>;
+    /** utf-8 contents, or null when unreadable (missing, binary, too large). */
+    read(path: string): Promise<string | null>;
+}
+/**
+ * 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[]>;
+/** 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. */
+declare function failures(results: readonly AcceptanceResult[]): string[];
+
 /**
  * High-level SDK entry point — loads config from the workspace and runs a task.
  *
@@ -3224,7 +3720,13 @@ declare class DashboardSocket {
     broadcastToRoom(room: string, event: string, data: unknown): void;
     broadcast(event: string, data: unknown): void;
     emitCascadeEvent(ev: CascadeEvent): void;
-    emitTierStatus(tierId: string, role: string, status: string, sessionId: string, action?: string): void;
+    /**
+     * `extra` exists because this signature is positional: every field the tier
+     * emits that is not named here is silently dropped on this path, while the
+     * other two forwarders spread the whole event through. That asymmetry is how
+     * a field can reach the web dashboard from one code path and not another.
+     */
+    emitTierStatus(tierId: string, role: string, status: string, sessionId: string, action?: string, extra?: Record<string, unknown>): void;
     emitStreamToken(tierId: string, text: string, sessionId: string): void;
     emitPeerMessage(event: PeerMessageEvent): void;
     emitApprovalRequest(request: PermissionRequest): void;
@@ -4812,4 +5314,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): CascadeConfig;
 
-export { AZURE_BASE_MODELS, AZURE_BASE_URL_TEMPLATE, type ApprovalRequest, type ApprovalResponse, type AuditEntry, AuditLogger, 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 CompleteFn, ConfigManager, type ConversationMessage, 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, 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, GITHUB_MODELS_API_VERSION, GITHUB_MODELS_CATALOG_URL, GITHUB_MODELS_INFERENCE_URL, 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, type RankedFact, type RefreshResult, type RenderOptions, type Reranker, type RetrievalContext, type RetrievalMode, type RetrievalPlan, Retriever, type RetrieverSearchOptions, type RuntimeNode, type RuntimeNodeLog, type RuntimeRefreshPayload, type RuntimeScope, type RuntimeSession, type RuntimeSnapshotPayload, type ScheduledTask, type ScoredChunk, type SearchOptions, type Session, type SessionCheckpoint, type SessionMetadata, type SessionSubscriptionPayload, 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, 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, applySyncBundle, azureModelForDeployment, beginMcpOAuth, buildDocumentTools, buildManifest, buildSessionTranscript, bytesToBase64, cagCharBudget, chartKind, chartToTableRows, chatCompleterFromProviders, chunkCode, chunkText, completeMcpOAuth, connectMcpWithLoopbackOAuth, createCascade, decryptJSON as decryptSyncBlob, diffManifest, disambiguateMcpServerNames, discoverMcpAuthServer, discoverMcpTools, distillSessionFacts, embedderFromProviders, encryptJSON as encryptSyncBlob, extractCharts, fileExt, fileOAuthProvider, gatherSyncBundle, hashContent, heuristicCodeChunker, inferAzureBaseModel, inlineRuns, isDocumentFormat, isMcpToolName, matchImageLine, mcpServerPrefix, mcpToolName, nodeHttpFetch, parseBlocks, parseChartSpec, parseDelimited, parseRankOrder, parseSlide, planRetrieval, preferIpv4Host, reciprocalRankFusion, refreshMcpToken, removeMcpServerDenials, renderDocument, renderDocx, renderPptx, renderXlsx, runCascade, sessionWorthRemembering, sniffImage, splitSlides, streamCascade, stripInline, uniqueMcpServerName };
+export { AZURE_BASE_MODELS, AZURE_BASE_URL_TEMPLATE, type AcceptanceProbe, type AcceptanceResult, type AcceptanceVerdict, type ApprovalRequest, type ApprovalResponse, type AuditEntry, AuditLogger, 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 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, GITHUB_MODELS_API_VERSION, GITHUB_MODELS_CATALOG_URL, GITHUB_MODELS_INFERENCE_URL, 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 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, applySyncBundle, azureModelForDeployment, beginMcpOAuth, buildDocumentTools, buildManifest, buildSessionTranscript, bytesToBase64, cagCharBudget, chartKind, chartToTableRows, chatCompleterFromProviders, chunkCode, chunkText, compileSectionGraph, compileSubtaskGraph, compileTaskGraph, completeMcpOAuth, connectMcpWithLoopbackOAuth, createCascade, decryptJSON as decryptSyncBlob, diffManifest, disambiguateMcpServerNames, discoverMcpAuthServer, discoverMcpTools, distillSessionFacts, embedderFromProviders, encryptJSON as encryptSyncBlob, evaluateAcceptance, extractCharts, failures, fileExt, fileOAuthProvider, gatherSyncBundle, hashContent, heuristicCodeChunker, inferAzureBaseModel, inlineRuns, isDocumentFormat, isMcpToolName, matchImageLine, mcpServerPrefix, mcpToolName, nodeHttpFetch, parseBlocks, parseChartSpec, parseDelimited, parseRankOrder, parseSlide, planRetrieval, preferIpv4Host, reciprocalRankFusion, refreshMcpToken, removeMcpServerDenials, renderDocument, renderDocx, renderPptx, renderXlsx, runCascade, sessionWorthRemembering, sniffImage, splitSlides, streamCascade, stripInline, summarizeCompleted, undecided, uniqueMcpServerName };