@smithers-orchestrator/driver 0.24.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithers-orchestrator/driver",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Workflow execution driver — runs tasks, acts on EngineDecisions, reports results",
   "type": "module",
   "sideEffects": false,
@@ -63,11 +63,11 @@
   "dependencies": {
     "effect": "^3.21.1",
     "zod": "^4.3.6",
-    "@smithers-orchestrator/db": "0.24.0",
-    "@smithers-orchestrator/errors": "0.24.0",
-    "@smithers-orchestrator/graph": "0.24.0",
-    "@smithers-orchestrator/observability": "0.24.0",
-    "@smithers-orchestrator/scheduler": "0.24.0"
+    "@smithers-orchestrator/db": "0.25.0",
+    "@smithers-orchestrator/graph": "0.25.0",
+    "@smithers-orchestrator/observability": "0.25.0",
+    "@smithers-orchestrator/errors": "0.25.0",
+    "@smithers-orchestrator/scheduler": "0.25.0"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/ResolveOutputRow.ts

@@ -0,0 +1,26 @@
+import type { z } from "zod";
+
+/**
+ * Resolve the row type a `ctx.output`/`ctx.outputMaybe`/`ctx.latest` call returns
+ * from the `table` argument it was given:
+ *
+ * - a string table name (a key of the workflow Schema) → the inferred row for
+ *   that registered schema (`outputs.X` keyed by name);
+ * - a Zod schema object (e.g. `outputs.research`) → `z.infer` of that schema;
+ * - a Drizzle table (carries `$inferSelect`) → its select row;
+ * - anything else (a widened `string`, `unknown`) → an untyped output row.
+ *
+ * This is what makes `ctx.outputMaybe(outputs.research, ...)` carry the research
+ * fields instead of an untyped `Record<string, unknown>`.
+ */
+export type ResolveOutputRow<Schema, T> = T extends keyof Schema
+	? Schema[T] extends z.ZodTypeAny
+		? z.infer<Schema[T]>
+		: Schema[T] extends { $inferSelect: infer R }
+			? R
+			: Record<string, unknown>
+	: T extends z.ZodTypeAny
+		? z.infer<T>
+		: T extends { $inferSelect: infer R }
+			? R
+			: Record<string, unknown>;

package/src/RunOptions.ts

@@ -1,4 +1,5 @@
 import type { RunAuthContext } from "./RunAuthContext.ts";
+import type { OutputSnapshot } from "./OutputSnapshot.ts";
 import type { SmithersEvent } from "@smithers-orchestrator/observability/SmithersEvent";
 
 export type HotReloadOptions = {
@@ -19,6 +20,7 @@ export type RunOptions = {
   parentRunId?: string | null;
   input: Record<string, unknown>;
   maxConcurrency?: number;
+  requireRerenderOnOutputChange?: boolean;
   onProgress?: (e: SmithersEvent) => void;
   signal?: AbortSignal;
   resume?: boolean;
@@ -34,6 +36,9 @@ export type RunOptions = {
   auth?: RunAuthContext | null;
   config?: Record<string, unknown>;
   cliAgentToolsDefault?: "all" | "explicit-only";
+  initialOutputs?: OutputSnapshot;
+  initialIteration?: number;
+  initialIterations?: Record<string, number> | ReadonlyMap<string, number>;
   resumeClaim?: {
     claimOwnerId: string;
     claimHeartbeatAtMs: number;

package/src/RunStatus.ts

@@ -3,6 +3,7 @@ export type RunStatus =
   | "waiting-approval"
   | "waiting-event"
   | "waiting-timer"
+  | "waiting-quota"
   | "finished"
   | "continued"
   | "failed"

package/src/SmithersCtx.js

@@ -12,6 +12,11 @@ import { resolveWorktreePath } from "@smithers-orchestrator/graph";
 /** @typedef {import("./SmithersRuntimeConfig.ts").SmithersRuntimeConfig} SmithersRuntimeConfig */
 /** @typedef {unknown} TableRef */
 /** @typedef {Record<string, unknown>} OutputRow User-visible output row — harness metadata fields (runId, nodeId, iteration) are stripped. */
+/**
+ * @template Schema
+ * @template T
+ * @typedef {import("./ResolveOutputRow.ts").ResolveOutputRow<Schema, T>} ResolveOutputRow
+ */
 /**
  * @template Schema
  * @typedef {import("./OutputAccessor.ts").OutputAccessor<Schema>} OutputAccessor
@@ -119,36 +124,93 @@ export class SmithersCtx {
         });
     }
     /**
-     * @param {TableRef} table
+     * @template {keyof Schema & string} K
+     * @overload
+     * @param {K} table
+     * @param {OutputKey} key
+     * @returns {ResolveOutputRow<Schema, K>}
+     */
+    /**
+     * @template {TableRef} T
+     * @overload
+     * @param {T} table
      * @param {OutputKey} key
-     * @returns {OutputRow}
+     * @returns {ResolveOutputRow<Schema, T>}
+     */
+    /**
+     * @template {TableRef} T
+     * @param {T} table
+     * @param {OutputKey} key
+     * @returns {ResolveOutputRow<Schema, T>}
      */
     output(table, key) {
         const row = this.resolveRow(table, key);
         if (!row) {
             throw new SmithersError("MISSING_OUTPUT", `Missing output for nodeId=${key.nodeId} iteration=${key.iteration ?? 0}`, { nodeId: key.nodeId, iteration: key.iteration ?? 0 });
         }
-        return /** @type {OutputRow} */ (stripAutoColumns(row));
+        return /** @type {ResolveOutputRow<Schema, T>} */ (/** @type {unknown} */ (stripAutoColumns(row)));
     }
     /**
-     * @param {TableRef} table
+     * Resolve a single output row. Without an explicit `key.iteration` this
+     * resolves the CURRENT render iteration — which equals the loop iteration
+     * only for a single, non-nested loop, and is 0 when several loops coexist.
+     * For a `<Loop>` exit condition use {@link latest} (the most recent
+     * iteration), not `outputMaybe`, or an `until` built on it never advances.
+     *
+     * @template {keyof Schema & string} K
+     * @overload
+     * @param {K} table
      * @param {OutputKey} key
-     * @returns {OutputRow | undefined}
+     * @returns {ResolveOutputRow<Schema, K> | undefined}
+     */
+    /**
+     * @template {TableRef} T
+     * @overload
+     * @param {T} table
+     * @param {OutputKey} key
+     * @returns {ResolveOutputRow<Schema, T> | undefined}
+     */
+    /**
+     * @template {TableRef} T
+     * @param {T} table
+     * @param {OutputKey} key
+     * @returns {ResolveOutputRow<Schema, T> | undefined}
      */
     outputMaybe(table, key) {
         const row = this.resolveRow(table, key);
-        return row !== undefined ? /** @type {OutputRow} */ (stripAutoColumns(row)) : undefined;
+        return row !== undefined ? /** @type {ResolveOutputRow<Schema, T>} */ (/** @type {unknown} */ (stripAutoColumns(row))) : undefined;
     }
     /**
-     * @param {TableRef} table
+     * Resolve the most recent iteration's output row for `nodeId` (highest
+     * iteration across all matching rows). This is the correct reader for a
+     * `<Loop>`/`<Ralph>` `until` exit condition; {@link outputMaybe} resolves
+     * the current render iteration and can read stale/iteration-0 data inside a
+     * loop.
+     *
+     * @template {keyof Schema & string} K
+     * @overload
+     * @param {K} table
      * @param {string} nodeId
-     * @returns {OutputRow | undefined}
+     * @returns {ResolveOutputRow<Schema, K> | undefined}
+     */
+    /**
+     * @template {TableRef} T
+     * @overload
+     * @param {T} table
+     * @param {string} nodeId
+     * @returns {ResolveOutputRow<Schema, T> | undefined}
+     */
+    /**
+     * @template {TableRef} T
+     * @param {T} table
+     * @param {string} nodeId
+     * @returns {ResolveOutputRow<Schema, T> | undefined}
      */
     latest(table, nodeId) {
         const tableName = this.resolveTableName(table);
         const rows = this._outputs[tableName] ?? [];
         const matching = filterRowsByNodeId(rows, nodeId, this._currentScopes);
-        /** @type {OutputRow | undefined} */
+        /** @type {ResolveOutputRow<Schema, T> | undefined} */
         let best = undefined;
         let bestIteration = -Infinity;
         for (const row of matching) {
@@ -156,7 +218,7 @@ export class SmithersCtx {
                 ? Number(row.iteration)
                 : 0;
             if (!best || iter >= bestIteration) {
-                best = row;
+                best = /** @type {ResolveOutputRow<Schema, T>} */ (/** @type {unknown} */ (row));
                 bestIteration = iter;
             }
         }

package/src/WorkflowDriver.js

@@ -20,7 +20,6 @@ import { withAbort } from "./withAbort.js";
 /** @typedef {import("@smithers-orchestrator/graph/types").TaskDescriptor} TaskDescriptor */
 
 const SCHEDULER_SPECIFIER = "@smithers-orchestrator/scheduler";
-const LOCAL_SCHEDULER_SPECIFIER = "../../scheduler/src/index.js";
 function createRunId() {
     return `run_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
 }
@@ -155,19 +154,17 @@ function mergeOutputSnapshots(base, live) {
  * @returns {Promise<CreateWorkflowSession | null>}
  */
 async function loadCreateSession() {
-    for (const specifier of [SCHEDULER_SPECIFIER, LOCAL_SCHEDULER_SPECIFIER]) {
-        let mod;
-        try {
-            mod = (await import(specifier));
-        }
-        catch {
-            continue;
-        }
-        if (typeof mod.createSession === "function")
-            return mod.createSession;
-        if (typeof mod.makeWorkflowSession === "function") {
-            return mod.makeWorkflowSession;
-        }
+    let mod;
+    try {
+        // The scheduler is a workspace dependency, so the package specifier always
+        // resolves (no relative-path fallback needed).
+        mod = (await import(SCHEDULER_SPECIFIER));
+    }
+    catch {
+        return null;
+    }
+    if (typeof mod.makeWorkflowSession === "function") {
+        return mod.makeWorkflowSession;
     }
     return null;
 }
@@ -276,6 +273,8 @@ export class WorkflowDriver {
     baseOutputs = {};
     /** @type {Map<string, Promise<{ key: string; task: TaskDescriptor; kind: "completed" | "failed" | "cancelled"; output?: unknown; error?: unknown }>>} */
     inflightTasks = new Map();
+    /** @type {Map<string, TaskDescriptor>} */
+    inflightTaskDescriptors = new Map();
     /** @type {Array<{ key: string; task: TaskDescriptor; kind: "completed" | "failed" | "cancelled"; output?: unknown; error?: unknown }>} */
     settledTasks = [];
     /**
@@ -428,6 +427,7 @@ export class WorkflowDriver {
             defaultIteration: iteration,
             baseRootDir,
             workflowPath,
+            trigger: context.trigger,
         });
         // Capture tasks that deferred on unresolved deps this render so the run
         // loop can fail loudly if any survive to a Finished decision instead of
@@ -490,10 +490,12 @@ export class WorkflowDriver {
             }
         })().then((settled) => {
             this.inflightTasks.delete(key);
+            this.inflightTaskDescriptors.delete(key);
             this.settledTasks.push(settled);
             return settled;
         });
         this.inflightTasks.set(key, promise);
+        this.inflightTaskDescriptors.set(key, task);
     }
     /**
    * Wait for the next settled task (or an optional deadline) and report it to
@@ -506,9 +508,12 @@ export class WorkflowDriver {
         if (!this.session) {
             throw new Error("WorkflowSession is not initialized.");
         }
-        const waitStart = performance.now();
+        let waitedTasks = [];
+        let waitStart = 0;
         try {
             if (this.settledTasks.length === 0 && this.inflightTasks.size > 0) {
+                waitedTasks = [...this.inflightTaskDescriptors.values()];
+                waitStart = performance.now();
                 const racers = [...this.inflightTasks.values()];
                 if (deadlineMs != null) {
                     racers.push(sleepWithAbort(deadlineMs, this.activeOptions?.signal).then(() => null));
@@ -517,10 +522,12 @@ export class WorkflowDriver {
             }
         }
         finally {
-            await this.onSchedulerWait?.(performance.now() - waitStart, {
-                runId: this.activeRunId,
-                tasks: [],
-            });
+            if (waitedTasks.length > 0) {
+                await this.onSchedulerWait?.(performance.now() - waitStart, {
+                    runId: this.activeRunId,
+                    tasks: waitedTasks,
+                });
+            }
         }
         if (this.activeOptions?.signal?.aborted) {
             return this.cancelRun();
@@ -603,6 +610,8 @@ export class WorkflowDriver {
                 return { runId: this.activeRunId, status: "waiting-event" };
             case "Timer":
                 return { runId: this.activeRunId, status: "waiting-timer" };
+            case "Quota":
+                return { runId: this.activeRunId, status: "waiting-quota" };
             case "RetryBackoff": {
                 await sleepWithAbort(reason.waitMs, this.activeOptions?.signal);
                 if (this.activeOptions?.signal?.aborted) {

package/src/index.d.ts

@@ -1,12 +1,12 @@
-import * as _smithers_graph_types from '@smithers-orchestrator/graph/types';
+import * as _smithers_orchestrator_graph_types from '@smithers-orchestrator/graph/types';
 import { WorkflowGraph as WorkflowGraph$1, TaskDescriptor as TaskDescriptor$1 } from '@smithers-orchestrator/graph/types';
 import { SmithersEvent } from '@smithers-orchestrator/observability/SmithersEvent';
-import * as _smithers_scheduler from '@smithers-orchestrator/scheduler';
+import * as _smithers_orchestrator_scheduler from '@smithers-orchestrator/scheduler';
 import { WaitReason as WaitReason$1, EngineDecision as EngineDecision$1 } from '@smithers-orchestrator/scheduler';
 import { z } from 'zod';
 import { SmithersWorkflowOptions } from '@smithers-orchestrator/scheduler/SmithersWorkflowOptions';
 import { SchemaRegistryEntry } from '@smithers-orchestrator/db/SchemaRegistryEntry';
-import * as _smithers_graph from '@smithers-orchestrator/graph';
+import * as _smithers_orchestrator_graph from '@smithers-orchestrator/graph';
 import { ExtractOptions, WorkflowGraph } from '@smithers-orchestrator/graph';
 
 type TaskCompletedEvent = {
@@ -40,6 +40,10 @@ type RunAuthContext$2 = {
     createdAt: string;
 };
 
+type OutputSnapshot$2<TFallback = unknown> = {
+    [tableName: string]: Array<TFallback>;
+};
+
 type HotReloadOptions$1 = {
     /** Root directory to watch for changes (default: auto-detect from workflow entry) */
     rootDir?: string;
@@ -57,6 +61,7 @@ type RunOptions$2 = {
     parentRunId?: string | null;
     input: Record<string, unknown>;
     maxConcurrency?: number;
+    requireRerenderOnOutputChange?: boolean;
     onProgress?: (e: SmithersEvent) => void;
     signal?: AbortSignal;
     resume?: boolean;
@@ -72,6 +77,9 @@ type RunOptions$2 = {
     auth?: RunAuthContext$2 | null;
     config?: Record<string, unknown>;
     cliAgentToolsDefault?: "all" | "explicit-only";
+    initialOutputs?: OutputSnapshot$2;
+    initialIteration?: number;
+    initialIterations?: Record<string, number> | ReadonlyMap<string, number>;
     resumeClaim?: {
         claimOwnerId: string;
         claimHeartbeatAtMs: number;
@@ -80,7 +88,7 @@ type RunOptions$2 = {
     };
 };
 
-type RunStatus$1 = "running" | "waiting-approval" | "waiting-event" | "waiting-timer" | "finished" | "continued" | "failed" | "cancelled";
+type RunStatus$1 = "running" | "waiting-approval" | "waiting-event" | "waiting-timer" | "waiting-quota" | "finished" | "continued" | "failed" | "cancelled";
 
 type RunResult$2 = {
     readonly runId: string;
@@ -136,10 +144,25 @@ type OutputAccessor$2<Schema, TRow = unknown> = {
 } & {
     [K in keyof Schema & string]: Array<InferOutputEntry$1<Schema[K]>>;
 };
-type OutputSchemaKey<Schema> = Exclude<keyof Schema & string, "input">;
-type OutputSchemaValue<Schema> = Schema[OutputSchemaKey<Schema>];
-type StrictTableRef<Schema> = [OutputSchemaKey<Schema>] extends [never] ? TableRef : OutputSchemaKey<Schema> | OutputSchemaValue<Schema>;
-type OutputForTable<Schema, Table> = Table extends OutputSchemaKey<Schema> ? InferOutputEntry$1<Schema[Table]> : Table extends OutputSchemaValue<Schema> ? InferOutputEntry$1<Table> : OutputRow;
+
+/**
+ * Resolve the row type a `ctx.output`/`ctx.outputMaybe`/`ctx.latest` call returns
+ * from the `table` argument it was given:
+ *
+ * - a string table name (a key of the workflow Schema) → the inferred row for
+ *   that registered schema (`outputs.X` keyed by name);
+ * - a Zod schema object (e.g. `outputs.research`) → `z.infer` of that schema;
+ * - a Drizzle table (carries `$inferSelect`) → its select row;
+ * - anything else (a widened `string`, `unknown`) → an untyped output row.
+ *
+ * This is what makes `ctx.outputMaybe(outputs.research, ...)` carry the research
+ * fields instead of an untyped `Record<string, unknown>`.
+ */
+type ResolveOutputRow$1<Schema, T> = T extends keyof Schema ? Schema[T] extends z.ZodTypeAny ? z.infer<Schema[T]> : Schema[T] extends {
+    $inferSelect: infer R;
+} ? R : Record<string, unknown> : T extends z.ZodTypeAny ? z.infer<T> : T extends {
+    $inferSelect: infer R;
+} ? R : Record<string, unknown>;
 
 type SmithersRuntimeConfig$1 = {
     cliAgentToolsDefault?: "all" | "explicit-only";
@@ -148,10 +171,6 @@ type SmithersRuntimeConfig$1 = {
     worktreePaths?: Record<string, string>;
 };
 
-type OutputSnapshot$2<TFallback = unknown> = {
-    [tableName: string]: Array<TFallback>;
-};
-
 type SmithersCtxOptions$2 = {
     runId: string;
     iteration: number;
@@ -210,6 +229,19 @@ declare class SmithersCtx<Schema extends unknown = unknown> {
     _zodToKeyName: Map<unknown, string> | undefined;
     /** @type {Set<string>} */
     _currentScopes: Set<string>;
+    /**
+     * Tasks that declared `deps` but could not resolve them this render, so
+     * they deferred (returned null) instead of mounting. The engine reads this
+     * after each render: a deferral is normal while an upstream is still
+     * producing, but one that survives to quiescence means the dependency can
+     * never resolve (e.g. a deps/needs key that maps to a node id no task
+     * produces) and the run would otherwise finish silently without it.
+     * @type {{ nodeId: string; waitingOn: string[] }[]}
+     */
+    _deferredDeps: {
+        nodeId: string;
+        waitingOn: string[];
+    }[];
     /**
      * Return the resolved absolute path for a rendered worktree or task id.
      * The lookup is populated from task descriptors, so task node ids and
@@ -228,23 +260,65 @@ declare class SmithersCtx<Schema extends unknown = unknown> {
      */
     resolveWorktreePath(path: string): string;
     /**
-     * @param {TableRef} table
+     * @template {keyof Schema & string} K
+     * @overload
+     * @param {K} table
      * @param {OutputKey} key
-     * @returns {OutputRow}
+     * @returns {ResolveOutputRow<Schema, K>}
      */
-    output<Table extends StrictTableRef<Schema>>(table: Table, key: OutputKey$1): OutputForTable<Schema, Table>;
+    output<K extends keyof Schema & string>(table: K, key: OutputKey$1): ResolveOutputRow<Schema, K>;
     /**
-     * @param {TableRef} table
+     * @template {TableRef} T
+     * @overload
+     * @param {T} table
      * @param {OutputKey} key
-     * @returns {OutputRow | undefined}
+     * @returns {ResolveOutputRow<Schema, T>}
      */
-    outputMaybe<Table extends StrictTableRef<Schema>>(table: Table, key: OutputKey$1): OutputForTable<Schema, Table> | undefined;
+    output<T extends TableRef>(table: T, key: OutputKey$1): ResolveOutputRow<Schema, T>;
     /**
-     * @param {TableRef} table
+     * Resolve a single output row. Without an explicit `key.iteration` this
+     * resolves the CURRENT render iteration — which equals the loop iteration
+     * only for a single, non-nested loop, and is 0 when several loops coexist.
+     * For a `<Loop>` exit condition use {@link latest} (the most recent
+     * iteration), not `outputMaybe`, or an `until` built on it never advances.
+     *
+     * @template {keyof Schema & string} K
+     * @overload
+     * @param {K} table
+     * @param {OutputKey} key
+     * @returns {ResolveOutputRow<Schema, K> | undefined}
+     */
+    outputMaybe<K extends keyof Schema & string>(table: K, key: OutputKey$1): ResolveOutputRow<Schema, K> | undefined;
+    /**
+     * @template {TableRef} T
+     * @overload
+     * @param {T} table
+     * @param {OutputKey} key
+     * @returns {ResolveOutputRow<Schema, T> | undefined}
+     */
+    outputMaybe<T extends TableRef>(table: T, key: OutputKey$1): ResolveOutputRow<Schema, T> | undefined;
+    /**
+     * Resolve the most recent iteration's output row for `nodeId` (highest
+     * iteration across all matching rows). This is the correct reader for a
+     * `<Loop>`/`<Ralph>` `until` exit condition; {@link outputMaybe} resolves
+     * the current render iteration and can read stale/iteration-0 data inside a
+     * loop.
+     *
+     * @template {keyof Schema & string} K
+     * @overload
+     * @param {K} table
      * @param {string} nodeId
-     * @returns {OutputRow | undefined}
+     * @returns {ResolveOutputRow<Schema, K> | undefined}
+     */
+    latest<K extends keyof Schema & string>(table: K, nodeId: string): ResolveOutputRow<Schema, K> | undefined;
+    /**
+     * @template {TableRef} T
+     * @overload
+     * @param {T} table
+     * @param {string} nodeId
+     * @returns {ResolveOutputRow<Schema, T> | undefined}
      */
-    latest<Table extends StrictTableRef<Schema>>(table: Table, nodeId: string): OutputForTable<Schema, Table> | undefined;
+    latest<T extends TableRef>(table: T, nodeId: string): ResolveOutputRow<Schema, T> | undefined;
     /**
      * @param {unknown} value
      * @param {SafeParser} schema
@@ -262,6 +336,17 @@ declare class SmithersCtx<Schema extends unknown = unknown> {
      * @returns {string}
      */
     resolveTableName(table: TableRef): string;
+    /**
+     * Record that a task with `deps` deferred this render because its
+     * dependencies were not resolvable. Called by the Task component before it
+     * returns null. The engine inspects these at quiescence to turn a permanent
+     * deferral (a never-satisfiable dependency) into a loud error instead of a
+     * silent skip.
+     * @param {string} nodeId
+     * @param {string[]} waitingOn
+     * @returns {void}
+     */
+    recordDeferredDep(nodeId: string, waitingOn: string[]): void;
     /**
      * @param {TableRef} table
      * @param {OutputKey} key
@@ -275,8 +360,11 @@ type SmithersCtxOptions$1 = SmithersCtxOptions$2;
 type RunAuthContext$1 = RunAuthContext$2;
 type SmithersRuntimeConfig = SmithersRuntimeConfig$1;
 type TableRef = unknown;
-/** User-visible output row — harness metadata fields (runId, nodeId, iteration) are stripped. */
+/**
+ * User-visible output row — harness metadata fields (runId, nodeId, iteration) are stripped.
+ */
 type OutputRow = Record<string, unknown>;
+type ResolveOutputRow<Schema, T> = ResolveOutputRow$1<Schema, T>;
 type OutputAccessor$1<Schema> = OutputAccessor$2<Schema>;
 
 type WorkflowElement = {
@@ -355,11 +443,36 @@ declare class WorkflowDriver<Schema extends unknown = unknown> {
     /** @type {RunOptions | undefined} */
     activeOptions: RunOptions$1 | undefined;
     /** @type {import("@smithers-orchestrator/graph").WorkflowGraph | undefined} */
-    lastGraph: _smithers_graph.WorkflowGraph | undefined;
+    lastGraph: _smithers_orchestrator_graph.WorkflowGraph | undefined;
+    /** @type {{ nodeId: string; waitingOn: string[] }[]} Tasks that deferred on unresolved deps in the latest render. */
+    lastDeferredDeps: {
+        nodeId: string;
+        waitingOn: string[];
+    }[];
+    /** @type {Record<string, string>} */
+    worktreePathsById: Record<string, string>;
     /** @type {Map<string, string>} */
     outputTablesByNodeId: Map<string, string>;
     /** @type {OutputSnapshot} */
     baseOutputs: OutputSnapshot$1;
+    /** @type {Map<string, Promise<{ key: string; task: TaskDescriptor; kind: "completed" | "failed" | "cancelled"; output?: unknown; error?: unknown }>>} */
+    inflightTasks: Map<string, Promise<{
+        key: string;
+        task: TaskDescriptor;
+        kind: "completed" | "failed" | "cancelled";
+        output?: unknown;
+        error?: unknown;
+    }>>;
+    /** @type {Map<string, TaskDescriptor>} */
+    inflightTaskDescriptors: Map<string, TaskDescriptor>;
+    /** @type {Array<{ key: string; task: TaskDescriptor; kind: "completed" | "failed" | "cancelled"; output?: unknown; error?: unknown }>} */
+    settledTasks: Array<{
+        key: string;
+        task: TaskDescriptor;
+        kind: "completed" | "failed" | "cancelled";
+        output?: unknown;
+        error?: unknown;
+    }>;
     /**
    * @param {RunOptions} options
    * @returns {Promise<RunResult>}
@@ -382,6 +495,38 @@ declare class WorkflowDriver<Schema extends unknown = unknown> {
    */
     executeTasks(tasks: readonly TaskDescriptor[]): Promise<EngineDecision | RunResult$1>;
     /**
+   * Start a task without blocking the driver loop on its completion. Settled
+   * tasks queue in `settledTasks` and are reported to the session one at a
+   * time from `nextCompletionDecision`, so each decision is computed against
+   * fresh session state and a slow task never blocks scheduling work that
+   * became ready elsewhere in the graph (#267).
+   * @param {TaskDescriptor} task
+   * @param {{ runId: string; options: RunOptions; signal?: AbortSignal }} context
+   */
+    startInflightTask(task: TaskDescriptor, context: {
+        runId: string;
+        options: RunOptions$1;
+        signal?: AbortSignal;
+    }): void;
+    /**
+   * Wait for the next settled task (or an optional deadline) and report it to
+   * the session for a fresh decision. Completions that landed while a previous
+   * one was being processed drain from `settledTasks` first.
+   * @param {number | null} [deadlineMs]
+   * @returns {Promise<EngineDecision | RunResult>}
+   */
+    nextCompletionDecision(deadlineMs?: number | null): Promise<EngineDecision | RunResult$1>;
+    /**
+   * Await every in-flight task without reporting further decisions. Used
+   * before run-level exits (failure, continue-as-new) so task executors are
+   * not abandoned mid-write. This matches the pre-#267 barrier semantics:
+   * failure reporting waits for in-flight siblings (bounded by their
+   * timeouts), trading latency for the invariant that no executor writes
+   * after the run is terminal. Fail-fast would need a per-run abort threaded
+   * through executors.
+   */
+    drainInflight(): Promise<void>;
+    /**
    * @param {WaitReason} reason
    * @returns {Promise<EngineDecision | RunResult>}
    */
@@ -412,11 +557,11 @@ type SchedulerWaitHandler = SchedulerWaitHandler$1;
 type WaitHandler = WaitHandler$1;
 type ContinueAsNewHandler = ContinueAsNewHandler$1;
 type RunOptions$1 = RunOptions$2;
-type RunResult$1 = _smithers_scheduler.RunResult;
-type EngineDecision = _smithers_scheduler.EngineDecision;
-type RenderContext = _smithers_scheduler.RenderContext;
-type WaitReason = _smithers_scheduler.WaitReason;
-type TaskDescriptor = _smithers_graph_types.TaskDescriptor;
+type RunResult$1 = _smithers_orchestrator_scheduler.RunResult;
+type EngineDecision = _smithers_orchestrator_scheduler.EngineDecision;
+type RenderContext = _smithers_orchestrator_scheduler.RenderContext;
+type WaitReason = _smithers_orchestrator_scheduler.WaitReason;
+type TaskDescriptor = _smithers_orchestrator_graph_types.TaskDescriptor;
 
 type HotReloadOptions = HotReloadOptions$1;
 type OutputAccessor<Schema = any> = OutputAccessor$2<Schema>;