taskflow-core 0.2.1 → 0.2.3

package/dist/schema.d.ts

@@ -5,6 +5,9 @@
  * to a subagent (an isolated `pi` process). Phases form a DAG via `dependsOn`.
  */
 import { Type, type Static } from "typebox";
+/** Hard cap on subagent calls made by one tree-reduce phase. This bounds
+ * author mistakes even when no run budget was declared. */
+export declare const TREE_REDUCE_HARD_MAX_CALLS = 256;
 /** Closed set of native phase kinds — single source of truth for DSL + FlowIR. */
 export declare const PHASE_TYPES: readonly ["agent", "parallel", "map", "gate", "reduce", "approval", "flow", "loop", "tournament", "script", 
 /** First completed branch wins (Horizon B). */
@@ -12,6 +15,9 @@ export declare const PHASE_TYPES: readonly ["agent", "parallel", "map", "gate",
 /** Dynamic sub-DAG: nested sub-flow or graft-promote into parent (Horizon B). */
 "expand"];
 export type PhaseType = (typeof PHASE_TYPES)[number];
+/** Phase kinds that execute one or more subagents and therefore require an
+ * effective idle watchdog (or a finite wall timeout when the watchdog is off). */
+export declare const AGENT_RUNNING_PHASE_TYPES: readonly ["agent", "gate", "reduce", "map", "parallel", "loop", "tournament", "race"];
 /** Loop iteration bounds. Authors may lower the max; the hard cap is a runaway guard. */
 export declare const LOOP_DEFAULT_MAX_ITERATIONS = 10;
 export declare const LOOP_HARD_MAX_ITERATIONS = 100;
@@ -40,6 +46,7 @@ export type CacheScope = (typeof CACHE_SCOPES)[number];
 declare const ParallelTaskSchema: Type.TObject<{
     task: Type.TString;
     agent: Type.TOptional<Type.TString>;
+    cwd: Type.TOptional<Type.TString>;
 }>;
 /** Declarative retry policy for a phase's subagent call(s). */
 declare const RetrySchema: Type.TObject<{
@@ -72,6 +79,7 @@ declare const PhaseSchema: Type.TObject<{
     branches: Type.TOptional<Type.TArray<Type.TObject<{
         task: Type.TString;
         agent: Type.TOptional<Type.TString>;
+        cwd: Type.TOptional<Type.TString>;
     }>>>;
     /**
      * [race] When true (default), abort in-flight loser branches after the first branch
@@ -80,6 +88,21 @@ declare const PhaseSchema: Type.TObject<{
      */
     cancelLosers: Type.TOptional<Type.TBoolean>;
     from: Type.TOptional<Type.TArray<Type.TString>>;
+    /**
+     * [reduce] How the aggregated `from[]` inputs are reduced. `'one-shot'`
+     * (default) feeds all inputs to a single reducer call as `{previous.output}`.
+     * `'tree'` batches the inputs (see `batchSize`) and runs intermediate
+     * reducer calls over each batch, then reduces the round outputs until one
+     * remains — useful when the aggregated input would exceed a single prompt.
+     * Tree reduction uses the SAME agent/model/options/timeout/idleTimeout as
+     * the phase and forces the imperative runtime (the event kernel falls back).
+     * The corrected `{previous.output}` aggregation (all `from[]` sources) always
+     * applies regardless of strategy.
+     */
+    reduceStrategy: Type.TOptional<Type.TUnsafe<"one-shot" | "tree">>;
+    /** [reduce] With `reduceStrategy:'tree'`, the max number of aggregated inputs
+     *  fed to each intermediate reducer call (>= 2). Ignored for one-shot. */
+    batchSize: Type.TOptional<Type.TInteger>;
     use: Type.TOptional<Type.TString>;
     /** [expand] Fragment source — string interpolation or inline Taskflow / phases (same as flow.def). */
     def: Type.TOptional<Type.TUnknown>;
@@ -91,6 +114,14 @@ declare const PhaseSchema: Type.TObject<{
     run: Type.TOptional<Type.TUnion<[Type.TString, Type.TArray<Type.TString>]>>;
     input: Type.TOptional<Type.TString>;
     timeout: Type.TOptional<Type.TNumber>;
+    /**
+     * Idle watchdog override (ms) for agent-running phases. A positive value (>= 1000)
+     * replaces the host default (300000ms): if a subagent produces no output for this
+     * long it is killed as stalled. `0` DISABLES the watchdog — but then a finite
+     * wall `timeout` (>= 1000) is REQUIRED on this phase so it can never hang forever.
+     * Overrides the flow-level `idleTimeout`. Absent → flow-level or host default.
+     */
+    idleTimeout: Type.TOptional<Type.TNumber>;
     until: Type.TOptional<Type.TString>;
     maxIterations: Type.TOptional<Type.TNumber>;
     convergence: Type.TOptional<Type.TBoolean>;
@@ -210,6 +241,14 @@ export declare const TaskflowSchema: Type.TObject<{
     strictInterpolation: Type.TOptional<Type.TBoolean>;
     contextSharing: Type.TOptional<Type.TBoolean>;
     incremental: Type.TOptional<Type.TBoolean>;
+    /**
+     * Flow-level idle watchdog (ms) for all agent-running phases that don't set
+     * their own `idleTimeout`. Positive (>= 1000) overrides the host default
+     * (300000ms); `0` disables the watchdog for those phases — but then every
+     * agent-running phase MUST declare a finite wall `timeout` (>= 1000) so the
+     * flow can never hang forever. A per-phase `idleTimeout` overrides this.
+     */
+    idleTimeout: Type.TOptional<Type.TNumber>;
     phases: Type.TArray<Type.TObject<{
         id: Type.TString;
         type: Type.TOptional<Type.TUnsafe<"agent" | "approval" | "expand" | "flow" | "gate" | "loop" | "map" | "parallel" | "race" | "reduce" | "script" | "tournament">>;
@@ -220,6 +259,7 @@ export declare const TaskflowSchema: Type.TObject<{
         branches: Type.TOptional<Type.TArray<Type.TObject<{
             task: Type.TString;
             agent: Type.TOptional<Type.TString>;
+            cwd: Type.TOptional<Type.TString>;
         }>>>;
         /**
          * [race] When true (default), abort in-flight loser branches after the first branch
@@ -228,6 +268,21 @@ export declare const TaskflowSchema: Type.TObject<{
          */
         cancelLosers: Type.TOptional<Type.TBoolean>;
         from: Type.TOptional<Type.TArray<Type.TString>>;
+        /**
+         * [reduce] How the aggregated `from[]` inputs are reduced. `'one-shot'`
+         * (default) feeds all inputs to a single reducer call as `{previous.output}`.
+         * `'tree'` batches the inputs (see `batchSize`) and runs intermediate
+         * reducer calls over each batch, then reduces the round outputs until one
+         * remains — useful when the aggregated input would exceed a single prompt.
+         * Tree reduction uses the SAME agent/model/options/timeout/idleTimeout as
+         * the phase and forces the imperative runtime (the event kernel falls back).
+         * The corrected `{previous.output}` aggregation (all `from[]` sources) always
+         * applies regardless of strategy.
+         */
+        reduceStrategy: Type.TOptional<Type.TUnsafe<"one-shot" | "tree">>;
+        /** [reduce] With `reduceStrategy:'tree'`, the max number of aggregated inputs
+         *  fed to each intermediate reducer call (>= 2). Ignored for one-shot. */
+        batchSize: Type.TOptional<Type.TInteger>;
         use: Type.TOptional<Type.TString>;
         /** [expand] Fragment source — string interpolation or inline Taskflow / phases (same as flow.def). */
         def: Type.TOptional<Type.TUnknown>;
@@ -239,6 +294,14 @@ export declare const TaskflowSchema: Type.TObject<{
         run: Type.TOptional<Type.TUnion<[Type.TString, Type.TArray<Type.TString>]>>;
         input: Type.TOptional<Type.TString>;
         timeout: Type.TOptional<Type.TNumber>;
+        /**
+         * Idle watchdog override (ms) for agent-running phases. A positive value (>= 1000)
+         * replaces the host default (300000ms): if a subagent produces no output for this
+         * long it is killed as stalled. `0` DISABLES the watchdog — but then a finite
+         * wall `timeout` (>= 1000) is REQUIRED on this phase so it can never hang forever.
+         * Overrides the flow-level `idleTimeout`. Absent → flow-level or host default.
+         */
+        idleTimeout: Type.TOptional<Type.TNumber>;
         until: Type.TOptional<Type.TString>;
         maxIterations: Type.TOptional<Type.TNumber>;
         convergence: Type.TOptional<Type.TBoolean>;
@@ -292,6 +355,10 @@ export interface ShorthandStep {
     context?: string[];
     /** Max characters per context file (pass-through to Phase.contextLimit). */
     contextLimit?: number;
+    /** Working directory for this step's subagent (pass-through to Phase.cwd).
+     *  A literal path or a reserved workspace keyword ('temp'/'dedicated'/
+     *  'worktree'). A top-level `cwd` is the default; a step cwd overrides it. */
+    cwd?: string;
 }
 /** True when `def` is a shorthand spec (no `phases`, but a task/tasks/chain field). */
 export declare function isShorthand(def: unknown): boolean;

package/dist/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}

package/dist/schema.js

@@ -11,9 +11,13 @@ import { scorerShapeErrors } from "./scorers.js";
 import { Type } from "typebox";
 import { Errors as SchemaErrors } from "typebox/value";
 import { cwdArgName, hasCwdPlaceholder, normalizeRelativePath } from "./cwd-bridge.js";
+import { WORKSPACE_KEYWORDS } from "./workspace.js";
 // ---------------------------------------------------------------------------
 // Phase types
 // ---------------------------------------------------------------------------
+/** Hard cap on subagent calls made by one tree-reduce phase. This bounds
+ * author mistakes even when no run budget was declared. */
+export const TREE_REDUCE_HARD_MAX_CALLS = 256;
 /** Closed set of native phase kinds — single source of truth for DSL + FlowIR. */
 export const PHASE_TYPES = [
     "agent",
@@ -31,6 +35,18 @@ export const PHASE_TYPES = [
     /** Dynamic sub-DAG: nested sub-flow or graft-promote into parent (Horizon B). */
     "expand",
 ];
+/** Phase kinds that execute one or more subagents and therefore require an
+ * effective idle watchdog (or a finite wall timeout when the watchdog is off). */
+export const AGENT_RUNNING_PHASE_TYPES = [
+    "agent",
+    "gate",
+    "reduce",
+    "map",
+    "parallel",
+    "loop",
+    "tournament",
+    "race",
+];
 /** Loop iteration bounds. Authors may lower the max; the hard cap is a runaway guard. */
 export const LOOP_DEFAULT_MAX_ITERATIONS = 10;
 export const LOOP_HARD_MAX_ITERATIONS = 100;
@@ -61,6 +77,9 @@ const CACHE_CROSS_RUN_BLOCKED_TYPES = ["gate", "approval", "loop", "tournament",
 const ParallelTaskSchema = Type.Object({
     task: Type.String({ description: "Task for this parallel branch (supports interpolation)" }),
     agent: Type.Optional(Type.String({ description: "Override the phase agent for this branch" })),
+    cwd: Type.Optional(Type.String({
+        description: "Working directory for this parallel branch's subagent (a literal path). Overrides the phase-level cwd for this branch only. Reserved workspace keywords ('temp'/'dedicated'/'worktree') are NOT supported per-branch (the workspace lifecycle is per-phase) — use the phase-level cwd for those.",
+    })),
 }, { additionalProperties: false });
 /** Declarative retry policy for a phase's subagent call(s). */
 const RetrySchema = Type.Object({
@@ -110,6 +129,24 @@ const PhaseSchema = Type.Object({
     cancelLosers: Type.Optional(Type.Boolean({ default: true })),
     // reduce
     from: Type.Optional(Type.Array(Type.String(), { description: "[reduce] Phase ids whose outputs are aggregated" })),
+    /**
+     * [reduce] How the aggregated `from[]` inputs are reduced. `'one-shot'`
+     * (default) feeds all inputs to a single reducer call as `{previous.output}`.
+     * `'tree'` batches the inputs (see `batchSize`) and runs intermediate
+     * reducer calls over each batch, then reduces the round outputs until one
+     * remains — useful when the aggregated input would exceed a single prompt.
+     * Tree reduction uses the SAME agent/model/options/timeout/idleTimeout as
+     * the phase and forces the imperative runtime (the event kernel falls back).
+     * The corrected `{previous.output}` aggregation (all `from[]` sources) always
+     * applies regardless of strategy.
+     */
+    reduceStrategy: Type.Optional(StringEnum(["one-shot", "tree"], {
+        description: "[reduce] 'one-shot' (default) = single reducer call; 'tree' = batched intermediate rounds (see batchSize). Forces imperative runtime.",
+        default: "one-shot",
+    })),
+    /** [reduce] With `reduceStrategy:'tree'`, the max number of aggregated inputs
+     *  fed to each intermediate reducer call (>= 2). Ignored for one-shot. */
+    batchSize: Type.Optional(Type.Integer({ minimum: 2, description: "[reduce] Batch size for reduceStrategy:'tree' (integer >= 2). Ignored for one-shot." })),
     // sub-workflow (flow) + expand fragment
     use: Type.Optional(Type.String({ description: "[flow] Name of a saved taskflow to run as this phase" })),
     /** [expand] Fragment source — string interpolation or inline Taskflow / phases (same as flow.def). */
@@ -137,6 +174,16 @@ const PhaseSchema = Type.Object({
     timeout: Type.Optional(Type.Number({
         description: "Max execution time in milliseconds. For script phases: caps the shell command (default 60000, max 300000). For agent-running phases (agent/gate/reduce/map/parallel/loop/tournament): caps EACH subagent call — on expiry the subagent is aborted and the phase fails with a 'timedOut' marker (never retried). Not supported for approval/flow phases. Must be >= 1000.",
     })),
+    /**
+     * Idle watchdog override (ms) for agent-running phases. A positive value (>= 1000)
+     * replaces the host default (300000ms): if a subagent produces no output for this
+     * long it is killed as stalled. `0` DISABLES the watchdog — but then a finite
+     * wall `timeout` (>= 1000) is REQUIRED on this phase so it can never hang forever.
+     * Overrides the flow-level `idleTimeout`. Absent → flow-level or host default.
+     */
+    idleTimeout: Type.Optional(Type.Number({
+        description: "[agent-running] Idle watchdog in ms (>= 1000, or 0 to disable). 0 requires a finite wall 'timeout' >= 1000. Overrides the flow-level idleTimeout.",
+    })),
     // loop-until-done
     until: Type.Optional(Type.String({
         description: "[loop] Stop condition evaluated after each iteration. The iteration's output is exposed as {steps.<thisId>.output}/.json. Supports the same operators as `when`. The loop stops when this is truthy, on convergence, or at maxIterations. A parse error stops the loop (fail-safe).",
@@ -279,6 +326,16 @@ export const TaskflowSchema = Type.Object({
     incremental: Type.Optional(Type.Boolean({
         description: "Default every phase to cross-run caching (scope:'cross-run') so re-running this flow reuses unchanged phases across runs/sessions. Equivalent to setting cache:{scope:'cross-run'} on every phase; per-phase cache settings and the cross-run-blocked types (gate/approval/loop/tournament) still take precedence. Default false (run-only — each run starts fresh unless a phase opts in). A run-time `incremental` argument overrides this.",
     })),
+    /**
+     * Flow-level idle watchdog (ms) for all agent-running phases that don't set
+     * their own `idleTimeout`. Positive (>= 1000) overrides the host default
+     * (300000ms); `0` disables the watchdog for those phases — but then every
+     * agent-running phase MUST declare a finite wall `timeout` (>= 1000) so the
+     * flow can never hang forever. A per-phase `idleTimeout` overrides this.
+     */
+    idleTimeout: Type.Optional(Type.Number({
+        description: "Flow-level idle watchdog in ms (>= 1000, or 0 to disable). Per-phase idleTimeout overrides. 0 requires every agent-running phase to declare a finite wall 'timeout' >= 1000.",
+    })),
     phases: Type.Array(PhaseSchema, { minItems: 1, description: "Ordered phase definitions (DAG via dependsOn)" }),
 }, { additionalProperties: false });
 /** True when `def` is a shorthand spec (no `phases`, but a task/tasks/chain field). */
@@ -310,6 +367,8 @@ function readStep(s) {
             step.context = ctx;
         if (typeof o.contextLimit === "number")
             step.contextLimit = o.contextLimit;
+        if (typeof o.cwd === "string")
+            step.cwd = o.cwd;
         return step;
     }
     return { task: "" };
@@ -336,6 +395,13 @@ export function desugar(def) {
         meta.budget = d.budget;
     if (typeof d.strictInterpolation === "boolean")
         meta.strictInterpolation = d.strictInterpolation;
+    /** Top-level shorthand cwd (literal path or workspace keyword). Becomes the
+     *  default for every step; a per-step cwd overrides it. For single/chain it
+     *  lands on each Phase.cwd (full workspace lifecycle). For parallel it lands
+     *  on the phase cwd (shared), with per-branch cwds overriding per-branch.
+     *  Note: `cwd` is a Phase field, NOT a Taskflow field, so it is distributed
+     *  to each phase below rather than placed on the Taskflow object. */
+    const topCwd = typeof d.cwd === "string" && d.cwd.trim() ? d.cwd : undefined;
     const nameOf = (fallback) => (typeof d.name === "string" && d.name.trim() ? d.name.trim() : fallback);
     // chain → sequential agent phases
     if (Array.isArray(d.chain) && d.chain.length > 0) {
@@ -353,6 +419,9 @@ export function desugar(def) {
                 phase.context = s.context;
             if (s.contextLimit !== undefined)
                 phase.contextLimit = s.contextLimit;
+            const stepCwd = s.cwd ?? topCwd;
+            if (stepCwd)
+                phase.cwd = stepCwd;
             if (i > 0)
                 phase.dependsOn = [`step${i}`];
             if (i === steps.length - 1)
@@ -366,8 +435,18 @@ export function desugar(def) {
     // per branch): spec-level context plus the union of step-level contexts.
     if (Array.isArray(d.tasks) && d.tasks.length > 0) {
         const steps = d.tasks.map(readStep);
-        const branches = steps.map((s) => (s.agent ? { task: s.task, agent: s.agent } : { task: s.task }));
+        const branches = steps.map((s) => {
+            const b = { task: s.task };
+            if (s.agent)
+                b.agent = s.agent;
+            // Per-branch literal cwd (workspace keywords are rejected by validation).
+            if (s.cwd)
+                b.cwd = s.cwd;
+            return b;
+        });
         const phase = { id: "parallel", type: "parallel", branches, final: true };
+        if (topCwd)
+            phase.cwd = topCwd;
         const shared = [...(readContextList(d.context) ?? []), ...steps.flatMap((s) => s.context ?? [])];
         if (shared.length)
             phase.context = Array.from(new Set(shared));
@@ -389,6 +468,8 @@ export function desugar(def) {
             phase.context = ctx;
         if (typeof d.contextLimit === "number")
             phase.contextLimit = d.contextLimit;
+        if (topCwd)
+            phase.cwd = topCwd;
         return { name: nameOf("task"), ...meta, phases: [phase] };
     }
     throw new Error("Shorthand spec needs one of: 'task' (single), 'tasks' (parallel), or 'chain' (sequential)");
@@ -524,6 +605,17 @@ export function validateTaskflow(def, opts = {}) {
                 warnings.push(`Invocation argument '${name}' is undeclared`);
         }
     }
+    // Flow-level idleTimeout: positive must be >= 1000; 0 is allowed (disables the
+    // watchdog) but every agent-running phase must then declare a finite wall
+    // `timeout` so the run can never hang forever (critical invariant #5).
+    if (flow.idleTimeout !== undefined) {
+        if (typeof flow.idleTimeout !== "number" || !Number.isFinite(flow.idleTimeout) || flow.idleTimeout < 0) {
+            errors.push(`Flow 'idleTimeout' must be a non-negative finite number (ms), got ${typeof flow.idleTimeout === "number" ? flow.idleTimeout : typeof flow.idleTimeout}`);
+        }
+        else if (flow.idleTimeout > 0 && flow.idleTimeout < 1000) {
+            errors.push(`Flow 'idleTimeout' must be 0 (disable) or >= 1000 ms, got ${flow.idleTimeout}`);
+        }
+    }
     // Hardening for runtime-generated (untrusted) sub-flows: bound breadth and
     // contain filesystem access. These do NOT apply to authored/saved flows.
     if (opts.dynamic) {
@@ -579,6 +671,13 @@ export function validateTaskflow(def, opts = {}) {
             if (typeof p.cwd === "string") {
                 errors.push(`Dynamic sub-flow phase '${p.id}': cwd selection is not allowed in generated flows`);
             }
+            if (Array.isArray(p.branches)) {
+                p.branches.forEach((branch, i) => {
+                    if (branch && typeof branch === "object" && typeof branch.cwd === "string") {
+                        errors.push(`Dynamic sub-flow phase '${p.id}': branches[${i}].cwd selection is not allowed in generated flows`);
+                    }
+                });
+            }
         }
     }
     const ids = new Set();
@@ -670,11 +769,35 @@ export function validateTaskflow(def, opts = {}) {
         // Branch entries become competitors at runtime (b.task is interpolated); a
         // non-object / non-string-task entry would crash the runtime, so reject it.
         if (Array.isArray(p.branches)) {
+            const branchPhaseType = (p.type ?? "agent");
             p.branches.forEach((b, i) => {
                 if (!b || typeof b !== "object" || Array.isArray(b))
                     errors.push(`Phase '${p.id}': branches[${i}] must be an object with a 'task', got ${b === null ? "null" : typeof b}`);
                 else if (typeof b.task !== "string")
                     errors.push(`Phase '${p.id}': branches[${i}].task must be a string`);
+                else {
+                    // Per-branch cwd: a literal path is honored per-branch; a reserved
+                    // workspace keyword ('temp'/'dedicated'/'worktree') is NOT supported
+                    // per-branch (the workspace lifecycle is per-phase — a branch cannot
+                    // safely allocate/teardown its own workspace). Reject that shape
+                    // precisely rather than silently using the wrong cwd. Use the
+                    // phase-level `cwd` for workspace isolation.
+                    const bcwd = b.cwd;
+                    if (typeof bcwd === "string") {
+                        if (branchPhaseType !== "parallel") {
+                            errors.push(`Phase '${p.id}' (${branchPhaseType}): branches[${i}].cwd is only supported for parallel phases`);
+                        }
+                        else if (hasCwdPlaceholder(bcwd)) {
+                            errors.push(`Phase '${p.id}': branches[${i}].cwd does not support interpolation placeholders (${bcwd}). Use a literal path.`);
+                        }
+                        else if (WORKSPACE_KEYWORDS.includes(bcwd)) {
+                            errors.push(`Phase '${p.id}': branches[${i}].cwd '${bcwd}' is a reserved workspace keyword not supported per-branch (the workspace lifecycle is per-phase). Use the phase-level 'cwd' for workspace isolation.`);
+                        }
+                        else if (typeof p.cwd === "string" && (WORKSPACE_KEYWORDS.includes(p.cwd) || hasCwdPlaceholder(p.cwd))) {
+                            errors.push(`Phase '${p.id}': branches[${i}].cwd cannot override phase cwd '${p.cwd}' because that phase uses a managed workspace/cwd binding. Put the literal cwd on the phase or remove the branch override.`);
+                        }
+                    }
+                }
             });
         }
         // tools entries are matched against a Set by the adapters (t => set.has(t));
@@ -812,6 +935,33 @@ export function validateTaskflow(def, opts = {}) {
                 errors.push(`Phase '${p.id}' (reduce) requires 'from'`);
             if (!p.task)
                 errors.push(`Phase '${p.id}' (reduce) requires 'task'`);
+            // reduceStrategy / batchSize (reduce-only).
+            const strat = p.reduceStrategy;
+            if (strat !== undefined && strat !== "tree" && strat !== "one-shot") {
+                errors.push(`Phase '${p.id}' (reduce): reduceStrategy must be 'tree' or 'one-shot', got '${String(strat)}'`);
+            }
+            const bs = p.batchSize;
+            if (bs !== undefined) {
+                if (typeof bs !== "number" || !Number.isFinite(bs) || bs < 2 || !Number.isInteger(bs)) {
+                    errors.push(`Phase '${p.id}' (reduce): batchSize must be an integer >= 2`);
+                }
+                else if (strat !== "tree") {
+                    warnings.push(`Phase '${p.id}' (reduce): batchSize is only used with reduceStrategy 'tree' — ignored for one-shot`);
+                }
+            }
+            if (strat === "tree") {
+                const batchSize = typeof bs === "number" && Number.isInteger(bs) && bs >= 2 ? bs : 2;
+                let remaining = asArray(p.from).length;
+                let maxCalls = 0;
+                while (remaining > 1 && maxCalls <= TREE_REDUCE_HARD_MAX_CALLS) {
+                    const callsThisRound = Math.ceil(remaining / batchSize);
+                    maxCalls += callsThisRound;
+                    remaining = callsThisRound;
+                }
+                if (maxCalls > TREE_REDUCE_HARD_MAX_CALLS) {
+                    errors.push(`Phase '${p.id}' (reduce): tree strategy exceeds hard cap ${TREE_REDUCE_HARD_MAX_CALLS} subagent calls; increase batchSize or split the reduction`);
+                }
+            }
         }
         if (type === "flow") {
             const hasUse = typeof p.use === "string" && p.use.length > 0;
@@ -883,6 +1033,32 @@ export function validateTaskflow(def, opts = {}) {
                     errors.push(`Phase '${p.id}' (${type}): 'timeout' must be a number >= 1000 ms`);
             }
         }
+        // idleTimeout validation (agent-running phases that can use the watchdog).
+        // The host default (300000ms) applies when neither phase nor flow sets it.
+        const AGENT_RUNNING_FOR_IDLE = new Set(AGENT_RUNNING_PHASE_TYPES);
+        if (AGENT_RUNNING_FOR_IDLE.has(type)) {
+            const phaseIdle = p.idleTimeout;
+            if (phaseIdle !== undefined) {
+                if (typeof phaseIdle !== "number" || !Number.isFinite(phaseIdle) || phaseIdle < 0) {
+                    errors.push(`Phase '${p.id}': 'idleTimeout' must be a non-negative finite number (ms), got ${typeof phaseIdle === "number" ? phaseIdle : typeof phaseIdle}`);
+                }
+                else if (phaseIdle > 0 && phaseIdle < 1000) {
+                    errors.push(`Phase '${p.id}': 'idleTimeout' must be 0 (disable) or >= 1000 ms, got ${phaseIdle}`);
+                }
+            }
+            // Effective idle watchdog = phase (wins) → flow → host default (undefined).
+            const effectiveIdle = (typeof phaseIdle === "number" ? phaseIdle : flow.idleTimeout);
+            if (effectiveIdle === 0) {
+                // Disabling the watchdog requires a finite wall timeout so the phase can
+                // never hang forever (critical invariant #5: never hang forever).
+                if (typeof p.timeout !== "number" || !Number.isFinite(p.timeout) || p.timeout < 1000) {
+                    errors.push(`Phase '${p.id}': idleTimeout:0 disables the watchdog — a finite wall 'timeout' (>= 1000 ms) is required so this phase cannot hang forever. Add a 'timeout' or use a positive 'idleTimeout'.`);
+                }
+            }
+        }
+        else if (p.idleTimeout !== undefined) {
+            warnings.push(`Phase '${p.id}' (${type}): 'idleTimeout' only applies to agent-running phases (${AGENT_RUNNING_PHASE_TYPES.join("/")}) — ignored here`);
+        }
         if (p.retry) {
             if (typeof p.retry.max !== "number" || p.retry.max < 0) {
                 errors.push(`Phase '${p.id}': retry.max must be a number >= 0`);