@juzser/blacksmith 0.1.0

package/factory/orchestrator/dist/waveConcurrency.js

@@ -0,0 +1,250 @@
+import { foldAgents } from './agents-registry.js';
+/**
+ * Did the wave that was admitted N wide actually run N wide?
+ *
+ * `wave next` computes the widest wave a plan admits and `wave check` admits
+ * one. Both are statements about what MAY happen next: the first proposes, the
+ * second permits, and neither has any way of knowing what the dispatcher did
+ * afterwards. So a factory whose whole premise is "many subagents running the
+ * plan's tasks in parallel" could serialise every wave it ever admitted and
+ * say nothing about it — the admission would still be in the log, four ids
+ * wide, indistinguishable from a wave that genuinely ran four at once.
+ *
+ * That is the declarations-vs-state split this repo keeps drawing (AGENTS.md):
+ * `wave-admitted` is a declaration, and the only state that can answer it is
+ * when each agent was actually live. Both halves were already in the log —
+ * `dispatch_decision` opens an agent and its terminal event closes one, and
+ * agents-registry.ts already folds exactly that pair into intervals. So this
+ * is a fold over facts that were always there, not a new thing to record.
+ *
+ * It reuses `foldAgents` rather than reading `dispatch_decision` directly for
+ * the reason that fold documents (D-161): a dispatch superseded by a
+ * redispatch, or abandoned at `epic-closed`, has an end even though no
+ * terminal event names it, and reading the raw dispatches would leave those
+ * intervals open forever and score every wave after one as parallel.
+ */
+const ADMITTED_EVENT_TYPE = 'wave-admitted';
+/**
+ * Said when a wave was admitted and no agent was ever dispatched for it. The
+ * two readings are genuinely different problems and the operator has to pick
+ * between them by hand, so the hint names both rather than choosing.
+ */
+export const UNOBSERVED_HINT = 'A wave admitted with no dispatch_decision under any of its tasks ran nowhere this log can ' +
+    'see. Either the dispatcher never started it, or the agents ran outside the lineage that was ' +
+    'read — narrow with --epic, or check that the run wrote its dispatches to this state dir.';
+function readAdmission(event) {
+    const payload = event.record.payload;
+    const raw = payload.task_ids;
+    const taskIds = Array.isArray(raw) && raw.every((id) => typeof id === 'string' && id.length > 0)
+        ? raw
+        : null;
+    if (!taskIds || taskIds.length === 0) {
+        // Refused rather than read as a zero-wide wave: a malformed admission that
+        // audited clean is exactly the silence this command exists to end.
+        throw new Error(`wave-concurrency.missing-task-ids: wave-admitted "${event.event_id}" names no tasks`);
+    }
+    return {
+        eventId: event.event_id,
+        ts: event.record.ts,
+        // Never derived from the task ids. `emitWaveAdmitted` always writes this
+        // field, so an admission without one was hand-authored, and inventing the
+        // epic it probably meant would put a guess where the log has a gap.
+        epicId: typeof payload.epic_id === 'string' && payload.epic_id ? payload.epic_id : null,
+        taskIds,
+    };
+}
+/** Milliseconds, with an unclosed agent reaching forward without bound. */
+function endMs(endedAt) {
+    return endedAt === null ? Number.POSITIVE_INFINITY : Date.parse(endedAt);
+}
+/**
+ * The most intervals overlapping at one instant. Ends are processed before
+ * starts at the same timestamp, so a task that finishes exactly as the next
+ * one begins counts as a handoff and not as concurrency — without that, a
+ * dispatcher running strictly one task at a time would score `parallel` on
+ * nothing but the clock's granularity.
+ *
+ * Times are doubled first so that a run whose dispatch and terminal share a
+ * millisecond still gets a width of one tick instead of none. On the raw axis
+ * such a run is an empty interval, overlapping nothing — not even itself —
+ * and two admitted tasks would come back as a peak of zero, which is a claim
+ * about the clock dressed up as a claim about the factory.
+ */
+function peakOverlap(runs) {
+    const points = runs.flatMap((run) => {
+        const start = Date.parse(run.startedAt) * 2;
+        return [
+            { t: start, d: 1 },
+            { t: Math.max(endMs(run.endedAt) * 2, start + 1), d: -1 },
+        ];
+    });
+    // Subtraction would give NaN for two unclosed agents (Infinity - Infinity),
+    // and a NaN comparator silently leaves the array unsorted.
+    points.sort((a, b) => (a.t === b.t ? a.d - b.d : a.t < b.t ? -1 : 1));
+    let live = 0;
+    let peak = 0;
+    for (const point of points) {
+        live += point.d;
+        if (live > peak)
+            peak = live;
+    }
+    return peak;
+}
+function verdictFor(declared, observed, peak) {
+    if (declared <= 1)
+        return 'single';
+    if (observed === 0)
+        return 'unobserved';
+    if (peak >= declared)
+        return 'parallel';
+    if (peak <= 1)
+        return 'serialized';
+    return 'partial';
+}
+/**
+ * Fold one task's agents into the interval it was worked on. Every role counts,
+ * not just the coder's: a task whose reviewer is still running is still work
+ * in progress, and a wave holding it has not narrowed yet.
+ */
+function runFor(taskId, agents) {
+    if (agents.length === 0)
+        return null;
+    const ordered = [...agents].sort((a, b) => a.dispatchedAt.localeCompare(b.dispatchedAt));
+    const startedAt = ordered[0]?.dispatchedAt;
+    let endedAt = null;
+    for (const agent of ordered) {
+        // One unclosed agent leaves the whole task open — the task is only done
+        // being worked on when every role on it is.
+        if (agent.terminalAt === null)
+            return { taskId, startedAt, endedAt: null, roles: rolesOf(ordered) };
+        if (endedAt === null || agent.terminalAt > endedAt)
+            endedAt = agent.terminalAt;
+    }
+    return { taskId, startedAt, endedAt, roles: rolesOf(ordered) };
+}
+function rolesOf(ordered) {
+    const seen = new Set();
+    const roles = [];
+    for (const agent of ordered) {
+        if (seen.has(agent.agentRole))
+            continue;
+        seen.add(agent.agentRole);
+        roles.push(agent.agentRole);
+    }
+    return roles;
+}
+/**
+ * Every wave in the log, scored against what the log says it did.
+ *
+ * A task can be admitted more than once — a follow-up, a redispatch after a
+ * bounce — so each wave owns its tasks' agents only until the admission that
+ * re-opens them. Without that window, a later wave that genuinely ran wide
+ * would retro-fit its parallelism onto the earlier serial one that admitted
+ * the same task, and the command would report the opposite of the truth.
+ */
+export function auditWaveConcurrency(events, options = {}) {
+    const admissions = events
+        .filter((event) => event.record.event_type === ADMITTED_EVENT_TYPE)
+        .map(readAdmission)
+        .sort((a, b) => (a.ts === b.ts ? a.eventId.localeCompare(b.eventId) : a.ts < b.ts ? -1 : 1));
+    // Built from every admission, before the epic filter: a window closed by an
+    // admission the caller filtered out is still closed, and asking about one
+    // epic must not widen another epic's windows.
+    const admittedAtByTask = new Map();
+    for (const admission of admissions) {
+        for (const taskId of admission.taskIds) {
+            const list = admittedAtByTask.get(taskId);
+            if (list)
+                list.push(admission.ts);
+            else
+                admittedAtByTask.set(taskId, [admission.ts]);
+        }
+    }
+    const agentsByTask = new Map();
+    for (const agent of foldAgents(events)) {
+        if (!agent.taskId)
+            continue;
+        const list = agentsByTask.get(agent.taskId);
+        if (list)
+            list.push(agent);
+        else
+            agentsByTask.set(agent.taskId, [agent]);
+    }
+    const waves = [];
+    for (const admission of admissions) {
+        if (options.epicId !== undefined && admission.epicId !== options.epicId)
+            continue;
+        const observed = [];
+        const unobserved = [];
+        for (const taskId of admission.taskIds) {
+            const closesAt = (admittedAtByTask.get(taskId) ?? []).find((ts) => ts > admission.ts);
+            const run = runFor(taskId, (agentsByTask.get(taskId) ?? []).filter((agent) => 
+            // A run already under way when the wave was cut is not this wave's
+            // to claim; a run after the next admission belongs to that one.
+            agent.dispatchedAt >= admission.ts &&
+                (closesAt === undefined || agent.dispatchedAt < closesAt)));
+            if (run)
+                observed.push(run);
+            else
+                unobserved.push(taskId);
+        }
+        observed.sort((a, b) => a.startedAt.localeCompare(b.startedAt));
+        const peak = peakOverlap(observed);
+        waves.push({
+            eventId: admission.eventId,
+            admittedAt: admission.ts,
+            epicId: admission.epicId,
+            declared: admission.taskIds,
+            observed,
+            unobserved,
+            peak,
+            verdict: verdictFor(admission.taskIds.length, observed.length, peak),
+        });
+    }
+    return waves;
+}
+/** The handle an operator has on a wave: its epic, or its own id when it named none. */
+function labelOf(wave) {
+    return wave.epicId ?? wave.eventId;
+}
+function labelsWith(waves, verdict) {
+    const labels = [];
+    for (const wave of waves) {
+        if (wave.verdict !== verdict)
+            continue;
+        const label = labelOf(wave);
+        // Once per epic, not once per wave: an epic that serialised every wave it
+        // ever cut has one problem, and listing it eight times reads as eight.
+        if (!labels.includes(label))
+            labels.push(label);
+    }
+    return labels;
+}
+/**
+ * Score the audit.
+ *
+ * Exit 1 is `serialized` alone. A `partial` wave — three admitted, two in
+ * flight — is the factory working and is reported rather than failed: an exit
+ * code that cried about it would be routed to /dev/null inside a week, and
+ * then the serialized one would go with it.
+ *
+ * Exit 2 is the same shape `judge escalations` uses: nothing was judged. A
+ * wave the log holds no dispatch for is not a passing wave, and returning 0
+ * for it would make an empty state dir look like a healthy factory.
+ */
+export function summariseWaveConcurrency(waves) {
+    const serialized = labelsWith(waves, 'serialized');
+    const unobserved = labelsWith(waves, 'unobserved');
+    return {
+        waves: [...waves],
+        serialized,
+        partial: labelsWith(waves, 'partial'),
+        unobserved,
+        widest: {
+            declared: waves.reduce((max, wave) => Math.max(max, wave.declared.length), 0),
+            observed: waves.reduce((max, wave) => Math.max(max, wave.peak), 0),
+        },
+        hint: unobserved.length > 0 ? UNOBSERVED_HINT : '',
+        exitCode: serialized.length > 0 ? 1 : unobserved.length > 0 ? 2 : 0,
+    };
+}

package/factory/orchestrator/dist/waveNext.js

@@ -0,0 +1,210 @@
+/**
+ * The widest wave the graph allows, computed instead of guessed.
+ *
+ * `wave check` answers a closed question — may *these* task ids run together
+ * — and answers it well. But it only ever sees a set someone already picked,
+ * and the safest set to pick is always a set of one: a single task is
+ * pairwise-disjoint with nothing, shares no hotspot with nothing, and crosses
+ * no import edge with nothing, so it passes every gate in the file. The gate
+ * cannot tell a deliberate wave of one from an orchestrator that never
+ * thought to ask for more, and both come back `valid: true`. A factory whose
+ * whole claim is parallel execution therefore had no command that computes
+ * parallelism; it had a command that declines to forbid it.
+ *
+ * `waveLayers` in graph.ts already bands a plan by longest-path depth, and
+ * its docblock says the band means "these can run in parallel right now" —
+ * but nothing outside the Flow page's layout ever imported it, so the one
+ * function that knew the answer only ever drew it.
+ *
+ * This module closes that gap from the other end: given a plan, the live
+ * status of its tasks and the import-graph crossings between them, it
+ * returns the largest set that `wave check` would admit, plus a named reason
+ * for every task it left out. It is pure and it writes nothing. Admission
+ * stays where it was — `wave check` remains the single command that emits
+ * `wave-admitted`, so a proposal here still has to survive the gate that
+ * enforces it, and a bug in this file costs a rejected proposal rather than
+ * two agents in one worktree.
+ */
+import { claimsOverlap, readClaimList, readEdgeList, touchesSerializeAlways, } from './claims.js';
+import { topoSort } from './graph.js';
+import { livePlanTasks } from './plan.js';
+/**
+ * A task is *done* only at the two statuses epic.ts already calls terminal —
+ * `completed` and `waived`. Everything else non-terminal still holds a
+ * worktree, so its claims are still spoken for even when nobody is typing in
+ * it: `blocked`, `failed` and `escalated` are waiting on a person, not on
+ * nothing, and their uncommitted work is exactly what a second agent in the
+ * same paths would destroy.
+ */
+const TERMINAL_TASK_STATUSES = new Set(['completed', 'waived']);
+/** The two statuses that mean "nothing has been dispatched for this yet". */
+const CANDIDATE_TASK_STATUSES = new Set(['todo', 'ready']);
+function nameList(ids) {
+    return ids.join(', ');
+}
+/**
+ * Order the candidates so that when two of them are coupled, the one that
+ * must land first is the one offered admission. Plan edges and import
+ * crossings are the same shape of constraint here — "this one after that
+ * one" — so both feed one sort, and a coupled pair resolves the way the
+ * playbook already resolves it by hand: run the producer first.
+ *
+ * A cycle among the crossings is not this function's to diagnose (plan.ts
+ * rejects cyclic plan edges; import cycles are legal TypeScript), so it falls
+ * back to lexicographic order — an arbitrary but stable pick, which still
+ * admits one of the pair and defers the other with a reason.
+ */
+function admissionOrder(candidates, edges, crossings) {
+    const byId = new Map(candidates.map((t) => [t.task_id, t]));
+    const ids = [...byId.keys()].sort();
+    const ordering = [
+        ...edges,
+        ...crossings.map((c) => ({ task: c.consumer, dependsOn: c.producer })),
+    ];
+    const sorted = topoSort(ids, ordering);
+    const order = sorted.ok ? sorted.order : ids;
+    return order.flatMap((id) => {
+        const task = byId.get(id);
+        return task ? [task] : []; // provably total: topoSort returns only ids it was given
+    });
+}
+/**
+ * Every live task in the plan, with its claims read as a list of globs.
+ *
+ * Exists because a caller has to hand `waveImpact` a readable claim set
+ * before `computeNextWave` runs, and there must not be a second, laxer way to
+ * obtain one. `readClaimList` is the door `wave check` refuses through; a CLI
+ * that reached past it — `(t.claims ?? []) as string[]` is the obvious
+ * shortcut — would hand the symbol graph a claims string to iterate by
+ * character, and a task claiming nothing crosses nobody. The wave would then
+ * be admitted for the one reason it must not be: the check could not read it.
+ *
+ * Terminal tasks are kept. The graph is built over the whole live plan
+ * because a crossing with an in-flight task is exactly the crossing that has
+ * to defer a candidate, and a caller cannot know which tasks are in flight
+ * until `computeNextWave` has partitioned them by status.
+ */
+export function liveWaveTasks(plan) {
+    return livePlanTasks(plan).map((record) => readClaimList({
+        task_id: record.task_id,
+        claims: record.claims,
+    }));
+}
+export function computeNextWave(input) {
+    const { plan, policy } = input;
+    const crossings = input.crossings ?? [];
+    const edges = readEdgeList(plan.edges);
+    const done = [];
+    const occupied = [];
+    const occupiedTasks = [];
+    const candidates = [];
+    for (const record of livePlanTasks(plan)) {
+        const id = record.task_id;
+        const status = input.statusById?.get(id) ?? String(record.task_status);
+        if (TERMINAL_TASK_STATUSES.has(status)) {
+            done.push(id);
+            continue;
+        }
+        // Past this door claims are a real string[], for a candidate and for a
+        // task merely holding ground — the wave is unanswerable either way.
+        const task = readClaimList({ task_id: id, claims: record.claims });
+        if (CANDIDATE_TASK_STATUSES.has(status)) {
+            candidates.push(task);
+        }
+        else {
+            occupied.push(id);
+            occupiedTasks.push(task);
+        }
+    }
+    done.sort();
+    occupied.sort();
+    const doneSet = new Set(done);
+    const dependsByTask = new Map();
+    for (const edge of edges) {
+        const list = dependsByTask.get(edge.task) ?? [];
+        list.push(edge.dependsOn);
+        dependsByTask.set(edge.task, list);
+    }
+    const coupledWith = new Map();
+    const link = (a, b, role) => {
+        const map = coupledWith.get(a) ?? new Map();
+        map.set(b, role);
+        coupledWith.set(a, map);
+    };
+    for (const crossing of crossings) {
+        link(crossing.consumer, crossing.producer, 'consumes');
+        link(crossing.producer, crossing.consumer, 'produces');
+    }
+    const admitted = [];
+    const deferred = [];
+    const defer = (taskId, reason, blockedBy, detail) => {
+        deferred.push({ taskId, reason, blockedBy: [...blockedBy].sort(), detail });
+    };
+    for (const task of admissionOrder(candidates, edges, crossings)) {
+        const id = task.task_id;
+        const pending = [...new Set(dependsByTask.get(id) ?? [])].filter((d) => !doneSet.has(d)).sort();
+        if (pending.length > 0) {
+            defer(id, 'dependency-pending', pending, `Depends on ${nameList(pending)}, which ${pending.length === 1 ? 'is' : 'are'} not terminal.`);
+            continue;
+        }
+        // Occupied tasks hold their claims for the same reason admitted ones do:
+        // a worktree exists and its edits are not merged.
+        const holders = [...admitted, ...occupiedTasks];
+        const overlapping = [];
+        let overlapDetail = '';
+        for (const holder of holders) {
+            const overlap = claimsOverlap(task, holder);
+            if (!overlap.overlaps)
+                continue;
+            overlapping.push(holder.task_id);
+            const pair = overlap.offendingGlobs[0];
+            if (overlapDetail === '' && pair !== undefined) {
+                overlapDetail = `Claims overlap ${holder.task_id} (${pair.globA} vs ${pair.globB}).`;
+            }
+        }
+        if (overlapping.length > 0) {
+            defer(id, 'claim-overlap', overlapping, overlapDetail);
+            continue;
+        }
+        const hotspots = touchesSerializeAlways(task, policy.serializeAlwaysGlobs);
+        const sharing = [];
+        let hotspotDetail = '';
+        if (hotspots.length > 0) {
+            for (const holder of holders) {
+                const glob = touchesSerializeAlways(holder, hotspots)[0];
+                if (glob === undefined)
+                    continue;
+                sharing.push(holder.task_id);
+                if (hotspotDetail === '') {
+                    hotspotDetail =
+                        `Shares the serialize-always glob ${glob} with ${holder.task_id}, ` +
+                            'which worktree.yml never schedules concurrently.';
+                }
+            }
+        }
+        if (sharing.length > 0) {
+            defer(id, 'serialize-hotspot', sharing, hotspotDetail);
+            continue;
+        }
+        const couplings = coupledWith.get(id);
+        const coupled = couplings ? holders.filter((h) => couplings.has(h.task_id)) : [];
+        const blocker = coupled[0];
+        if (couplings !== undefined && blocker !== undefined) {
+            const detail = couplings.get(blocker.task_id) === 'consumes'
+                ? `Imports symbols from ${blocker.task_id}, which has not merged: the producer runs first.`
+                : `${blocker.task_id} imports symbols from it and is already scheduled, so this one follows.`;
+            defer(id, 'symbol-coupled', coupled.map((h) => h.task_id), detail);
+            continue;
+        }
+        admitted.push(task);
+    }
+    deferred.sort((a, b) => a.taskId.localeCompare(b.taskId));
+    return {
+        epicId: plan.epic_id,
+        wave: admitted.map((t) => t.task_id),
+        deferred,
+        done,
+        occupied,
+        remaining: deferred.length + occupied.length,
+    };
+}

package/factory/orchestrator/dist/waveSchedule.js

@@ -0,0 +1,146 @@
+/**
+ * How wide this plan can *ever* run, answered before an agent is dispatched.
+ *
+ * The factory now brackets parallelism from two sides and neither one reaches
+ * the plan. `wave check` certifies that a set someone already picked *could*
+ * run together; `wave audit` reads the log afterwards and reports whether it
+ * *did*. Both take the plan as given. But a plan whose tasks all claim
+ * overlapping globs has a ceiling of one no matter how many agents are
+ * available, and a planner that sliced it that way gets the same silent
+ * `valid: true` from every gate downstream — each wave of one is admitted,
+ * each run of one is faithful to its admission, and the epic serializes with
+ * nothing anywhere reporting a problem. The cost is paid at plan time and
+ * every check that could have named it runs too late to matter.
+ *
+ * So this module replays the dispatcher against the plan. It calls the same
+ * pure `computeNextWave` the real wave loop calls, marks the returned wave
+ * terminal, and calls it again until nothing more can start. What comes back
+ * is the number of rounds the plan needs and the widest round it ever gets --
+ * computed by the containment code itself, so the ceiling reported here is
+ * the ceiling the dispatcher will actually hit, not a second opinion about
+ * it that can drift.
+ *
+ * The one distinction that makes the output actionable: a task deferred
+ * `dependency-pending` is waiting on work it genuinely needs, and that is the
+ * shape of the problem, not a defect — a chain of five real dependencies
+ * takes five rounds and no re-slicing changes it. A task deferred for any
+ * other reason had its dependencies satisfied, was ready to run that round,
+ * and was held back purely by how the planner drew the claims. Only the
+ * second kind is anybody's to fix, so only the second kind is reported as a
+ * constraint.
+ *
+ * What this deliberately does not do is claim a counterfactual. It never says
+ * "re-slice these claims and the plan runs in three rounds instead of five",
+ * because knowing that would mean inventing the claim geometry the planner
+ * would have written instead, and the dependency graph may simply bind next.
+ * It names which tasks were held back, by whom, and in which round. Deciding
+ * whether that is worth re-planning is the operator's, and the numbers are
+ * there to decide on.
+ *
+ * Pure, and it writes nothing. Like `waveNext`, admission stays where it was:
+ * a round simulated here has been admitted by nobody.
+ */
+import { computeNextWave, } from './waveNext.js';
+/**
+ * Reported in this order, which is the order `computeNextWave` tests them in.
+ * `dependency-pending` is absent on purpose — it is the one reason that is
+ * never a finding.
+ */
+const AVOIDABLE_REASONS = [
+    'claim-overlap',
+    'serialize-hotspot',
+    'symbol-coupled',
+];
+function nameList(ids) {
+    return ids.join(', ');
+}
+function buildHint(stalled, occupied, constraints, depth) {
+    if (stalled.length > 0) {
+        const held = constraints.flatMap((c) => c.blockedBy).filter((id) => occupied.includes(id));
+        const because = held.length > 0
+            ? ` ${nameList([...new Set(held)].sort())} still holds claims and is waiting on a person, not on the schedule.`
+            : '';
+        return (`The schedule stalls: ${nameList(stalled)} can never start, ` +
+            `so ${stalled.length === 1 ? 'that task' : 'those tasks'} will not run as this plan is written.${because}`);
+    }
+    if (constraints.length > 0) {
+        const reasons = constraints.map((c) => c.reason);
+        return (`This plan runs in ${depth} ${depth === 1 ? 'round' : 'rounds'}, and some of that ` +
+            `depth is claim geometry rather than dependencies (${nameList(reasons)}). ` +
+            'Re-slicing the claims may widen it; whether it does depends on the dependency graph, ' +
+            'which this command does not speculate about.');
+    }
+    return '';
+}
+/**
+ * Replay the wave loop against a plan until nothing more can start.
+ *
+ * Termination is structural, not capped: every iteration either admits at
+ * least one task — which is then marked terminal, strictly shrinking the
+ * candidate set — or admits none, and the loop ends. So it runs at most
+ * once per task plus the final unproductive round that proves there is
+ * nothing left.
+ */
+export function scheduleWaves(input) {
+    // A copy, because a caller's status register is theirs and this simulation
+    // completes tasks that have not been dispatched.
+    const statusById = new Map(input.statusById ?? []);
+    const rounds = [];
+    const accumulators = new Map();
+    let epicId = input.plan.epic_id;
+    let stalled = [];
+    let occupied = [];
+    for (;;) {
+        const result = computeNextWave({ ...input, statusById });
+        epicId = result.epicId;
+        occupied = result.occupied;
+        const avoidable = result.deferred.filter((d) => d.reason !== 'dependency-pending');
+        for (const deferral of avoidable) {
+            const acc = accumulators.get(deferral.reason) ?? {
+                tasks: new Set(),
+                blockedBy: new Set(),
+                detail: deferral.detail,
+            };
+            acc.tasks.add(deferral.taskId);
+            for (const holder of deferral.blockedBy)
+                acc.blockedBy.add(holder);
+            accumulators.set(deferral.reason, acc);
+        }
+        if (result.wave.length === 0) {
+            // The round that starts nothing is the round that names the stall:
+            // anything still deferred here is a candidate no later round reaches.
+            stalled = result.deferred.map((d) => d.taskId).sort();
+            break;
+        }
+        rounds.push({ round: rounds.length + 1, tasks: result.wave, avoidable });
+        for (const taskId of result.wave)
+            statusById.set(taskId, 'completed');
+    }
+    const constraints = AVOIDABLE_REASONS.flatMap((reason) => {
+        const acc = accumulators.get(reason);
+        if (acc === undefined)
+            return [];
+        return [
+            {
+                reason,
+                tasks: [...acc.tasks].sort(),
+                blockedBy: [...acc.blockedBy].sort(),
+                detail: acc.detail,
+            },
+        ];
+    });
+    const depth = rounds.length;
+    const hint = buildHint(stalled, occupied, constraints, depth);
+    return {
+        epicId,
+        rounds,
+        depth,
+        widest: rounds.reduce((max, r) => Math.max(max, r.tasks.length), 0),
+        scheduled: rounds.reduce((total, r) => total + r.tasks.length, 0),
+        stalled,
+        occupied,
+        constraints,
+        hint,
+        exitCode: stalled.length > 0 ? 1 : constraints.length > 0 ? 2 : 0,
+    };
+}