taskflow-core 0.2.0 → 0.2.2

package/dist/schema.js

@@ -10,10 +10,14 @@ import { contractShapeErrors } from "./contract.js";
 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;
@@ -58,11 +74,12 @@ const CACHE_SCOPES = ["run-only", "cross-run", "off"];
 const CACHE_FINGERPRINT_PREFIXES = ["git:", "glob:", "glob!:", "file:", "env:"];
 /** Phase types that must NOT be cached across runs (a fresh result is required each run). */
 const CACHE_CROSS_RUN_BLOCKED_TYPES = ["gate", "approval", "loop", "tournament", "script", "race", "expand"];
-/** `cwd` is a literal path / workspace keyword, not an interpolated field. */
-const CWD_PLACEHOLDER_RE = /\{[a-zA-Z0-9_-]+(?:\.[a-zA-Z0-9_-]+)*\}/;
 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({
@@ -112,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). */
@@ -139,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).",
@@ -186,7 +231,7 @@ const PhaseSchema = Type.Object({
         description: "Thinking level override for this phase. Unknown values are rejected instead of silently inheriting the host default.",
     })),
     tools: Type.Optional(Type.Array(Type.String(), { description: "Restrict tools for this phase's agent" })),
-    cwd: Type.Optional(Type.String({ description: "Working directory for this phase's subagent. A literal path, or a reserved keyword: 'temp' (ephemeral dir, removed after the phase), 'dedicated' (persistent dir under the run state, kept), or 'worktree' (a git worktree on a throwaway branch, removed after the phase)." })),
+    cwd: Type.Optional(Type.String({ description: "Working directory for this phase. Accepts a literal path; a reserved keyword ('temp', 'dedicated', 'worktree'); or the exact whole placeholder {args.X} when X is declared type:'relative-path'. The 0.2.1 argument bridge requires an explicit host resolve-only opt-in." })),
     final: Type.Optional(Type.Boolean({ description: "Mark this phase's output as the workflow result" })),
     optional: Type.Optional(Type.Boolean({ description: "If true, a failure does not abort the run", default: false })),
     idempotent: Type.Optional(Type.Boolean({
@@ -216,11 +261,53 @@ const PhaseSchema = Type.Object({
         description: "Opt into the Shared Context Tree for this phase: the subagent gets ctx_read/ctx_write (a blackboard shared with siblings/ancestors, to avoid re-reading files) and ctx_report/ctx_spawn (report upward + queue child tasks the runtime picks up). Default false — existing flows are unaffected.",
     })),
 }, { additionalProperties: false });
-const ArgSpecSchema = Type.Object({
+const LegacyArgSpecSchema = Type.Object({
+    type: Type.Optional(Type.Never()),
     default: Type.Optional(Type.Unknown()),
     description: Type.Optional(Type.String()),
     required: Type.Optional(Type.Boolean()),
 }, { additionalProperties: false });
+const StringArgSpecSchema = Type.Object({
+    type: Type.Literal("string"),
+    default: Type.Optional(Type.String()),
+    description: Type.Optional(Type.String()),
+    required: Type.Optional(Type.Boolean()),
+}, { additionalProperties: false });
+const RelativePathArgSpecSchema = Type.Object({
+    type: Type.Literal("relative-path"),
+    default: Type.Optional(Type.String()),
+    description: Type.Optional(Type.String()),
+    required: Type.Optional(Type.Boolean()),
+}, { additionalProperties: false });
+const NumberArgSpecSchema = Type.Object({
+    type: Type.Literal("number"),
+    default: Type.Optional(Type.Number()),
+    minimum: Type.Optional(Type.Number()),
+    maximum: Type.Optional(Type.Number()),
+    description: Type.Optional(Type.String()),
+    required: Type.Optional(Type.Boolean()),
+}, { additionalProperties: false });
+const BooleanArgSpecSchema = Type.Object({
+    type: Type.Literal("boolean"),
+    default: Type.Optional(Type.Boolean()),
+    description: Type.Optional(Type.String()),
+    required: Type.Optional(Type.Boolean()),
+}, { additionalProperties: false });
+const EnumArgSpecSchema = Type.Object({
+    type: Type.Literal("enum"),
+    values: Type.Array(Type.Union([Type.String(), Type.Number()]), { minItems: 1 }),
+    default: Type.Optional(Type.Union([Type.String(), Type.Number()])),
+    description: Type.Optional(Type.String()),
+    required: Type.Optional(Type.Boolean()),
+}, { additionalProperties: false });
+const ArgSpecSchema = Type.Union([
+    LegacyArgSpecSchema,
+    StringArgSpecSchema,
+    RelativePathArgSpecSchema,
+    NumberArgSpecSchema,
+    BooleanArgSpecSchema,
+    EnumArgSpecSchema,
+]);
 export const TaskflowSchema = Type.Object({
     name: Type.String({ minLength: 1, description: "Workflow name (becomes /tf:<name> command when saved)" }),
     description: Type.Optional(Type.String()),
@@ -239,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). */
@@ -270,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: "" };
@@ -296,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) {
@@ -313,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)
@@ -326,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));
@@ -349,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)");
@@ -370,6 +491,58 @@ export function parseTtlMs(ttl) {
     const mult = { ms: 1, s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 };
     return n * mult[unit];
 }
+function typedArgValueErrors(name, spec, value, source) {
+    const prefix = `Argument '${name}' ${source}`;
+    if (spec.type === "relative-path") {
+        const r = normalizeRelativePath(value);
+        return r.ok ? [] : [`${prefix} ${r.message}`];
+    }
+    if (spec.type === "string") {
+        if (typeof value !== "string")
+            return [`${prefix} must be a string, got ${value === null ? "null" : typeof value}`];
+        return [];
+    }
+    if (spec.type === "number") {
+        if (typeof value !== "number" || !Number.isFinite(value))
+            return [`${prefix} must be a finite number`];
+        if (spec.minimum !== undefined && value < spec.minimum)
+            return [`${prefix} must be >= ${spec.minimum}`];
+        if (spec.maximum !== undefined && value > spec.maximum)
+            return [`${prefix} must be <= ${spec.maximum}`];
+        return [];
+    }
+    if (spec.type === "boolean") {
+        return typeof value === "boolean" ? [] : [`${prefix} must be a boolean, got ${value === null ? "null" : typeof value}`];
+    }
+    if (spec.type === "enum") {
+        const values = Array.isArray(spec.values) ? spec.values : [];
+        return values.some((v) => Object.is(v, value)) ? [] : [`${prefix} must be one of ${JSON.stringify(values)}`];
+    }
+    return [];
+}
+/** Validate resolved invocation values independently of full flow structure.
+ * Runtime calls this at the Core boundary so direct, resume, and detached
+ * execution cannot bypass adapter-level typed-arg checks. */
+export function validateInvocationArgs(def, args) {
+    const errors = [];
+    const specs = (def.args ?? {});
+    for (const [name, spec] of Object.entries(specs)) {
+        // Full structural validation owns malformed specs. Keep this boundary
+        // total so validateTaskflow() reports SchemaErrors instead of throwing
+        // while it performs the optional invocation-value pass.
+        if (typeof spec !== "object" || spec === null || Array.isArray(spec))
+            continue;
+        const typedSpec = spec;
+        if (!(name in args)) {
+            if (typedSpec.type !== undefined && typedSpec.required === true && typedSpec.default === undefined)
+                errors.push(`Missing required argument '${name}'`);
+            continue;
+        }
+        if (typedSpec.type !== undefined)
+            errors.push(...typedArgValueErrors(name, typedSpec, args[name], "invocation"));
+    }
+    return errors;
+}
 export function validateTaskflow(def, opts = {}) {
     const errors = [];
     const warnings = [];
@@ -397,6 +570,52 @@ export function validateTaskflow(def, opts = {}) {
         errors.push("Taskflow must have at least one phase");
         return { ok: false, errors, warnings };
     }
+    // Typed invocation args are the trust boundary for resource selectors. Legacy
+    // specs remain valid for every flow version, but can never feed a cwd bridge.
+    // `version` is informational metadata, not a schema-version selector.
+    const argSpecs = (typeof flow.args === "object" && flow.args !== null && !Array.isArray(flow.args)
+        ? flow.args
+        : {});
+    for (const [name, spec] of Object.entries(argSpecs)) {
+        if (!spec || typeof spec !== "object" || Array.isArray(spec))
+            continue;
+        if (spec.type === "number" && spec.minimum !== undefined && spec.maximum !== undefined && spec.minimum > spec.maximum) {
+            errors.push(`Argument '${name}': minimum must be <= maximum`);
+        }
+        if (spec.type === "enum" && Array.isArray(spec.values) && new Set(spec.values.map((v) => `${typeof v}:${String(v)}`)).size !== spec.values.length) {
+            errors.push(`Argument '${name}': enum values must be unique`);
+        }
+        if (spec.default !== undefined && spec.type !== undefined) {
+            errors.push(...typedArgValueErrors(name, spec, spec.default, "default"));
+        }
+    }
+    if (opts.args !== undefined) {
+        errors.push(...validateInvocationArgs(flow, opts.args));
+        for (const [name, spec] of Object.entries(argSpecs)) {
+            if (!spec || typeof spec !== "object" || Array.isArray(spec))
+                continue;
+            if (spec.type === undefined && spec.required === true && spec.default === undefined && !(name in opts.args)) {
+                warnings.push(`Legacy untyped argument '${name}' is marked required but remains advisory; add an explicit type to enforce it`);
+            }
+        }
+        for (const name of Object.keys(opts.args)) {
+            if (name in argSpecs)
+                continue;
+            if (strict)
+                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) {
@@ -406,10 +625,12 @@ export function validateTaskflow(def, opts = {}) {
         if (typeof flow.concurrency === "number" && flow.concurrency > MAX_DYNAMIC_CONCURRENCY) {
             errors.push(`Dynamic sub-flow concurrency too high (${flow.concurrency}, max ${MAX_DYNAMIC_CONCURRENCY})`);
         }
-        const root = opts.cwd ? path.resolve(opts.cwd) : undefined;
         for (const p of flow.phases) {
             if (!p || typeof p !== "object")
                 continue;
+            if (Array.isArray(p.context) && p.context.length > 0) {
+                errors.push(`Dynamic sub-flow phase '${p.id}': context file pre-reads are not allowed in generated flows`);
+            }
             // A generated phase may not execute shell commands. `script` runs an
             // arbitrary command — a strictly larger capability than the reserved
             // cwd keywords blocked below — so an LLM-authored plan (flow{def} /
@@ -444,20 +665,18 @@ export function validateTaskflow(def, opts = {}) {
             if (typeof p.concurrency === "number" && p.concurrency > MAX_DYNAMIC_CONCURRENCY) {
                 errors.push(`Dynamic sub-flow phase '${p.id}': concurrency too high (${p.concurrency}, max ${MAX_DYNAMIC_CONCURRENCY})`);
             }
-            // cwd containment: a generated phase may not escape the run's cwd, and
-            // may not request a reserved workspace keyword (temp/dedicated/worktree)
-            // — LLM-authored sub-flows must not allocate isolated dirs or git
-            // worktrees that mutate the repo. Only author-written flows may.
+            // W1a/FileBroker is not available yet, so a generated phase may not
+            // choose any cwd. Lexical containment is insufficient because symlinks
+            // and time-of-check/time-of-use races can cross the invocation boundary.
             if (typeof p.cwd === "string") {
-                if (WORKSPACE_KEYWORDS.includes(p.cwd)) {
-                    errors.push(`Dynamic sub-flow phase '${p.id}': cwd '${p.cwd}' is a reserved workspace keyword not allowed in generated flows`);
-                }
-                else if (root) {
-                    const resolved = path.resolve(root, p.cwd);
-                    if (resolved !== root && !resolved.startsWith(root + path.sep)) {
-                        errors.push(`Dynamic sub-flow phase '${p.id}': cwd '${p.cwd}' escapes the run directory`);
+                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`);
                     }
-                }
+                });
             }
         }
     }
@@ -516,8 +735,26 @@ export function validateTaskflow(def, opts = {}) {
             !THINKING_LEVELS.includes(p.thinking)) {
             errors.push(`Phase '${p.id}': 'thinking' must be one of ${THINKING_LEVELS.join(", ")}; got '${p.thinking}'`);
         }
-        if (typeof p.cwd === "string" && CWD_PLACEHOLDER_RE.test(p.cwd)) {
-            errors.push(`Phase '${p.id}': 'cwd' does not support interpolation placeholders (${p.cwd}). Use a literal path, or a reserved workspace keyword ('temp', 'dedicated', 'worktree').`);
+        if (typeof p.cwd === "string" && hasCwdPlaceholder(p.cwd)) {
+            const argName = cwdArgName(p.cwd);
+            if (!argName) {
+                errors.push(`Phase '${p.id}': dynamic 'cwd' must be exactly one whole {args.X} placeholder; concatenation, multiple placeholders, and {steps.*} are forbidden.`);
+            }
+            else {
+                const spec = argSpecs[argName];
+                if (!spec) {
+                    errors.push(`Phase '${p.id}': cwd references undeclared argument '${argName}'`);
+                }
+                else if (spec.type !== "relative-path") {
+                    errors.push(`Phase '${p.id}': cwd argument '${argName}' must be declared with type 'relative-path'`);
+                }
+                if (p.cache?.scope === "cross-run") {
+                    errors.push(`Phase '${p.id}': cwd selected by an argument cannot use cache.scope 'cross-run' until workspace state restoration is available.`);
+                }
+                if (p.retry && typeof p.retry.max === "number" && p.retry.max > 0) {
+                    errors.push(`Phase '${p.id}': cwd selected by an argument cannot use retry.max > 0 because a failed resolve-only write has an unknown filesystem outcome and must be reconciled before another attempt.`);
+                }
+            }
         }
         // dependsOn / from entries are string phase-id refs that flow into the graph
         // helpers and nodeId(); a non-string entry would crash the renderer.
@@ -532,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));
@@ -590,7 +851,9 @@ export function validateTaskflow(def, opts = {}) {
                     warnings.push(`Phase '${p.id}' (gate): both 'eval' and 'score' are set — eval runs first (all-pass skips the gate entirely), then score. This is valid but usually one of the two suffices.`);
                 }
                 // Judge agent naming convention (mirrors the phase-agent check below).
-                const judgeAgent = scoreVal.judge?.agent;
+                const judgeAgent = scoreVal !== null && typeof scoreVal === "object"
+                    ? scoreVal.judge?.agent
+                    : undefined;
                 if (typeof judgeAgent === "string" && judgeAgent.includes("_")) {
                     errors.push(`Phase '${p.id}': score.judge.agent '${judgeAgent}' uses underscores — use hyphens`);
                 }
@@ -672,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;
@@ -743,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`);
@@ -972,6 +1288,7 @@ export function collectRefs(phase) {
     scan(phase.over);
     scan(phase.when);
     scan(phase.until);
+    scan(phase.cwd);
     // Script phases: the array form of `run` supports {steps.X}/{args.X}
     // interpolation (the string form does NOT — it's a raw shell command,
     // validation rejects placeholders in it), and `input` (stdin) does too.