@loopingai/core 0.5.1 → 0.6.0

package/dist/host/agent.js

@@ -6,7 +6,7 @@ import { AgentDB, stateOf } from "../db/index.js";
 import { callerContext } from "../a2a/caller.js";
 import { createPushChannel } from "../a2a/push.js";
 import { buildAgentSession } from "../agent/session.js";
-import { createModelRuntime } from "../agent/model.js";
+import { workersAIModels } from "../agent/workers-ai/index.js";
 /**
  * The Durable Object body every Looping agent has, whatever loop it runs.
  *
@@ -59,6 +59,9 @@ export class LoopingAgent extends Agent {
      * `onStart` runs before any request, so it is not known when `agentPlugins()`
      * is built — which is why anything per-caller takes a thunk. The DO is keyed
      * 1:1 by this value, so it is constant once set.
+     *
+     * In-memory, and deliberately so — see {@link requireIdentityKey}, which does
+     * not depend on it surviving.
      */
     identityKey;
     /**
@@ -101,12 +104,34 @@ export class LoopingAgent extends Agent {
             stores: this.runtime.stores
         }));
     }
-    /** The model runtime for this instance, built lazily over the `AI` binding. */
+    /**
+     * Which provider this agent's loops run on. Defaults to Workers AI; override
+     * to run on something else.
+     *
+     * The seam is here rather than in `models` because `models` memoizes, and a
+     * subclass overriding a memoized getter has to remember to keep the caching —
+     * a trap that only shows up as a performance bug. This is called once.
+     *
+     * `ModelRuntime` is the whole contract: return anything satisfying it and
+     * every loop in core keeps working unchanged. Core ships two implementations,
+     * one directory each — {@link file://../agent/workers-ai/index.ts
+     * `agent/workers-ai`} (the default below) and `@loopingai/core/anthropic` —
+     * and a third provider is a third directory exporting one
+     * {@link file://../agent/model.ts ModelRuntimeFactory}, not a change to
+     * anything on this path.
+     *
+     * Takes the resolved {@link ModelConfig} rather than reading `this.config`, so
+     * that this signature matches
+     * {@link file://../round/subagent.ts RecipeSubagentHost.modelRuntime} — an
+     * agent and its facet **must** run the same provider, and identical seams are
+     * what let one factory serve both instead of two hand-copied bodies.
+     */
+    modelRuntime(model) {
+        return workersAIModels(this.env, model);
+    }
+    /** The model runtime for this instance, built lazily and memoized. */
     get models() {
-        return (this._models ??= createModelRuntime({
-            ai: this.env.AI,
-            config: this.config.model
-        }));
+        return (this._models ??= this.modelRuntime(this.config.model));
     }
     /**
      * What this agent's plugins are handed. Built from
@@ -193,12 +218,41 @@ export class LoopingAgent extends Agent {
             onMessagesDisplaced: this.runtime.onMessagesDisplaced
         }));
     }
-    /** The caller key, which is present on every path that can reach a plugin. */
+    /**
+     * The caller key, which is present on every path that can reach a plugin.
+     *
+     * ## Why this does not just read the field
+     *
+     * `identityKey` is set on the first turn and lives in the isolate. An isolate
+     * does not live as long as the work does: it can be evicted between two rounds
+     * of the same task, and it can be reset outright — "Durable Object connection
+     * closed because the object was reset" — while a Workflow step is mid-flight.
+     * The next call arrives on a fresh instance where the field is empty, and
+     * every per-caller thunk built off it throws.
+     *
+     * That failure is disproportionate to its cause. A plugin asking which caller
+     * it is serving gets an exception, mid-task, on an object whose entire purpose
+     * is to be that caller's — and because the throw happens inside a tool or a
+     * runtime resolution rather than at the edge, it surfaces as a failed branch
+     * rather than as anything an operator can read.
+     *
+     * So the object answers from itself. `define-agent` routes with
+     * `ns.get(ns.idFromName(identity.key))`, which means the caller key *is* this
+     * object's name and the platform hands it back on `ctx.id.name` — durable, free
+     * and correct by construction: an object cannot disagree with the name it was
+     * addressed by.
+     *
+     * The field still wins when it is set. `id.name` is undefined for an object
+     * addressed by `newUniqueId()` or a raw id string, so it is a fallback rather
+     * than the source of truth, and the throw is kept for the case where neither
+     * exists.
+     */
     requireIdentityKey() {
-        if (!this.identityKey) {
+        const key = this.identityKey ?? this.ctx.id.name;
+        if (!key) {
             throw new Error("identity.key is required for per-caller isolation");
         }
-        return this.identityKey;
+        return (this.identityKey = key);
     }
     /** The gateway callback channel for one turn. See {@link PushChannel}. */
     push(context) {

package/dist/index.d.ts

@@ -9,11 +9,11 @@
  * production bundle.
  */
 export { createAgentRuntime, RuntimeSetupError, buildRecipeTools, collectToolFamilies, type AgentRuntime, type CreateAgentRuntimeOptions } from "./runtime/index.js";
-export { PLUGIN_CONTRACT_VERSION, definePlugin, type AgentPlugin, type EmitProgress, type EnrichResultContext, type MainAgentToolContext, type PluginRequirements, type RecipeToolSet, type ResolveRuntimeContext, type ToolFamilyBuilder, type ToolFamilyContext, type TurnGateContext } from "./contract/plugin.js";
+export { PLUGIN_CONTRACT_VERSION, definePlugin, restrictMainAgentTools, type AgentPlugin, type RestrictMainAgentToolsOptions, type EmitProgress, type EnrichResultContext, type MainAgentToolContext, type PluginRequirements, type RecipeToolSet, type ResolveRuntimeContext, type ToolFamilyBuilder, type ToolFamilyContext, type TurnGateContext } from "./contract/plugin.js";
 export type { DelegationNames, RecipeLimits, ResolvedRecipe, SubtaskParams, SubtaskParamsSchema, SubtaskParamsShape, SubtaskTypeSpec, ValidatedRecipe } from "./contract/recipe.js";
 export { RecipeValidationError, resolveLimits, validateRecipe, type RecipePolicy } from "./contract/validation.js";
 export { ConfigError, DEFAULT_CORE_CONFIG, resolveConfig, type AgentLimits, type CoreConfig, type CoreConfigOverrides, type ModelConfig, type SessionConfig } from "./config.js";
 export { parseGatewayOrigins, type A2ASecretsEnv, type AiEnv, type CoreEnv } from "./env.js";
-export { CHUNK_SOFT_MS, MAX_CHUNKS_PER_BRANCH, STEP_TIMEOUT_MS, STEPS_PER_INSTANCE } from "./platform.js";
+export { CHUNK_SOFT_MS, MAX_CHUNKS_PER_BRANCH, MAX_TOOL_CALL_MS, STEP_TIMEOUT_MS, STEPS_PER_INSTANCE } from "./platform.js";
 export type { PluginStore } from "./db/db.js";
 export { makeWorkspaceHandle, memoryWorkspaceBacking, WorkspaceLimitError, WORKSPACE_MAX_FILES, WORKSPACE_MAX_FILE_BYTES, type WorkspaceBacking, type WorkspaceEntry, type WorkspaceHandle } from "./subagent/workspace.js";

package/dist/index.js

@@ -9,9 +9,9 @@
  * production bundle.
  */
 export { createAgentRuntime, RuntimeSetupError, buildRecipeTools, collectToolFamilies } from "./runtime/index.js";
-export { PLUGIN_CONTRACT_VERSION, definePlugin } from "./contract/plugin.js";
+export { PLUGIN_CONTRACT_VERSION, definePlugin, restrictMainAgentTools } from "./contract/plugin.js";
 export { RecipeValidationError, resolveLimits, validateRecipe } from "./contract/validation.js";
 export { ConfigError, DEFAULT_CORE_CONFIG, resolveConfig } from "./config.js";
 export { parseGatewayOrigins } from "./env.js";
-export { CHUNK_SOFT_MS, MAX_CHUNKS_PER_BRANCH, STEP_TIMEOUT_MS, STEPS_PER_INSTANCE } from "./platform.js";
+export { CHUNK_SOFT_MS, MAX_CHUNKS_PER_BRANCH, MAX_TOOL_CALL_MS, STEP_TIMEOUT_MS, STEPS_PER_INSTANCE } from "./platform.js";
 export { makeWorkspaceHandle, memoryWorkspaceBacking, WorkspaceLimitError, WORKSPACE_MAX_FILES, WORKSPACE_MAX_FILE_BYTES } from "./subagent/workspace.js";

package/dist/platform.d.ts

@@ -4,20 +4,38 @@
  * for those, and note that no Recipe can reach these. They change when the
  * platform changes, and for no other reason.
  *
- * The distinction is worth keeping sharp, because collapsing it is what produced
- * the bug this file was extracted during: a *turn count* was used to keep a step
- * under the step timeout, which only works if you can predict how long a turn
- * takes. You cannot. Time bounds time here; turns bound cost, over in `config.ts`.
+ * The distinction is worth keeping sharp, because collapsing it produces a
+ * specific bug: using a *turn count* to keep a step under the step timeout only
+ * works if you can predict how long a turn takes. You cannot. Time bounds time
+ * here; turns bound cost, over in `config.ts`.
  */
 /**
- * Platform fact: a `step.do(...)` callback is killed at ~10 minutes (Workflows'
- * default step timeout). {@link CHUNK_SOFT_MS} is sized against this.
+ * The step timeout **we configure**, passed as `WorkflowStepConfig.timeout` on
+ * every step that can hold a model call or a container command.
+ *
+ * This is the one value in this file that is **not** a platform fact, and
+ * treating it as one is the mistake to avoid: ten minutes is Workflows'
+ * *default* step timeout, not its ceiling, and a step that never passes a config
+ * inherits it silently. Sizing {@link CHUNK_SOFT_MS} against that inherited
+ * default is what once ran a production task as ten four-minute slices, one of
+ * which blew the ten minutes anyway and was retried whole.
+ *
+ * The genuine platform facts are narrower and do not bind us: wall-clock time per
+ * step is effectively unlimited, and a step is bounded by **CPU** time. Measured
+ * over a 59-minute task, the chunk steps used ~100 ms of CPU against 3,146 s of
+ * wall — this ceiling is nowhere near the real one.
+ *
+ * It is still a ceiling worth having, because it is what turns a hung container
+ * into a retry rather than a task that never ends. {@link CHUNK_SOFT_MS} is sized
+ * against it, and that relationship is asserted in `platform.spec.ts`.
  */
 export declare const STEP_TIMEOUT_MS: number;
 /**
- * Platform fact: a single Workflow instance may run ~10,000 steps (paid plan).
- * {@link MAX_CHUNKS_PER_BRANCH} is sized against this — see the worst-case
- * product asserted in `platform.spec.ts`.
+ * Platform fact: a single Workflow instance may run 10,000 steps by default on the
+ * paid plan. Cloudflare will raise it to 25,000 on request — worth knowing, and
+ * worth not relying on: {@link MAX_CHUNKS_PER_BRANCH} is sized against the default
+ * so nothing here needs an account-level exception to be correct. See the
+ * worst-case product asserted in `platform.spec.ts`.
  */
 export declare const STEPS_PER_INSTANCE = 10000;
 /**
@@ -28,8 +46,52 @@ export declare const STEPS_PER_INSTANCE = 10000;
  * This is the *only* thing keeping a step under the timeout. A subagent otherwise
  * runs until its turn or wall-clock budget is spent, however many turns that takes
  * — which is the point: the runner no longer guesses at turn duration.
+ *
+ * ## Why this is 15 minutes and not 4
+ *
+ * A chunk boundary is not free. It checkpoints, returns through two RPC hops,
+ * starts a fresh step, and re-hydrates the subagent — and for a coding agent it
+ * also means the container connection is re-established. Four minutes bought a
+ * boundary roughly every third tool call: a task that edited one README line spent
+ * 59 minutes across **ten** chunks, and the model was idle for most of each one,
+ * blocked on a single `sb_exec` running the project's test gate.
+ *
+ * ## Why it is not larger, which is the part that bit us
+ *
+ * This is a **soft** deadline, checked between turns (`stopWhen` in
+ * `subagent/run.ts`). A turn that starts one millisecond before it trips still runs
+ * to completion, so the real worst case is:
+ *
+ *     chunk wall  ≤  CHUNK_SOFT_MS + one whole turn
+ *
+ * and one turn is a model call plus a tool call. The old pair ignored that: four
+ * minutes soft under a ten-minute timeout looked like six minutes of headroom, but
+ * a single `sb_exec` may run for {@link MAX_TOOL_CALL_MS}, so a turn could add ten.
+ * That is not a hypothetical — it is the `WorkflowTimeoutError` that cost a
+ * production task ten minutes and a full chunk replay.
+ *
+ * So the headroom is sized against a whole turn, not against a guess:
+ * `STEP_TIMEOUT_MS - CHUNK_SOFT_MS` is 15 minutes, covering
+ * {@link MAX_TOOL_CALL_MS} of tool call plus five minutes for the model call and
+ * its provider retries. Asserted in `platform.spec.ts` — raise the step timeout
+ * before raising this.
  */
 export declare const CHUNK_SOFT_MS: number;
+/**
+ * The longest a **single tool call** may run, and a contract rather than a
+ * mechanism: core has no way to enforce it, because core installs no tools.
+ *
+ * It exists because {@link CHUNK_SOFT_MS} cannot be reasoned about without it. The
+ * soft deadline is checked between turns, so a host that lets one tool block for
+ * longer than the headroom under {@link STEP_TIMEOUT_MS} reintroduces exactly the
+ * step-timeout kill this pair is sized to prevent — and it reintroduces it
+ * invisibly, in a plugin, a long way from this file.
+ *
+ * A host installing a tool that can block (a shell, a container command, a fetch
+ * with no ceiling of its own) must bound it at or below this. See the `timeoutMs`
+ * passed to `@loopingai/plugins/computer` in looping-starter.
+ */
+export declare const MAX_TOOL_CALL_MS: number;
 /**
  * Hard ceiling on durable chunk steps for one Subtask branch. A backstop, not a
  * budget: the Workflow *fails* a branch that reaches it, so reaching it is a bug.
@@ -39,8 +101,9 @@ export declare const CHUNK_SOFT_MS: number;
  * 1. It exceeds every Recipe's `maxTurns`. A chunk that yields always advanced at
  *    least one turn, so a run takes at most `maxTurns` chunks however short they
  *    are — and they do get short, because `CHUNK_SOFT_MS` and progress events both
- *    end one early. That bound survives both; a nominal `maxTurns / turnsPerChunk`
- *    estimate survived neither, which is why no such estimate exists any more.
+ *    end one early. Counting turns is what makes the bound survive that; any
+ *    estimate of turns-per-chunk would not, since neither of those two is
+ *    predictable.
  * 2. The worst-case step product stays under {@link STEPS_PER_INSTANCE}.
  */
 export declare const MAX_CHUNKS_PER_BRANCH = 40;

package/dist/platform.js

@@ -4,20 +4,38 @@
  * for those, and note that no Recipe can reach these. They change when the
  * platform changes, and for no other reason.
  *
- * The distinction is worth keeping sharp, because collapsing it is what produced
- * the bug this file was extracted during: a *turn count* was used to keep a step
- * under the step timeout, which only works if you can predict how long a turn
- * takes. You cannot. Time bounds time here; turns bound cost, over in `config.ts`.
+ * The distinction is worth keeping sharp, because collapsing it produces a
+ * specific bug: using a *turn count* to keep a step under the step timeout only
+ * works if you can predict how long a turn takes. You cannot. Time bounds time
+ * here; turns bound cost, over in `config.ts`.
  */
 /**
- * Platform fact: a `step.do(...)` callback is killed at ~10 minutes (Workflows'
- * default step timeout). {@link CHUNK_SOFT_MS} is sized against this.
+ * The step timeout **we configure**, passed as `WorkflowStepConfig.timeout` on
+ * every step that can hold a model call or a container command.
+ *
+ * This is the one value in this file that is **not** a platform fact, and
+ * treating it as one is the mistake to avoid: ten minutes is Workflows'
+ * *default* step timeout, not its ceiling, and a step that never passes a config
+ * inherits it silently. Sizing {@link CHUNK_SOFT_MS} against that inherited
+ * default is what once ran a production task as ten four-minute slices, one of
+ * which blew the ten minutes anyway and was retried whole.
+ *
+ * The genuine platform facts are narrower and do not bind us: wall-clock time per
+ * step is effectively unlimited, and a step is bounded by **CPU** time. Measured
+ * over a 59-minute task, the chunk steps used ~100 ms of CPU against 3,146 s of
+ * wall — this ceiling is nowhere near the real one.
+ *
+ * It is still a ceiling worth having, because it is what turns a hung container
+ * into a retry rather than a task that never ends. {@link CHUNK_SOFT_MS} is sized
+ * against it, and that relationship is asserted in `platform.spec.ts`.
  */
-export const STEP_TIMEOUT_MS = 10 * 60_000;
+export const STEP_TIMEOUT_MS = 30 * 60_000;
 /**
- * Platform fact: a single Workflow instance may run ~10,000 steps (paid plan).
- * {@link MAX_CHUNKS_PER_BRANCH} is sized against this — see the worst-case
- * product asserted in `platform.spec.ts`.
+ * Platform fact: a single Workflow instance may run 10,000 steps by default on the
+ * paid plan. Cloudflare will raise it to 25,000 on request — worth knowing, and
+ * worth not relying on: {@link MAX_CHUNKS_PER_BRANCH} is sized against the default
+ * so nothing here needs an account-level exception to be correct. See the
+ * worst-case product asserted in `platform.spec.ts`.
  */
 export const STEPS_PER_INSTANCE = 10_000;
 /**
@@ -28,8 +46,52 @@ export const STEPS_PER_INSTANCE = 10_000;
  * This is the *only* thing keeping a step under the timeout. A subagent otherwise
  * runs until its turn or wall-clock budget is spent, however many turns that takes
  * — which is the point: the runner no longer guesses at turn duration.
+ *
+ * ## Why this is 15 minutes and not 4
+ *
+ * A chunk boundary is not free. It checkpoints, returns through two RPC hops,
+ * starts a fresh step, and re-hydrates the subagent — and for a coding agent it
+ * also means the container connection is re-established. Four minutes bought a
+ * boundary roughly every third tool call: a task that edited one README line spent
+ * 59 minutes across **ten** chunks, and the model was idle for most of each one,
+ * blocked on a single `sb_exec` running the project's test gate.
+ *
+ * ## Why it is not larger, which is the part that bit us
+ *
+ * This is a **soft** deadline, checked between turns (`stopWhen` in
+ * `subagent/run.ts`). A turn that starts one millisecond before it trips still runs
+ * to completion, so the real worst case is:
+ *
+ *     chunk wall  ≤  CHUNK_SOFT_MS + one whole turn
+ *
+ * and one turn is a model call plus a tool call. The old pair ignored that: four
+ * minutes soft under a ten-minute timeout looked like six minutes of headroom, but
+ * a single `sb_exec` may run for {@link MAX_TOOL_CALL_MS}, so a turn could add ten.
+ * That is not a hypothetical — it is the `WorkflowTimeoutError` that cost a
+ * production task ten minutes and a full chunk replay.
+ *
+ * So the headroom is sized against a whole turn, not against a guess:
+ * `STEP_TIMEOUT_MS - CHUNK_SOFT_MS` is 15 minutes, covering
+ * {@link MAX_TOOL_CALL_MS} of tool call plus five minutes for the model call and
+ * its provider retries. Asserted in `platform.spec.ts` — raise the step timeout
+ * before raising this.
+ */
+export const CHUNK_SOFT_MS = 15 * 60_000;
+/**
+ * The longest a **single tool call** may run, and a contract rather than a
+ * mechanism: core has no way to enforce it, because core installs no tools.
+ *
+ * It exists because {@link CHUNK_SOFT_MS} cannot be reasoned about without it. The
+ * soft deadline is checked between turns, so a host that lets one tool block for
+ * longer than the headroom under {@link STEP_TIMEOUT_MS} reintroduces exactly the
+ * step-timeout kill this pair is sized to prevent — and it reintroduces it
+ * invisibly, in a plugin, a long way from this file.
+ *
+ * A host installing a tool that can block (a shell, a container command, a fetch
+ * with no ceiling of its own) must bound it at or below this. See the `timeoutMs`
+ * passed to `@loopingai/plugins/computer` in looping-starter.
  */
-export const CHUNK_SOFT_MS = 4 * 60_000;
+export const MAX_TOOL_CALL_MS = 10 * 60_000;
 /**
  * Hard ceiling on durable chunk steps for one Subtask branch. A backstop, not a
  * budget: the Workflow *fails* a branch that reaches it, so reaching it is a bug.
@@ -39,8 +101,9 @@ export const CHUNK_SOFT_MS = 4 * 60_000;
  * 1. It exceeds every Recipe's `maxTurns`. A chunk that yields always advanced at
  *    least one turn, so a run takes at most `maxTurns` chunks however short they
  *    are — and they do get short, because `CHUNK_SOFT_MS` and progress events both
- *    end one early. That bound survives both; a nominal `maxTurns / turnsPerChunk`
- *    estimate survived neither, which is why no such estimate exists any more.
+ *    end one early. Counting turns is what makes the bound survive that; any
+ *    estimate of turns-per-chunk would not, since neither of those two is
+ *    predictable.
  * 2. The worst-case step product stays under {@link STEPS_PER_INSTANCE}.
  */
 export const MAX_CHUNKS_PER_BRANCH = 40;

package/dist/round/agent.d.ts

@@ -7,14 +7,13 @@ import type { SubagentClass } from "./subagent.js";
 import type { RoundPolicy } from "./policy.js";
 import { type RoundMode } from "./turn.js";
 /**
- * A **delegating** agent: the round loop, the durable Subtask DAG, and the
- * isolated subagent execution beneath it.
+ * A **delegating** agent: the round loop, the durable Subtasks it hands out, and
+ * the isolated subagent execution beneath them.
  *
  * Everything {@link LoopingAgent} gives every agent, plus the half that only a
  * delegating one needs — and it is all mechanism. A Workflow drives it through
- * native Cloudflare RPC (`runTaskTurn`, `skipBlockedSubtasks`,
- * `executeSubtaskChunk`, …), never HTTP: the DO is a private implementation
- * detail of the Worker.
+ * native Cloudflare RPC (`runTaskTurn`, `scanSubtasks`, `executeSubtaskChunk`,
+ * …), never HTTP: the DO is a private implementation detail of the Worker.
  *
  * ## Why core owns this
  *
@@ -73,8 +72,8 @@ export declare abstract class RoundAgentBase<TEnv extends Cloudflare.Env & AiEnv
     /** Age out this agent's subtask rows alongside the task rows. */
     protected cleanupAgentState(): void;
     /**
-     * One main-agent round: answer the user, or delegate a durable Subtask DAG and
-     * return the acknowledgment the user sees while it runs.
+     * One main-agent round: answer the user, or delegate a durable set of Subtasks
+     * and return the acknowledgment the user sees while it runs.
      *
      * This is the RPC boundary, so it is where the round's cost becomes a field. The
      * budget is created here, handed to {@link decideRound} to be spent, and read
@@ -120,29 +119,33 @@ export declare abstract class RoundAgentBase<TEnv extends Cloudflare.Env & AiEnv
      * Every round's branches for a Task, in stable ordinal order — what a round
      * needs to reunite each earlier `delegate` call with its result. Built inside
      * the DO and consumed here, so the 1 MiB Workflow-step cap that keeps
-     * {@link SubtaskNode} narrow does not apply.
+     * {@link SubtaskScan} down to ids does not apply.
      */
     private compositionBranches;
     /** A Task's Subtasks, every round, in stable ordinal order. */
     listSubtasks(taskId: string): Promise<Subtask[]>;
     /**
-     * The Workflow's per-wave scan for **one round's** DAG: report a cancellation,
-     * or skip every pending Subtask blocked by a dependency that did not succeed and
-     * return the refreshed DAG as scheduler {@link SubtaskNode}s.
+     * The Workflow's scan for **one round's** Subtasks: report a cancellation, or
+     * return the ids that still owe an outcome, in ordinal order.
      *
-     * Scoped to the round because dependency edges never cross one: an earlier
-     * round's rows are already terminal and irrelevant to this wave, and including
-     * them would only widen a projection that has a size cap.
+     * Scoped to the round because the Workflow drives one round at a time: an
+     * earlier round's rows are already terminal and would only widen a projection
+     * that has a size cap.
      *
-     * Skipping runs to a fixpoint because it propagates: a node skipped for a
-     * failed prerequisite blocks *its* dependents in turn. Bounded by the
-     * per-round maximum. Independent branches are untouched — one branch's failure
-     * never stops work that does not depend on it.
+     * `running` counts alongside `pending` on purpose. `executeSubtaskChunk`
+     * accepts a row that is either: the latter is its ambiguous-retry path, where a
+     * previous attempt crashed mid-execution and the managed child's fingerprint
+     * cache may still hold the terminal result that makes the retry free. So a row
+     * stranded `running` is re-runnable, and omitting it here would abandon it.
+     *
+     * Ordinal order comes from {@link listRound} and is not incidental: these ids
+     * become durable Workflow step names, so the traversal that produces them has
+     * to be deterministic.
      *
      * The cancellation verdict rides along rather than being probed separately, so
-     * a wave costs one round trip and cannot act on a stale answer.
+     * the scan costs one round trip and cannot act on a stale answer.
      */
-    skipBlockedSubtasks(taskId: string, round: number): Promise<SubtaskScan>;
+    scanSubtasks(taskId: string, round: number): Promise<SubtaskScan>;
     /** Parent cancellation: cancel every still-pending Subtask. Returns the count. */
     cancelPendingSubtasks(taskId: string): Promise<number>;
     /**
@@ -182,8 +185,9 @@ export declare abstract class RoundAgentBase<TEnv extends Cloudflare.Env & AiEnv
      *   delete; that now happens strictly later.
      *
      * Throws on a transient fault (the step retries and the child resumes from its
-     * checkpoint) and on scheduler-invariant violations — both are bugs, not
-     * outcomes.
+     * checkpoint) and when the row is in a status this cannot accept — a subtask
+     * that is neither `pending` nor `running` nor already terminal. Both are bugs,
+     * not outcomes.
      */
     executeSubtaskChunk(id: SubtaskId, chunk: number, push?: TurnPushContext): Promise<SubtaskChunkOutcome>;
     /**
@@ -230,14 +234,6 @@ export declare abstract class RoundAgentBase<TEnv extends Cloudflare.Env & AiEnv
     private abortChildQuietly;
     /** Persist a child's terminal outcome. Returns whether the guarded write applied. */
     private persistResult;
-    /**
-     * Load a Subtask's dependency results, in ordinal order.
-     *
-     * Order is semantic: it feeds the child's request fingerprint, so a retry must
-     * build the identical array or the cache misses. A dependency that has not
-     * completed means the scheduler ran this node too early.
-     */
-    private loadDependencyResults;
     /** Re-read a Subtask that must exist (it was just written). */
     private requireSubtask;
     /** Delete a managed child, swallowing failures (used on best-effort sweeps). */
@@ -248,7 +244,7 @@ export declare abstract class RoundAgentBase<TEnv extends Cloudflare.Env & AiEnv
      * Interrupt a canceled Task's live children: each `running` Subtask's managed
      * child gets `abortRun`, so a long recipe stops at its current model call
      * instead of at the next chunk boundary (up to `chunkSoftMs` later). A subtask
-     * that already finished (e.g. one branch of a wave completed while another was
+     * that already finished (e.g. one branch completed while another was
      * still running) is deliberately retained until the terminal-delivery sweep —
      * but a canceled Task never reaches delivery, so its idle child is deleted
      * here instead, or it would leak until the 30-day row cleanup regardless of
@@ -261,6 +257,15 @@ export declare abstract class RoundAgentBase<TEnv extends Cloudflare.Env & AiEnv
      * status. Bounded by `maxSubtasks`. Best-effort throughout: a child that
      * cannot be reached is logged, never fatal — cancellation must not fail
      * because cleanup did.
+     *
+     * The `pending` rows are transitioned here too, and that is not bookkeeping:
+     * it is the only thing that resolves them. Nothing else is coming back to a
+     * pending row once a Task is canceled — the Workflow's scheduler runs a
+     * single pass and does not re-scan, and `prepareChunk` reports a canceled
+     * Task's pending row as terminal *without* claiming it, so a branch whose RPC
+     * had not yet reached the claim when the cancellation landed simply returns.
+     * Left to the loop below, which only deletes the child, the row would sit
+     * non-terminal until the 30-day cleanup.
      */
     protected onTaskCanceled(taskId: string): Promise<void>;
 }