taskflow-core 0.2.1 → 0.2.2

package/dist/runtime.js

@@ -28,7 +28,7 @@ const noRunnerInjected = async (_cwd, _agents, agentName, task) => ({
 });
 export { PHASE_TIMEOUT_ABORT_GRACE_MS } from "./runner-core.js";
 import { aggregateUsage, emptyUsage } from "./usage.js";
-import { dependenciesOf, finalPhase, LOOP_DEFAULT_MAX_ITERATIONS, LOOP_HARD_MAX_ITERATIONS, MAX_DYNAMIC_MAP_ITEMS, MAX_DYNAMIC_NESTING, MAX_DYNAMIC_PHASES, parseTtlMs, resolveArgs, topoLayers, TOURNAMENT_DEFAULT_VARIANTS, TOURNAMENT_HARD_MAX_VARIANTS, validateInvocationArgs, validateTaskflow } from "./schema.js";
+import { asArray, dependenciesOf, LOOP_DEFAULT_MAX_ITERATIONS, LOOP_HARD_MAX_ITERATIONS, MAX_DYNAMIC_MAP_ITEMS, MAX_DYNAMIC_NESTING, MAX_DYNAMIC_PHASES, parseTtlMs, resolveArgs, topoLayers, TOURNAMENT_DEFAULT_VARIANTS, TOURNAMENT_HARD_MAX_VARIANTS, validateInvocationArgs, validateTaskflow } from "./schema.js";
 import { verifyTaskflow } from "./verify.js";
 import { combineScores, combineWithJudge, evaluatePureScorer, formatScorerReport, parseJudgeOutput, SCORE_DEFAULT_THRESHOLD, scoreResultJSON, scorerShapeErrors } from "./scorers.js";
 import { parseGateVerdict, overBudget as overBudgetCheck, parseTournamentWinner } from "./deterministic.js";
@@ -40,6 +40,7 @@ export { parseGateVerdict };
 import { runCodeCompilesScorer } from "./scorer-runtime.js";
 import { buildReflexionSummary, isContractViolation, REFLEXION_SENTINEL } from "./reflexion.js";
 import { hashInput, newRunId, runsDir } from "./store.js";
+import { resolveFinalOutput } from "./final-output.js";
 import { CacheStore, resolveFingerprint } from "./cache.js";
 import { compileTaskflowToIR, phaseFingerprint } from "./flowir/index.js";
 import { computeStaleFrontier, declaredReadMapOfDef, readMapOf } from "./stale.js";
@@ -47,6 +48,11 @@ import { ctxDirFor, drainPendingSpawns, initCtxDir, registerNode, setNodeStatus
 import { allocateWorkspace, isWorkspaceKeyword } from "./workspace.js";
 import { cwdArgName, directoryIdentity, isPathWithin, resolveCwdArg, } from "./cwd-bridge.js";
 import { createResolveOnlyWorkspaceSession, } from "./resources/execution.js";
+// Re-export the shared final-output helper + types so callers importing from
+// the runtime barrel get them from one place. The event kernel
+// (`exec/driver.ts`) imports these directly from `./final-output.ts` to avoid
+// a static runtime↔driver import cycle.
+export { resolveFinalOutput, } from "./final-output.js";
 /** Compute the incremental-reuse summary from a run's terminal phase states.
  *  Pure, total, never throws. A phase is "reused" iff it carries a `cacheHit`
  *  marker (set by `cachedPhase` for both within-run resume and cross-run hits). */
@@ -556,6 +562,13 @@ function resolveEffCwd(deps, phase) {
     // is not necessarily the invocation root, so anchor legacy literals here.
     return path.resolve(deps.cwd, phase.cwd);
 }
+/** Resolve a literal per-branch cwd once for BOTH cache identity and execution.
+ * Existing directories are realpath-canonicalized so aliases/symlinks cannot
+ * collide with a different invocation root under the same raw cwd string. */
+function resolveBranchCwd(deps, cwd) {
+    const resolved = path.resolve(deps.cwd, cwd);
+    return directoryIdentity(resolved)?.canonicalPath ?? resolved;
+}
 function flowTreeUsesCwdBridge(def, loadFlow, seenUses = new Set()) {
     if (def.phases.some((phase) => cwdArgName(phase.cwd) !== undefined))
         return true;
@@ -700,14 +713,11 @@ async function runInlineSubflow(subflowSpec, defaultAgent, childNodeId, phase, d
         return { output: `(spawned subflow failed: ${error})`, usage: emptyUsage(), failed: true, error };
     }
 }
-async function runSpawnedChildren(assignments, ctxDir, parentNodeId, phase, deps, state, run, ledger = { usage: emptyUsage() }) {
+async function runSpawnedChildren(assignments, ctxDir, parentNodeId, phase, deps, state, runChild, ledger = { usage: emptyUsage() }) {
     const capped = assignments.slice(0, MAX_DYNAMIC_MAP_ITEMS);
     const lines = [];
     const usages = [];
     const errors = [];
-    // Effective cwd for flat spawned tasks: honour a workspace override and never
-    // pass a reserved keyword through to the runner.
-    const spawnCwd = resolveEffCwd(deps, phase);
     let idx = 0;
     for (const a of capped) {
         if (deps.signal?.aborted || spawnedOverBudget(state, ledger.usage))
@@ -730,30 +740,11 @@ async function runSpawnedChildren(assignments, ctxDir, parentNodeId, phase, deps
             }
             else {
                 const task = a.task ?? "";
-                const runOptions = {
-                    model: phase.model,
-                    thinking: phase.thinking,
-                    tools: phase.tools,
-                    cwd: spawnCwd,
-                    signal: deps.signal,
-                    ctxDir,
-                    nodeId: childNodeId,
-                };
-                const invoke = () => run(spawnCwd, deps.agents, agentName, task, runOptions, deps.globalThinking);
-                // ctx_spawn is part of the phase's execution tree, not bookkeeping.
-                // Inherit the exact cwd capability and give every descendant a unique
-                // unit owner so no child can bypass lease/WAL/permit coordination.
-                const r = deps._workspaceBinding
-                    ? await deps._workspaceBinding.runAgent({
-                        agents: deps.agents,
-                        agentName,
-                        task,
-                        opts: runOptions,
-                        globalThinking: deps.globalThinking,
-                        unitId: childNodeId,
-                        invoke,
-                    })
-                    : await invoke();
+                // Flat ctx_spawn children use the SAME runOne policy as their parent:
+                // phase timeout, idle watchdog, retries, budget accounting, tracing,
+                // prompt diagnostics, cwd capability, and workspace binding.
+                const usageBefore = ledger.usage;
+                const r = await runChild(agentName, task, childNodeId, usageBefore);
                 out = r.output ?? "";
                 if (isFailed(r)) {
                     const detail = sanitizeErrorMessage(r.errorMessage ?? r.stderr ?? "spawned child failed");
@@ -769,7 +760,7 @@ async function runSpawnedChildren(assignments, ctxDir, parentNodeId, phase, deps
                 // A child may itself have queued spawns — recurse (depth-capped by the tool).
                 const grand = drainPendingSpawns(ctxDir, childNodeId);
                 if (grand.length > 0 && !deps.signal?.aborted && !spawnedOverBudget(state, ledger.usage)) {
-                    const rec = await runSpawnedChildren(grand, ctxDir, childNodeId, phase, deps, state, run, ledger);
+                    const rec = await runSpawnedChildren(grand, ctxDir, childNodeId, phase, deps, state, runChild, ledger);
                     if (rec.reports)
                         out += rec.reports;
                     usages.push(rec.usage);
@@ -810,8 +801,10 @@ async function executePhase(phase, state, deps, prior, emitProgress, _retryDepth
         emitUnreplayableMarker(deps, state, phase);
     let result;
     let threw = false;
+    const promptCalls = [];
+    const trackedOpts = { ...opts, promptCalls };
     try {
-        result = await executePhaseImpl(phase, state, deps, prior, emitProgress, _retryDepth, opts);
+        result = await executePhaseImpl(phase, state, deps, prior, emitProgress, _retryDepth, trackedOpts);
     }
     catch (e) {
         threw = true;
@@ -825,6 +818,9 @@ async function executePhase(phase, state, deps, prior, emitProgress, _retryDepth
     }
     if (threw)
         return result; // unreachable; satisfies TS
+    if (promptCalls.length > 0 && !result.cacheHit) {
+        setPromptStats(result, promptCalls);
+    }
     // S1: cache-hit decision (within-run or cross-run) for fold/replay.
     if (result.cacheHit) {
         traceDecision(deps, state, phase.id, {
@@ -1053,7 +1049,13 @@ async function executePhaseImpl(phase, state, deps, prior, emitProgress, _retryD
 async function executePhaseInner(phase, state, deps, prior, emitProgress, _retryDepth = 0, opts) {
     const type = phase.type ?? "agent";
     const concurrency = phase.concurrency ?? state.def.concurrency ?? 8;
-    const previousOutput = lastCompletedOutput(state, phase);
+    // BREAKING (dogfood issue 1): a reduce phase's {previous.output} aggregates
+    // ALL completed `from[]` outputs in from-array order (one → raw, many →
+    // `### <id>\n\n<output>` joined by `\n\n---\n\n`). Other phase types keep the
+    // historical "last completed dependency" behavior. The aggregated from-ids
+    // are recorded as observed reads (below) so staleness tracks them.
+    const reduceAgg = type === "reduce" ? aggregateReduceFrom(state, phase) : undefined;
+    const previousOutput = reduceAgg ? reduceAgg.value : lastCompletedOutput(state, phase);
     const run = deps.runTask ?? noRunnerInjected;
     // Effective working directory for THIS phase's execution. When an isolated
     // workspace was allocated (worktree isolation), `_cwdOverride` is its dir and
@@ -1087,6 +1089,14 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
     const onRead = (ref) => {
         readRefs.push(ref);
     };
+    // Record the reduce-aggregated from-ids as observed reads: the phase consumed
+    // these upstream outputs (folded into {previous.output}) even when the task
+    // references {previous.output} once (a single placeholder read would otherwise
+    // record only "previous.output", not the real upstream ids).
+    if (reduceAgg) {
+        for (const id of reduceAgg.ids)
+            readRefs.push(`steps.${id}.output`);
+    }
     const ctx = buildInterpolationContext(state, previousOutput, undefined, onRead);
     // M3 observed-readSet: when conditions are part of the phase's real
     // dependencies. Evaluate them inside executePhaseInner so every upstream
@@ -1158,21 +1168,60 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         agentScope: state.def.agentScope,
         contextSharing: state.def.contextSharing === true,
         agentDefinitions: agentDefinitionsIdentity(deps.agents),
-        executionCwd: phase.cwd !== undefined || deps._cacheCwdIdentity !== undefined ? effCwd : undefined,
+        executionCwd: directoryIdentity(effCwd)?.canonicalPath ?? path.resolve(effCwd),
     };
-    const baseRun = (agentName, task, onLive, ctxNodeId, signal, onTerminalCommit) => {
+    // Effective idle watchdog (ms): phase overrides flow; host default (300000)
+    // applies when neither sets it. `0` disables the watchdog (validation already
+    // required a finite wall `timeout` in that case). Threaded into RunOptions so
+    // every host runner that delegates to runSubagentProcess honors it.
+    const effIdleTimeoutMs = resolveIdleTimeoutMs(phase, state.def);
+    const baseRun = (agentName, task, onLive, ctxNodeId, signal, callCwd, onTerminalCommit) => {
+        const invocationCwd = callCwd ? path.resolve(deps.cwd, callCwd) : effCwd;
+        // A per-branch cwd cannot replace a phase-level workspace/cwd-bridge
+        // binding: that would bypass the binding's containment/dirty-state
+        // lifecycle. Validation rejects this shape; keep a runtime fail-closed
+        // guard for direct callers or legacy persisted definitions.
+        if (callCwd && (deps._workspaceBinding || isWorkspaceKeyword(phase.cwd))) {
+            return Promise.resolve({
+                agent: agentName,
+                task,
+                exitCode: 1,
+                output: "",
+                stderr: "TF_CWD_BRANCH_BINDING_CONFLICT: per-branch cwd cannot override a phase workspace binding",
+                usage: emptyUsage(),
+                stopReason: "error",
+                errorMessage: "TF_CWD_BRANCH_BINDING_CONFLICT: per-branch cwd cannot override a phase workspace binding",
+            });
+        }
+        if (callCwd && deps._cwdBoundary) {
+            const selected = directoryIdentity(invocationCwd);
+            if (!selected || !isPathWithin(deps._cwdBoundary, selected.canonicalPath)) {
+                return Promise.resolve({
+                    agent: agentName,
+                    task,
+                    exitCode: 1,
+                    output: "",
+                    stderr: "TF_CWD_BOUNDARY_ESCAPE: per-branch cwd must select an existing directory inside the inherited cwd boundary",
+                    usage: emptyUsage(),
+                    stopReason: "error",
+                    errorMessage: "TF_CWD_BOUNDARY_ESCAPE: per-branch cwd must select an existing directory inside the inherited cwd boundary",
+                });
+            }
+        }
+        opts?.promptCalls?.push(task);
         const runOptions = {
             model: phase.model,
             thinking: phase.thinking,
             tools: phase.tools,
-            cwd: effCwd,
+            cwd: invocationCwd,
             signal: signal ?? deps.signal,
             onLive,
             ctxDir: ctxDir,
             nodeId: ctxDir ? ctxNodeId : undefined,
+            idleTimeoutMs: effIdleTimeoutMs,
             onTerminalCommit,
         };
-        const invoke = () => run(effCwd, deps.agents, agentName, task, runOptions, deps.globalThinking);
+        const invoke = () => run(invocationCwd, deps.agents, agentName, task, runOptions, deps.globalThinking);
         return deps._workspaceBinding
             ? deps._workspaceBinding.runAgent({
                 agents: deps.agents,
@@ -1204,7 +1253,18 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         : undefined;
     const runOne = async (agentName, task, onLive, ctxNodeId, check, 
     /** Extra abort (e.g. race branch cancelLosers) — chained with run + phase timeout. */
-    extraSignal) => {
+    extraSignal, 
+    /** Per-call cwd override (e.g. a parallel branch's literal cwd). Falls back
+     *  to the phase effective cwd when absent. Workspace keywords are rejected
+     *  by validation for branches, so this is always a literal path or undefined. */
+    callCwd, 
+    /** Usage already spent by earlier calls inside this same multi-call phase
+     * (tree reduce). Included in live budget accounting, but not returned as
+     * this call's own usage. */
+    usageBefore, 
+    /** Optional hard admission guard invoked immediately before EVERY actual
+     * runner attempt. Return an error message to deny that attempt. */
+    beforeAttempt) => {
         const explicitMax = Math.max(1, 1 + Math.max(0, Math.floor(retry?.max ?? 0)));
         // Allow enough attempts to cover whichever policy applies on a given attempt.
         const maxAttempts = Math.max(explicitMax, 1 + DEFAULT_TRANSIENT_RETRIES);
@@ -1213,6 +1273,20 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         for (let attempt = 0; attempt < maxAttempts; attempt++) {
             if (deps.signal?.aborted || extraSignal?.aborted)
                 break;
+            const admissionError = beforeAttempt?.();
+            if (admissionError) {
+                last = {
+                    agent: agentName,
+                    task,
+                    exitCode: 1,
+                    output: "",
+                    stderr: admissionError,
+                    usage: emptyUsage(),
+                    stopReason: "error",
+                    errorMessage: admissionError,
+                };
+                break;
+            }
             // AbortController chains: run signal + optional extra (race cancel) + phase timeout.
             // Deterministic: a timed-out call is never retried (would double-spend).
             let timedOut = false;
@@ -1251,7 +1325,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                         timer = undefined;
                     }
                 };
-                const invocation = baseRun(agentName, task, onLive, ctxNodeId, callSignal, onTerminalCommit);
+                const invocation = baseRun(agentName, task, onLive, ctxNodeId, callSignal, callCwd, onTerminalCommit);
                 if (phaseTimeoutMs && timeoutController) {
                     const timeoutFallback = new Promise((resolve) => {
                         timer = setTimeout(() => {
@@ -1332,7 +1406,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
             // so the TUI / budget guard see the in-flight spend on every attempt.
             const liveRetry = state.phases[phase.id];
             if (liveRetry)
-                liveRetry.usage = aggregateUsage(usages);
+                liveRetry.usage = aggregateUsage(usageBefore ? [usageBefore, ...usages] : usages);
             // Persist every attempt, not only the final aggregate. This is required
             // for honest replay/cost accounting when a transient or explicit retry
             // succeeds after earlier spend.
@@ -1432,11 +1506,33 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                 attempts: 0,
             };
         }
-        if (usages.length > 1)
+        if (usages.length > 0)
             last.usage = aggregateUsage(usages);
         last.attempts = usages.length;
         return last;
     };
+    const runSpawnedChild = async (agentName, task, childNodeId, spawnedUsageBefore) => {
+        // runOne updates the live phase usage so retry/budget admission sees current
+        // spend. A spawned child is folded into the parent result later, so restore
+        // the parent's pre-child usage after the call to avoid replacing/doubling it.
+        const livePhase = state.phases[phase.id];
+        const parentUsage = livePhase?.usage ? { ...livePhase.usage } : undefined;
+        const totalUsageBefore = aggregateUsage([
+            parentUsage ?? emptyUsage(),
+            spawnedUsageBefore ?? emptyUsage(),
+        ]);
+        try {
+            return await runOne(agentName, task, undefined, childNodeId, undefined, undefined, undefined, totalUsageBefore);
+        }
+        finally {
+            if (livePhase) {
+                if (parentUsage)
+                    livePhase.usage = parentUsage;
+                else
+                    livePhase.usage = undefined;
+            }
+        }
+    };
     const parseJson = phase.output === "json";
     // Output contract (`expect`): validates the parsed JSON output of a finished
     // subagent call. Wired into `runOne` so a violation counts as a failed attempt
@@ -1531,12 +1627,16 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                 if (l.model)
                     latestModel = l.model;
                 refresh();
-            }, ctxDir ? nodeIdFor(String(idx)) : undefined);
+            }, ctxDir ? nodeIdFor(String(idx)) : undefined, undefined, undefined, it.cwd);
             running--;
             done++;
             if (isFailed(r))
                 failed++;
             liveUsages[idx] = r.usage;
+            // Publish the just-finished sibling's spend before considering any
+            // ctx_spawn intents. Budgeted fan-out allows one atomic call to cross the
+            // ceiling, but must not admit descendants after that overshoot.
+            refresh();
             // Per-item cross-run cache record (map only): persist a successful fresh
             // item so a later run with this item unchanged hits per-item instead of
             // re-running. Failed and budget-skipped items are never cached (a stale
@@ -1564,7 +1664,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                     // post-run drain below only covers single-agent phases).
                     const spawned = drainPendingSpawns(ctxDir, itemNid);
                     if (spawned.length > 0 && !deps.signal?.aborted && !overBudget(state).over) {
-                        const child = await runSpawnedChildren(spawned, ctxDir, itemNid, phase, deps, state, run);
+                        const child = await runSpawnedChildren(spawned, ctxDir, itemNid, phase, deps, state, runSpawnedChild, { usage: emptyUsage() });
                         if (child.reports)
                             r.output = `${r.output ?? ""}${child.reports}`;
                         if (child.failed && deps._workspaceBinding) {
@@ -1587,6 +1687,96 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
     // Single-agent phases: agent, gate, and reduce all run one subagent on an
     // interpolated task. gate additionally parses a verdict; reduce simply pulls
     // its inputs from `from` phases (already exposed via interpolation).
+    //
+    // Tree reduce (`reduceStrategy: "tree"`) is handled FIRST: it runs batched
+    // intermediate reducer calls over the aggregated `from[]` inputs, reusing
+    // `runOne` so retry/timeout/budget/idleTimeout behavior is identical to a
+    // one-shot call. It forces the imperative runtime (the event kernel falls
+    // back via kernelUnsupportedReason). The corrected `{previous.output}`
+    // aggregation (all completed `from[]` sources) applies to EVERY round.
+    if (type === "reduce" && phase.reduceStrategy === "tree") {
+        const stratBs = phase.batchSize;
+        const batchSize = typeof stratBs === "number" && Number.isFinite(stratBs) && stratBs >= 2 ? Math.floor(stratBs) : 2;
+        const { collectTreeReduceInputs, executeTreeReduction, treeReduceCacheParts, } = await import("./runtime/phases/reduce.js");
+        const inputs = collectTreeReduceInputs(state, phase);
+        // 0–1 completed inputs: tree reduction is a no-op — fall through to the
+        // one-shot path (which handles the degenerate case correctly).
+        if (inputs.length >= 2) {
+            const agentName = resolveAgent(phase.agent, deps, state);
+            const cacheKey = cacheKeys(cc, treeReduceCacheParts(state, phase, inputs, batchSize));
+            const cached = cachedPhase(cc, cacheKey);
+            if (cached)
+                return cached;
+            const execution = await executeTreeReduction({
+                phase,
+                inputs,
+                batchSize,
+                agentName,
+                inputHash: cacheKey.key,
+                isAborted: () => deps.signal?.aborted === true,
+                isOverBudget: () => overBudget(state).over,
+                resolveTask: (batchValue) => {
+                    const batchCtx = buildInterpolationContext(state, batchValue, undefined, onRead);
+                    const interp = interpolate(phase.task ?? "", batchCtx);
+                    return {
+                        task: appendGateFormatSuffix(preRead + interp.text, phase),
+                        warning: warnUnresolvedRefs(phase.id, interp.missing),
+                    };
+                },
+                runOne: async (task, usageBefore, beforeAttempt, callId) => {
+                    const batchNodeId = nodeIdFor(`tree-${callId}`);
+                    if (ctxDir) {
+                        try {
+                            registerNode(ctxDir, batchNodeId, phase.id, undefined, "running");
+                        }
+                        catch { /* fail-open */ }
+                    }
+                    const result = await runOne(agentName, task, liveSink(state, phase.id, emitProgress), batchNodeId, contractCheck, undefined, undefined, usageBefore, beforeAttempt);
+                    if (ctxDir) {
+                        try {
+                            const spawned = drainPendingSpawns(ctxDir, batchNodeId);
+                            if (spawned.length > 0 && !deps.signal?.aborted && !overBudget(state).over) {
+                                const child = await runSpawnedChildren(spawned, ctxDir, batchNodeId, phase, deps, state, runSpawnedChild, { usage: emptyUsage() });
+                                if (child.reports)
+                                    result.output = `${result.output ?? ""}${child.reports}`;
+                                if (child.failed && deps._workspaceBinding) {
+                                    result.exitCode = result.exitCode === 0 ? 1 : result.exitCode;
+                                    result.stopReason = "error";
+                                    result.errorMessage = `Workspace ctx_spawn descendant failed: ${child.errors.join("; ")}`;
+                                }
+                                result.usage = aggregateUsage([result.usage ?? emptyUsage(), child.usage]);
+                            }
+                            setNodeStatus(ctxDir, batchNodeId, isFailed(result) ? "failed" : "done");
+                        }
+                        catch { /* fail-open */ }
+                    }
+                    const livePhase = state.phases[phase.id];
+                    if (livePhase) {
+                        livePhase.usage = aggregateUsage([
+                            usageBefore ?? emptyUsage(),
+                            result.usage ?? emptyUsage(),
+                        ]);
+                    }
+                    return result;
+                },
+            });
+            const ps = execution.phaseState;
+            if (parseJson && ps.status === "done")
+                ps.json = safeParse(ps.output ?? "");
+            if (readRefs.length)
+                ps.reads = readRefsToReads(readRefs, state);
+            if (execution.refWarning)
+                ps.warnings = [...(ps.warnings ?? []), execution.refWarning];
+            if (ps.budgetTruncated) {
+                ps.warnings = [...(ps.warnings ?? []), "tree reduction stopped by the run budget; output is partial"];
+            }
+            attachReduceInputStats(ps, state, phase);
+            if (execution.cacheable)
+                recordCache(cc, ps);
+            return ps;
+        }
+        // inputs.length < 2 → fall through to one-shot (below).
+    }
     if (type === "agent" || type === "gate" || type === "reduce") {
         // Eval gate: zero-token machine checks before the LLM gate.
         if (type === "gate" && Array.isArray(phase.eval) && phase.eval.length > 0) {
@@ -1876,6 +2066,11 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
             ps.reads = readRefsToReads(readRefs, state);
         if (refWarning)
             ps.warnings = [...(ps.warnings ?? []), refWarning];
+        // Prompt-size diagnostics for the single agent call (durable).
+        attachPromptStats(ps, [fullTask]);
+        // reduce: record aggregate input stats.
+        if (type === "reduce")
+            attachReduceInputStats(ps, state, phase);
         if (type === "gate" && ps.status === "done") {
             ps.gate = parseGateVerdict(r.output);
             // Trace: gate decision (fail-open). Replay re-adjudicates thresholds.
@@ -1892,7 +2087,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                 registerNode(ctxDir, nid, phase.id, undefined, ps.status === "failed" ? "failed" : "done");
                 const spawned = drainPendingSpawns(ctxDir, nid);
                 if (spawned.length > 0 && !deps.signal?.aborted && !overBudget(state).over) {
-                    const child = await runSpawnedChildren(spawned, ctxDir, nid, phase, deps, state, run);
+                    const child = await runSpawnedChildren(spawned, ctxDir, nid, phase, deps, state, runSpawnedChild, { usage: emptyUsage() });
                     if (child.reports)
                         ps.output = `${ps.output ?? ""}${child.reports}`;
                     if (child.failed && deps._workspaceBinding) {
@@ -2024,6 +2219,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
             return {
                 agent: resolveAgent(b.agent ?? phase.agent, deps, state),
                 task: preRead + r.text,
+                cwd: typeof b.cwd === "string" ? resolveBranchCwd(deps, b.cwd) : undefined,
             };
         });
         const ck = cacheKeys(cc, [phase.id, phase.model ?? "", JSON.stringify(branches)]);
@@ -2835,6 +3031,147 @@ function lastCompletedOutput(state, phase) {
     }
     return undefined;
 }
+/** A conservative prompt-size warning threshold in estimated tokens. Crossed
+ *  → the phase records a `warnings` entry so an author notices they may be
+ *  approaching a model's context limit. Approximate (ceil(chars/4)), not a
+ *  real tokenizer count. Chosen conservatively well below typical 128K context
+ *  windows so the warning fires with ample headroom. */
+export const PROMPT_SIZE_WARN_TOKENS = 32_000;
+/** Compute durable prompt-size diagnostics for a resolved prompt string:
+ *  exact UTF-8 byte count, character count, and a documented approximate token
+ *  estimate (ceil(chars/4)). Never throws. */
+export function promptSizeStats(text) {
+    let chars = 0;
+    for (const _char of text)
+        chars++; // Unicode code points, not UTF-16 code units
+    const bytes = Buffer.byteLength(text, "utf8");
+    const estTokens = Math.ceil(chars / 4);
+    return { bytes, chars, estTokens };
+}
+/** Replace a phase's call diagnostics with the exact prompts captured by the
+ * shared runner boundary. This covers single calls, retries, fan-out items,
+ * loop/tournament/judge calls, and tree-reduce rounds without per-branch drift. */
+function setPromptStats(ps, prompts) {
+    try {
+        const calls = prompts.map((text) => promptSizeStats(text));
+        const reduceInputs = ps.promptStats?.reduceInputs;
+        ps.promptStats = { calls, ...(reduceInputs ? { reduceInputs } : {}) };
+        ps.warnings = (ps.warnings ?? []).filter((warning) => !warning.startsWith("Prompt size ≈"));
+        for (const call of calls) {
+            if (call.estTokens >= PROMPT_SIZE_WARN_TOKENS) {
+                ps.warnings.push(`Prompt size ≈${call.estTokens} tokens (${call.chars} chars, ${call.bytes} bytes) exceeds the conservative ${PROMPT_SIZE_WARN_TOKENS}-token warning threshold — the prompt may be approaching a model's context limit.`);
+            }
+        }
+        if (ps.warnings.length === 0)
+            delete ps.warnings;
+    }
+    catch {
+        /* diagnostics must never sink the phase */
+    }
+}
+/** Attach durable prompt-size diagnostics to a PhaseState. `prompts` is the list
+ *  of resolved prompt strings actually sent to a subagent (one entry per call —
+ *  one for an agent phase, multiple for a tree reduce). Each becomes a
+ *  `{bytes, chars, estTokens}` record on `ps.promptStats.calls`. When any call
+ *  crosses {@link PROMPT_SIZE_WARN_TOKENS}, a `warnings` entry is appended so an
+ *  author notices they may be approaching a model's context limit (the estimate
+ *  is conservative: ceil(chars/4), not a real tokenizer count). Never throws. */
+function attachPromptStats(ps, prompts) {
+    try {
+        const calls = prompts.map((t) => promptSizeStats(t));
+        const existing = ps.promptStats;
+        ps.promptStats = existing
+            ? { ...existing, calls: [...existing.calls, ...calls] }
+            : { calls };
+        for (const c of calls) {
+            if (c.estTokens >= PROMPT_SIZE_WARN_TOKENS) {
+                ps.warnings = [...(ps.warnings ?? []), `Prompt size ≈${c.estTokens} tokens (${c.chars} chars, ${c.bytes} bytes) exceeds the conservative ${PROMPT_SIZE_WARN_TOKENS}-token warning threshold — the prompt may be approaching a model's context limit.`];
+            }
+        }
+    }
+    catch {
+        /* diagnostics must never sink the phase */
+    }
+}
+/** Attach aggregate input stats for a reduce phase: count + total bytes/chars/
+ *  estTokens over the completed `from[]` inputs being reduced. Stored on
+ *  `ps.promptStats.reduceInputs` so post-hoc inspection can account for input
+ *  size across reduce rounds. Never throws. */
+function attachReduceInputStats(ps, state, phase) {
+    try {
+        const s = reduceInputStats(state, phase);
+        const existing = ps.promptStats;
+        ps.promptStats = existing
+            ? { ...existing, reduceInputs: s }
+            : { calls: [], reduceInputs: s };
+    }
+    catch {
+        /* diagnostics must never sink the phase */
+    }
+}
+/** Format a single reduce-from input as a labeled section. */
+function formatReduceInput(id, output) {
+    return `### ${id}\n\n${output}`;
+}
+/** Aggregate completed `from[]` outputs for a reduce phase's {previous.output}.
+ *
+ *  BREAKING correction (dogfood issue 1): a reduce phase's {previous.output}
+ *  resolves to ALL completed `from[]` outputs in from-array order — not just
+ *  the last completed dependency. One completed input → its raw output.
+ *  Multiple → `### <id>\n\n<output>` sections joined by `\n\n---\n\n`.
+ *  `join:"any"` includes only completed branches (skipped/failed are omitted).
+ *
+ *  Returns `{ value, ids }` where `ids` are the from-ids actually aggregated
+ *  (so the runtime can record them as observed reads). `value` is undefined
+ *  when no `from[]` phase completed (e.g. all skipped under join:any). */
+function aggregateReduceFrom(state, phase) {
+    const fromIds = asArray(phase.from);
+    const completed = [];
+    for (const id of fromIds) {
+        const ps = state.phases[id];
+        if (ps?.status === "done" && ps.output !== undefined) {
+            completed.push({ id, output: ps.output });
+        }
+    }
+    if (completed.length === 0)
+        return { value: undefined, ids: [] };
+    if (completed.length === 1)
+        return { value: completed[0].output, ids: [completed[0].id] };
+    const value = completed.map((c) => formatReduceInput(c.id, c.output)).join("\n\n---\n\n");
+    return { value, ids: completed.map((c) => c.id) };
+}
+/** Aggregate stats over the completed `from[]` inputs for reduce diagnostics. */
+function reduceInputStats(state, phase) {
+    const fromIds = asArray(phase.from);
+    let count = 0;
+    let totalBytes = 0;
+    let totalChars = 0;
+    let totalEstTokens = 0;
+    for (const id of fromIds) {
+        const ps = state.phases[id];
+        if (ps?.status === "done" && ps.output !== undefined) {
+            count++;
+            const s = promptSizeStats(ps.output);
+            totalBytes += s.bytes;
+            totalChars += s.chars;
+            totalEstTokens += s.estTokens;
+        }
+    }
+    return { count, totalBytes, totalChars, totalEstTokens };
+}
+/** Resolve the effective idle-watchdog ms for a phase: phase overrides flow;
+ *  returns `undefined` when neither sets it (host default 300000 applies).
+ *  `0` is passed through (disables the watchdog — validation already ensured a
+ *  finite wall `timeout` exists in that case). */
+export function resolveIdleTimeoutMs(phase, def) {
+    const p = phase.idleTimeout;
+    if (typeof p === "number" && Number.isFinite(p))
+        return p;
+    const f = def.idleTimeout;
+    if (typeof f === "number" && Number.isFinite(f))
+        return f;
+    return undefined;
+}
 /** Stable cache identity for the fully resolved agent pool. File paths are
  * excluded: content/config, not installation location, determines output. */
 export function agentDefinitionsIdentity(agents) {
@@ -3567,6 +3904,8 @@ async function runTaskflowLayers(state, deps) {
     let gateBlocked = false;
     let gateReason = "";
     let gateOutput = "";
+    /** Id of the blocking gate/approval phase (source of `gateOutput`). */
+    let gatePhaseId;
     // `budgetBlocked` gates the skipping of remaining phases once the cap is hit
     // and also drives the terminal "blocked" status — a maxUSD ceiling must never
     // silently do nothing.
@@ -3674,6 +4013,7 @@ async function runTaskflowLayers(state, deps) {
                 gateBlocked = true;
                 gateReason = ps.gate.reason ?? "";
                 gateOutput = ps.output ?? "";
+                gatePhaseId = phase.id;
             }
             // A fan-out cut short by the cap is itself a budget skip.
             if (ps.budgetTruncated) {
@@ -3712,15 +4052,6 @@ async function runTaskflowLayers(state, deps) {
             break;
         }
     }
-    const fp = finalPhase(def.phases);
-    let finalState = state.phases[fp.id];
-    // If the designated final phase produced no output (skipped/blocked), fall
-    // back to the last phase (in definition order) that actually completed.
-    if (!finalState || finalState.status !== "done") {
-        const doneInOrder = def.phases.map((p) => state.phases[p.id]).filter((p) => p?.status === "done");
-        if (doneInOrder.length)
-            finalState = doneInOrder[doneInOrder.length - 1];
-    }
     // A failed non-optional phase fails the run; optional failures are tolerated.
     const anyFailed = Object.entries(state.phases).some(([id, p]) => p.status === "failed" && !byId.get(id)?.optional && !p.optional);
     state.status = aborted
@@ -3731,13 +4062,14 @@ async function runTaskflowLayers(state, deps) {
                 ? "failed"
                 : "completed";
     safeEmit(deps, state);
-    let finalOutput = finalState?.output ?? "(no output)";
-    if (gateBlocked) {
-        finalOutput = `Gate blocked the workflow.${gateReason ? `\nReason: ${gateReason}` : ""}${gateOutput ? `\n\n${gateOutput}` : ""}`;
-    }
-    else if (budgetBlocked) {
-        finalOutput = `Budget exceeded — run halted.${budgetReason ? `\nReason: ${budgetReason}` : ""}${finalState?.output ? `\n\n${finalState.output}` : ""}`;
-    }
+    const { finalOutput, outputSourcePhaseId } = resolveFinalOutput(def.phases, state, {
+        gate: gateBlocked,
+        gateReason,
+        gateOutput,
+        gatePhaseId,
+        budget: budgetBlocked,
+        budgetReason,
+    });
     const totalUsage = aggregateUsage(Object.values(state.phases).map((p) => p.usage ?? emptyUsage()));
     return {
         state,
@@ -3745,6 +4077,7 @@ async function runTaskflowLayers(state, deps) {
         ok: state.status === "completed",
         totalUsage,
         reuse: summarizeReuse(state),
+        outputSourcePhaseId,
     };
 }
 //# sourceMappingURL=runtime.js.map