@wildorder/nightshift 0.16.0 → 0.18.0

package/dist/run-analytics-report.js

@@ -0,0 +1,1242 @@
+import { BUCKETS, KNOWN_OUTCOMES, KNOWN_WAIT_CAUSES, SCHEDULING_POINT_KINDS, } from "./run-analytics.js";
+function compareIntervals(a, b) {
+    return a.start - b.start || a.end - b.end || a.span.id.localeCompare(b.span.id);
+}
+function attemptKeyOf(dims) {
+    if (dims.workstream === undefined || dims.attemptSeat === undefined || dims.attemptIndex === undefined) {
+        return undefined;
+    }
+    return `${dims.workstream} ${dims.attemptSeat} ${dims.attemptIndex}`;
+}
+function bump(map, key, durationMs) {
+    const cur = map.get(key) ?? { count: 0, durationMs: 0 };
+    cur.count += 1;
+    cur.durationMs += durationMs;
+    map.set(key, cur);
+}
+function rankedFromGroups(map) {
+    return [...map.entries()]
+        .map(([key, v]) => ({ key, durationMs: v.durationMs, count: v.count }))
+        .sort((a, b) => b.durationMs - a.durationMs || a.key.localeCompare(b.key));
+}
+/**
+ * Walks a span's `parentId` chain until it reaches a top-level span id.
+ * Returns `undefined` for an orphan chain (a dangling `parentId` — already
+ * flagged as its own diagnostic — or a chain that never reaches a top-level
+ * ancestor), never throws, and is bounded against a cyclic `parentId` a
+ * malformed artifact might otherwise loop on forever.
+ */
+function findTopLevelAncestor(span, byId, topLevelIds) {
+    let parentId = span.parentId;
+    let hops = 0;
+    while (parentId !== undefined && hops < 10_000) {
+        if (topLevelIds.has(parentId))
+            return parentId;
+        const parent = byId.get(parentId);
+        if (parent === undefined)
+            return undefined;
+        parentId = parent.parentId;
+        hops += 1;
+    }
+    return undefined;
+}
+/**
+ * Sweeps the sorted endpoints of every top-level interval and assigns each
+ * covered elementary sub-interval to exactly one owner — the covering span
+ * that sorts first by `(startOffsetMs, endOffsetMs, id)` — so
+ * `Σ(bucket durations)` equals the interval union exactly, even when
+ * top-level spans overlap (D2).
+ *
+ * An `overlap` diagnostic fires only when at least two of the covering spans
+ * share the same *defined* `dimensions.workstream` (§3.2): a workstream's own
+ * stages are sequential by construction, so overlap within one workstream is
+ * still a bug worth a note. Overlap between different workstreams — or
+ * involving a span with no workstream at all — is the expected shape of a
+ * concurrent run and produces no diagnostic. Top-level spans are direct
+ * children of the `run` span, which itself carries no workstream (WS-01), so
+ * a top-level span's own `dimensions.workstream` already *is* its effective
+ * workstream — no ancestor walk is needed here.
+ */
+function sweepBucketOwnership(intervals, diagnostics) {
+    const totals = new Map(BUCKETS.map((bucket) => [bucket, 0]));
+    if (intervals.length === 0)
+        return totals;
+    const boundarySet = new Set();
+    for (const interval of intervals) {
+        boundarySet.add(interval.start);
+        boundarySet.add(interval.end);
+    }
+    const boundaries = [...boundarySet].sort((a, b) => a - b);
+    const seenOverlaps = new Set();
+    for (let i = 0; i < boundaries.length - 1; i++) {
+        const a = boundaries[i];
+        const b = boundaries[i + 1];
+        if (b <= a)
+            continue;
+        const covering = intervals.filter((interval) => interval.start <= a && interval.end >= b);
+        if (covering.length === 0)
+            continue;
+        covering.sort(compareIntervals);
+        const owner = covering[0];
+        totals.set(owner.span.bucket, (totals.get(owner.span.bucket) ?? 0) + (b - a));
+        if (covering.length > 1) {
+            const workstreams = new Set(covering.map((interval) => interval.span.dimensions.workstream).filter((ws) => ws !== undefined));
+            const sameWorkstream = [...workstreams].find((ws) => covering.filter((interval) => interval.span.dimensions.workstream === ws).length > 1);
+            if (sameWorkstream !== undefined) {
+                const ids = covering.map((interval) => interval.span.id).sort();
+                const key = ids.join(",");
+                if (!seenOverlaps.has(key)) {
+                    seenOverlaps.add(key);
+                    diagnostics.push({
+                        kind: "overlap",
+                        message: `${sameWorkstream}'s top-level spans overlap in [${a}, ${b}]ms: ${ids.join(", ")} — ` +
+                            `attributed once, to ${owner.span.id} (${owner.span.bucket})`,
+                        spanIds: ids,
+                    });
+                }
+            }
+        }
+    }
+    return totals;
+}
+// ---------------------------------------------------------------------------
+// WS-06: scheduling-observation reconciliation, the derived dependency-landing
+// wait, the concurrency sweep, and the critical-path walk.
+// ---------------------------------------------------------------------------
+/** Two adjacent-but-distinct `monotonic()` reads can differ by a scheduler
+ *  tick; this is orders of magnitude below any wait worth reporting and
+ *  orders of magnitude above that jitter (§3.5). */
+const SCHEDULING_IDENTITY_TOLERANCE_MS = 50;
+const SCHEDULING_POINT_KIND_SET = new Set(SCHEDULING_POINT_KINDS);
+function isFiniteNonNegative(value) {
+    return value !== undefined && Number.isFinite(value) && value >= 0;
+}
+/**
+ * Reconciles the three `SCHEDULING_POINT_KINDS` points into a per-workstream
+ * schedule, fail-open (§3.5): every malformed or contradictory observation is
+ * diagnosed and either skipped (malformed) or summed/kept-earliest-or-latest
+ * (a genuine duplicate) — never silently dropped, never thrown.
+ */
+function reconcileScheduling(artifact, diagnostics) {
+    const readyPoints = new Map();
+    const scheduledPoints = new Map();
+    const waitPoints = new Map(); // key: `${workstream} ${cause}`
+    for (const point of artifact.points) {
+        if (!SCHEDULING_POINT_KIND_SET.has(point.kind))
+            continue;
+        const workstream = point.dimensions?.workstream;
+        if (workstream === undefined) {
+            diagnostics.push({
+                kind: "scheduling-observation",
+                message: `${point.kind} point ${point.id} has no dimensions.workstream and cannot be attributed to any subject — skipped`,
+                spanIds: [],
+                pointIds: [point.id],
+            });
+            continue;
+        }
+        if (point.kind === "workstream-waiting") {
+            const cause = point.dimensions?.waitCause;
+            const value = point.value;
+            if (cause === undefined || !isFiniteNonNegative(value)) {
+                diagnostics.push({
+                    kind: "scheduling-observation",
+                    message: `workstream-waiting point ${point.id} for ${workstream} has no waitCause, or a missing/negative/non-finite ` +
+                        "value — skipped",
+                    spanIds: [],
+                    pointIds: [point.id],
+                });
+                continue;
+            }
+            const key = `${workstream} ${cause}`;
+            const list = waitPoints.get(key) ?? [];
+            list.push({ pointId: point.id, atOffsetMs: point.atOffsetMs, waitedMs: value });
+            waitPoints.set(key, list);
+        }
+        else {
+            if (!isFiniteNonNegative(point.atOffsetMs)) {
+                diagnostics.push({
+                    kind: "scheduling-observation",
+                    message: `${point.kind} point ${point.id} for ${workstream} has a missing, negative, or non-finite atOffsetMs — skipped`,
+                    spanIds: [],
+                    pointIds: [point.id],
+                });
+                continue;
+            }
+            const map = point.kind === "workstream-ready" ? readyPoints : scheduledPoints;
+            const list = map.get(workstream) ?? [];
+            list.push({ pointId: point.id, atOffsetMs: point.atOffsetMs });
+            map.set(workstream, list);
+        }
+    }
+    function resolveInstant(list, pick) {
+        const sorted = [...list].sort((a, b) => a.atOffsetMs - b.atOffsetMs || a.pointId.localeCompare(b.pointId));
+        return pick === "earliest" ? sorted[0] : sorted[sorted.length - 1];
+    }
+    const readyByWorkstream = new Map();
+    for (const [workstream, list] of readyPoints) {
+        if (list.length > 1) {
+            diagnostics.push({
+                kind: "duplicate-scheduling-point",
+                message: `workstream ${workstream} emitted ${list.length} workstream-ready points; the earliest is kept and the rest diagnosed`,
+                spanIds: [],
+                pointIds: [...list.map((p) => p.pointId)].sort(),
+            });
+        }
+        readyByWorkstream.set(workstream, resolveInstant(list, "earliest"));
+    }
+    const scheduledByWorkstream = new Map();
+    for (const [workstream, list] of scheduledPoints) {
+        if (list.length > 1) {
+            diagnostics.push({
+                kind: "duplicate-scheduling-point",
+                message: `workstream ${workstream} emitted ${list.length} workstream-scheduled points; the latest is kept and the rest diagnosed`,
+                spanIds: [],
+                pointIds: [...list.map((p) => p.pointId)].sort(),
+            });
+        }
+        scheduledByWorkstream.set(workstream, resolveInstant(list, "latest"));
+    }
+    const resolvedWaits = [];
+    for (const [key, list] of waitPoints) {
+        const sep = key.indexOf(" ");
+        const workstream = key.slice(0, sep);
+        const cause = key.slice(sep + 1);
+        if (list.length > 1) {
+            diagnostics.push({
+                kind: "duplicate-scheduling-point",
+                message: `workstream ${workstream} emitted ${list.length} workstream-waiting points for cause "${cause}"; ` +
+                    "their durations were summed and the anomaly diagnosed",
+                spanIds: [],
+                pointIds: [...list.map((p) => p.pointId)].sort(),
+            });
+        }
+        const waitedMs = list.reduce((sum, p) => sum + p.waitedMs, 0);
+        const endMs = list.reduce((max, p) => Math.max(max, p.atOffsetMs), 0);
+        resolvedWaits.push({
+            workstream,
+            cause,
+            waitedMs,
+            endMs,
+            derived: false,
+            pointIds: [...list.map((p) => p.pointId)].sort(),
+        });
+    }
+    const allScheduleWorkstreams = new Set([
+        ...readyByWorkstream.keys(),
+        ...scheduledByWorkstream.keys(),
+        ...resolvedWaits.map((w) => w.workstream),
+    ]);
+    // The `scheduled − ready === concurrency-cap` identity (rule 4, §3.3).
+    for (const workstream of allScheduleWorkstreams) {
+        const ready = readyByWorkstream.get(workstream);
+        const scheduled = scheduledByWorkstream.get(workstream);
+        if (scheduled === undefined)
+            continue;
+        if (ready === undefined) {
+            diagnostics.push({
+                kind: "scheduling-identity",
+                message: `workstream ${workstream} has a workstream-scheduled point with no matching workstream-ready point`,
+                spanIds: [],
+                pointIds: [scheduled.pointId],
+            });
+            continue;
+        }
+        const capWaitMs = resolvedWaits.find((w) => w.workstream === workstream && w.cause === "concurrency-cap")?.waitedMs ?? 0;
+        const diff = scheduled.atOffsetMs - ready.atOffsetMs;
+        if (Math.abs(diff - capWaitMs) > SCHEDULING_IDENTITY_TOLERANCE_MS) {
+            diagnostics.push({
+                kind: "scheduling-identity",
+                message: `workstream ${workstream}: scheduled − ready is ${diff}ms but the concurrency-cap wait is ${capWaitMs}ms ` +
+                    `(beyond the ${SCHEDULING_IDENTITY_TOLERANCE_MS}ms tolerance)`,
+                spanIds: [],
+                pointIds: [ready.pointId, scheduled.pointId],
+            });
+        }
+    }
+    // The derived `dependency-landing` wait (§3.4).
+    const depsReadyByWorkstream = new Map();
+    for (const [workstream, ready] of readyByWorkstream) {
+        const specPendingMs = resolvedWaits.find((w) => w.workstream === workstream && w.cause === "spec-pending")?.waitedMs ?? 0;
+        depsReadyByWorkstream.set(workstream, ready.atOffsetMs - specPendingMs);
+    }
+    const schedulerStartMs = depsReadyByWorkstream.size > 0 ? Math.min(...depsReadyByWorkstream.values()) : undefined;
+    const derivedWaits = [];
+    if (schedulerStartMs !== undefined) {
+        for (const [workstream, depsReadyMs] of [...depsReadyByWorkstream].sort(([a], [b]) => a.localeCompare(b))) {
+            const landingMs = Math.max(0, depsReadyMs - schedulerStartMs);
+            if (landingMs > 0) {
+                derivedWaits.push({ workstream, cause: "dependency-landing", waitedMs: landingMs, endMs: depsReadyMs, derived: true, pointIds: [] });
+            }
+        }
+    }
+    const allWaits = [...resolvedWaits, ...derivedWaits];
+    const scheduleWorkstreams = new Set([...allScheduleWorkstreams, ...derivedWaits.map((w) => w.workstream)]);
+    const schedules = [...scheduleWorkstreams].sort().map((workstream) => {
+        const ready = readyByWorkstream.get(workstream);
+        const scheduled = scheduledByWorkstream.get(workstream);
+        const depsReadyMs = depsReadyByWorkstream.get(workstream);
+        const waits = allWaits
+            .filter((w) => w.workstream === workstream)
+            .sort((a, b) => a.cause.localeCompare(b.cause))
+            .map((w) => ({
+            workstream: w.workstream,
+            cause: w.cause,
+            waitedMs: w.waitedMs,
+            endMs: w.endMs,
+            derived: w.derived,
+            ...(!w.derived && w.pointIds.length > 0 ? { pointId: w.pointIds[0] } : {}),
+        }));
+        return {
+            workstream,
+            ...(ready !== undefined ? { readyMs: ready.atOffsetMs } : {}),
+            ...(depsReadyMs !== undefined ? { depsReadyMs } : {}),
+            ...(scheduled !== undefined ? { scheduledMs: scheduled.atOffsetMs } : {}),
+            ...(ready !== undefined && scheduled !== undefined ? { queuedMs: scheduled.atOffsetMs - ready.atOffsetMs } : {}),
+            waits,
+        };
+    });
+    function waitCauseTier(cause) {
+        if (KNOWN_WAIT_CAUSES.includes(cause))
+            return 0;
+        if (cause === "dependency-landing")
+            return 1;
+        return 2;
+    }
+    const causeTotals = new Map();
+    for (const w of allWaits) {
+        const entry = causeTotals.get(w.cause) ?? { totalMs: 0, workstreams: new Set(), derived: w.derived };
+        entry.totalMs += w.waitedMs;
+        entry.workstreams.add(w.workstream);
+        causeTotals.set(w.cause, entry);
+    }
+    const waitsByCause = [...causeTotals.entries()]
+        .map(([cause, v]) => ({ cause, totalMs: v.totalMs, workstreams: v.workstreams.size, derived: v.derived }))
+        .sort((a, b) => {
+        const tierDiff = waitCauseTier(a.cause) - waitCauseTier(b.cause);
+        if (tierDiff !== 0)
+            return tierDiff;
+        if (waitCauseTier(a.cause) === 0) {
+            return KNOWN_WAIT_CAUSES.indexOf(a.cause) - KNOWN_WAIT_CAUSES.indexOf(b.cause);
+        }
+        return a.cause.localeCompare(b.cause);
+    });
+    return { schedules, waitsByCause, ...(schedulerStartMs !== undefined ? { schedulerStartMs } : {}), allWaits };
+}
+/**
+ * Time-weighted distribution of how many *distinct* workstreams were live at
+ * once (§3.7), over top-level intervals that carry a `workstream` — run-level
+ * spans are excluded entirely. Reuses the boundary-sweep technique from
+ * `sweepBucketOwnership`, counting distinct workstream ids rather than spans
+ * so a same-workstream overlap (already diagnosed in §3.2) is never counted
+ * as parallelism.
+ */
+function sweepWorkstreamConcurrency(topLevelIntervals) {
+    const withWorkstream = topLevelIntervals.filter((interval) => interval.span.dimensions.workstream !== undefined);
+    const cumulativeWorkstreamMs = withWorkstream.reduce((sum, interval) => sum + (interval.end - interval.start), 0);
+    if (withWorkstream.length === 0) {
+        return { meanWorkstreamConcurrency: 0, peakWorkstreamConcurrency: 0, overlappedMs: 0, cumulativeWorkstreamMs: 0 };
+    }
+    const boundarySet = new Set();
+    for (const interval of withWorkstream) {
+        boundarySet.add(interval.start);
+        boundarySet.add(interval.end);
+    }
+    const boundaries = [...boundarySet].sort((a, b) => a - b);
+    let peak = 0;
+    let overlappedMs = 0;
+    let weightedSum = 0;
+    let coveredLength = 0;
+    for (let i = 0; i < boundaries.length - 1; i++) {
+        const a = boundaries[i];
+        const b = boundaries[i + 1];
+        if (b <= a)
+            continue;
+        const distinct = new Set(withWorkstream.filter((interval) => interval.start <= a && interval.end >= b).map((interval) => interval.span.dimensions.workstream));
+        const count = distinct.size;
+        if (count === 0)
+            continue;
+        const length = b - a;
+        peak = Math.max(peak, count);
+        if (count >= 2)
+            overlappedMs += length;
+        weightedSum += count * length;
+        coveredLength += length;
+    }
+    const meanWorkstreamConcurrency = coveredLength > 0 ? weightedSum / coveredLength : 0;
+    return { meanWorkstreamConcurrency, peakWorkstreamConcurrency: peak, overlappedMs, cumulativeWorkstreamMs };
+}
+function ownerKeyOf(workstream) {
+    return workstream ?? "\u0000run-level";
+}
+function covers(start, end, cursor) {
+    return start < cursor && end >= cursor;
+}
+/**
+ * Backward walk from the end of the run (§3.6): at each step, either the
+ * current owner's own work explains the instant before the cursor (step 1),
+ * or another flow was holding the clock instead — the *truthful* leg for a
+ * cap/mutex wait, since somebody else was running, not nobody (step 2) — or,
+ * only when nothing at all was running, a genuine idle wait (step 3) — or,
+ * failing all three, an unexplained gap (step 4). Every branch strictly
+ * decreases the cursor, and an explicit `budget` backstops pathological
+ * input against a hang or a silently truncated path.
+ */
+function computeCriticalPath(topLevelIntervals, allWaits, totalElapsedMs) {
+    // `start` is clamped into [0, totalElapsedMs] defensively: a well-formed
+    // artifact never has a negative startOffsetMs, but a pathological one must
+    // still tile [0, totalElapsedMs) exactly rather than producing a leg whose
+    // startMs is negative.
+    const stages = topLevelIntervals.map((interval) => ({
+        kind: "stage",
+        workstream: interval.span.dimensions.workstream,
+        stage: interval.span.stage,
+        spanId: interval.span.id,
+        start: Math.min(Math.max(interval.start, 0), totalElapsedMs),
+        end: Math.min(Math.max(interval.end, 0), totalElapsedMs),
+    }));
+    const waits = allWaits
+        .map((w) => {
+        const rawStart = w.endMs - w.waitedMs;
+        const start = Math.min(Math.max(rawStart, 0), totalElapsedMs);
+        const end = Math.min(Math.max(w.endMs, 0), totalElapsedMs);
+        return {
+            workstream: w.workstream,
+            cause: w.cause,
+            pointId: w.derived ? undefined : w.pointIds[0],
+            derived: w.derived,
+            start,
+            end,
+        };
+    })
+        .filter((w) => w.end > w.start);
+    const allEnds = [...stages.map((s) => s.end), ...waits.map((w) => w.end)];
+    const legs = [];
+    let cursor = totalElapsedMs;
+    let owner;
+    let budget = stages.length + waits.length + 8;
+    while (cursor > 0 && budget-- > 0) {
+        const ownerKey = ownerKeyOf(owner);
+        // Step 1: the owner's own work explains it.
+        let step1;
+        for (const s of stages) {
+            if (ownerKeyOf(s.workstream) !== ownerKey || !covers(s.start, s.end, cursor))
+                continue;
+            if (step1 === undefined ||
+                s.start > step1.start ||
+                (s.start === step1.start && (s.end < step1.end || (s.end === step1.end && s.spanId < step1.spanId)))) {
+                step1 = s;
+            }
+        }
+        if (step1 !== undefined) {
+            legs.push({
+                startMs: step1.start,
+                endMs: cursor,
+                durationMs: cursor - step1.start,
+                kind: "stage",
+                ...(step1.workstream !== undefined ? { workstream: step1.workstream } : {}),
+                stage: step1.stage,
+                spanId: step1.spanId,
+            });
+            cursor = step1.start;
+            continue;
+        }
+        // Step 2: somebody else held the clock.
+        let step2;
+        for (const s of stages) {
+            if (ownerKeyOf(s.workstream) === ownerKey || !covers(s.start, s.end, cursor))
+                continue;
+            if (step2 === undefined ||
+                s.end < step2.end ||
+                (s.end === step2.end && (s.start > step2.start || (s.start === step2.start && s.spanId < step2.spanId)))) {
+                step2 = s;
+            }
+        }
+        if (step2 !== undefined) {
+            const ownerWait = owner === undefined
+                ? undefined
+                : waits
+                    .filter((w) => w.workstream === owner && covers(w.start, w.end, cursor))
+                    .sort((a, b) => b.start - a.start || a.end - b.end || a.cause.localeCompare(b.cause))[0];
+            const previousLeg = legs.length > 0 ? legs[legs.length - 1] : undefined;
+            if (previousLeg !== undefined && previousLeg.kind !== "gap") {
+                previousLeg.handoff = {
+                    ...(step2.workstream !== undefined ? { fromWorkstream: step2.workstream } : {}),
+                    cause: ownerWait?.cause ?? "concurrent-work",
+                    causeObserved: ownerWait !== undefined,
+                    ...(ownerWait?.pointId !== undefined ? { pointId: ownerWait.pointId } : {}),
+                };
+            }
+            legs.push({
+                startMs: step2.start,
+                endMs: cursor,
+                durationMs: cursor - step2.start,
+                kind: "stage",
+                ...(step2.workstream !== undefined ? { workstream: step2.workstream } : {}),
+                stage: step2.stage,
+                spanId: step2.spanId,
+            });
+            owner = step2.workstream;
+            cursor = step2.start;
+            continue;
+        }
+        // Step 3: nothing was running — a genuine idle wait.
+        const step3 = owner === undefined
+            ? undefined
+            : waits
+                .filter((w) => w.workstream === owner && covers(w.start, w.end, cursor))
+                .sort((a, b) => b.start - a.start || a.end - b.end || a.cause.localeCompare(b.cause))[0];
+        if (step3 !== undefined) {
+            legs.push({
+                startMs: step3.start,
+                endMs: cursor,
+                durationMs: cursor - step3.start,
+                kind: "wait",
+                workstream: step3.workstream,
+                waitCause: step3.cause,
+                ...(step3.pointId !== undefined ? { pointId: step3.pointId } : {}),
+            });
+            cursor = step3.start;
+            continue;
+        }
+        // Step 4: nothing explains it at all.
+        const prevEnd = allEnds.filter((end) => end < cursor).reduce((max, end) => Math.max(max, end), 0);
+        legs.push({ startMs: prevEnd, endMs: cursor, durationMs: cursor - prevEnd, kind: "gap" });
+        cursor = prevEnd;
+    }
+    if (cursor > 0) {
+        legs.push({ startMs: 0, endMs: cursor, durationMs: cursor, kind: "gap" });
+    }
+    return legs.reverse();
+}
+const AGENT_ATTEMPT_STAGES = new Set(["implementer", "recovery", "informed-retry", "fix-now", "test-critique-fix"]);
+const AGENT_REPEAT_REASONS = new Set([
+    "verify-failure",
+    "informed-by-diagnosis",
+    "critique-finding",
+    "fix-now-finding",
+]);
+const ALWAYS_RERUN_VERIFY_PHASES = new Set(["post-recovery", "post-informed-retry", "test-critique-fix", "fix-now"]);
+const VERIFY_COMMAND_STAGES = new Set(["verification-command", "baseline-verification"]);
+const TELEMETRY_KINDS = new Set(["provider-telemetry", "prompt-component-size"]);
+/**
+ * Deterministically reconciles a `RunAnalytics` artifact into conserved
+ * wall-clock and repetition analytics (SC-09). Pure: no clock, no I/O, no
+ * randomness. A shuffled `spans`/`points` array yields a byte-identical
+ * summary, because every grouping keys off span/point fields — never array
+ * position — and every list is explicitly sorted before it is returned.
+ */
+export function aggregateRunAnalytics(artifact) {
+    const diagnostics = [];
+    const totalElapsedMs = artifact.anchors.finalizedOffsetMs ?? 0;
+    const byId = new Map(artifact.spans.map((span) => [span.id, span]));
+    for (const span of artifact.spans) {
+        if (span.parentId !== undefined && !byId.has(span.parentId)) {
+            diagnostics.push({
+                kind: "unresolved-parent",
+                message: `span ${span.id} (${span.stage}) has parentId "${span.parentId}", which does not resolve`,
+                spanIds: [span.id],
+            });
+        }
+        if (span.endOffsetMs !== undefined && span.endOffsetMs < span.startOffsetMs) {
+            diagnostics.push({
+                kind: "invalid-interval",
+                message: `span ${span.id} (${span.stage}) has endOffsetMs < startOffsetMs`,
+                spanIds: [span.id],
+            });
+        }
+    }
+    const runSpan = artifact.spans.find((span) => span.stage === "run");
+    const runId = runSpan?.id;
+    if (runSpan === undefined) {
+        diagnostics.push({
+            kind: "unresolved-parent",
+            message: "no run-stage span was found; treating root spans (no parentId) as top-level",
+            spanIds: [],
+        });
+    }
+    const topLevelSpans = artifact.spans.filter((span) => span.stage !== "run" && (runId !== undefined ? span.parentId === runId : span.parentId === undefined));
+    const topLevelIntervals = topLevelSpans.map((span) => {
+        if (span.endOffsetMs === undefined) {
+            diagnostics.push({
+                kind: "open-span",
+                // No raw span id in the human-facing message (the report never
+                // prints internal ids — `spanIds` below carries it for machine
+                // consumers/tests instead): this fires on effectively every real
+                // run, since `report-assembly` is deliberately still open when the
+                // snapshot is taken (§2.3/§3.2), not just on a genuine crash.
+                message: `the \`${span.stage}\` span has no endOffsetMs — open (still in progress, or interrupted) at ` +
+                    `snapshot/finalize time, clamped to the total elapsed ${Math.round(totalElapsedMs)}ms`,
+                spanIds: [span.id],
+            });
+        }
+        const rawEnd = span.endOffsetMs ?? totalElapsedMs;
+        let end = rawEnd;
+        if (end > totalElapsedMs) {
+            diagnostics.push({
+                kind: "interval-exceeds-total",
+                message: `span ${span.id} (${span.stage}) ends at ${end}ms, past the total elapsed ${totalElapsedMs}ms`,
+                spanIds: [span.id],
+            });
+            end = totalElapsedMs;
+        }
+        const start = span.startOffsetMs;
+        return { span, start, end: Math.max(start, end) };
+    });
+    const bucketTotals = sweepBucketOwnership(topLevelIntervals, diagnostics);
+    let attributedMs = 0;
+    for (const bucket of BUCKETS) {
+        if (bucket !== "unattributed")
+            attributedMs += bucketTotals.get(bucket) ?? 0;
+    }
+    const unattributedMs = Math.max(0, totalElapsedMs - attributedMs);
+    bucketTotals.set("unattributed", unattributedMs);
+    const spanCountByBucket = new Map(BUCKETS.map((bucket) => [bucket, 0]));
+    // `cumulativeByBucket` (§3.1) is computed from the exact same clamped
+    // `topLevelIntervals` the conserved `durationMs` uses — never the raw
+    // `endOffsetMs − startOffsetMs` — so an open or overrunning span's
+    // cumulative figure matches its owned duration on a serial run, keeping
+    // `cumulativeMs === durationMs` there for every bucket (the identity the
+    // renderer's self-gating suffix relies on).
+    const cumulativeByBucket = new Map(BUCKETS.map((bucket) => [bucket, 0]));
+    for (const interval of topLevelIntervals) {
+        spanCountByBucket.set(interval.span.bucket, (spanCountByBucket.get(interval.span.bucket) ?? 0) + 1);
+        cumulativeByBucket.set(interval.span.bucket, (cumulativeByBucket.get(interval.span.bucket) ?? 0) + (interval.end - interval.start));
+    }
+    // `unattributed` is a residual, not a set of spans (§3.1): its cumulative
+    // figure is its own duration, and its span count stays 0.
+    cumulativeByBucket.set("unattributed", unattributedMs);
+    const buckets = BUCKETS.map((bucket) => ({
+        bucket,
+        durationMs: bucketTotals.get(bucket) ?? 0,
+        cumulativeMs: cumulativeByBucket.get(bucket) ?? 0,
+        percent: totalElapsedMs > 0 ? ((bucketTotals.get(bucket) ?? 0) / totalElapsedMs) * 100 : 0,
+        spanCount: spanCountByBucket.get(bucket) ?? 0,
+    }));
+    // Drill-downs: every non-top-level, non-run span, grouped under its
+    // nearest top-level ancestor — detail, never summed into any bucket.
+    const topLevelIds = new Set(topLevelIntervals.map((interval) => interval.span.id));
+    const drillGroups = new Map();
+    for (const span of artifact.spans) {
+        if (span.id === runId || topLevelIds.has(span.id))
+            continue;
+        const owner = findTopLevelAncestor(span, byId, topLevelIds);
+        if (owner === undefined)
+            continue;
+        const durationMs = Math.max(0, (span.endOffsetMs ?? totalElapsedMs) - span.startOffsetMs);
+        const list = drillGroups.get(owner) ?? [];
+        list.push({
+            id: span.id,
+            stage: span.stage,
+            ...(span.dimensions.workstream !== undefined ? { workstream: span.dimensions.workstream } : {}),
+            ...(span.dimensions.role !== undefined ? { role: span.dimensions.role } : {}),
+            ...(span.dimensions.outcome !== undefined ? { outcome: span.dimensions.outcome } : {}),
+            durationMs,
+        });
+        drillGroups.set(owner, list);
+    }
+    const drillDowns = [...drillGroups.entries()]
+        .map(([ownerSpanId, spans]) => ({
+        ownerSpanId,
+        ownerStage: byId.get(ownerSpanId)?.stage ?? "",
+        spans: [...spans].sort((a, b) => b.durationMs - a.durationMs || a.id.localeCompare(b.id)),
+    }))
+        .sort((a, b) => a.ownerSpanId.localeCompare(b.ownerSpanId));
+    // Dispositions: the five point-backed outcomes join `attempt-outcome`
+    // points to their spawn span on (workstream, attemptSeat, attemptIndex);
+    // `interrupted` is span-derived (D3) since WS-02 emits no point for it.
+    // Restricted to the actual attempt-spawn stages: a `verification-command`
+    // span carries the very same (workstream, attemptSeat, attemptIndex) triple
+    // as the attempt that provoked it (WS-02 §3.4/§3.6, so a rerun pass can be
+    // correlated back to its trigger) — without this filter it would collide
+    // with, and could nondeterministically shadow, the real spawn span.
+    const spawnByAttemptKey = new Map();
+    for (const interval of topLevelIntervals) {
+        if (!AGENT_ATTEMPT_STAGES.has(interval.span.stage))
+            continue;
+        const key = attemptKeyOf(interval.span.dimensions);
+        if (key === undefined)
+            continue;
+        const existing = spawnByAttemptKey.get(key);
+        if (existing === undefined || interval.span.id < existing.span.id)
+            spawnByAttemptKey.set(key, interval);
+    }
+    const dispositionTotals = new Map(KNOWN_OUTCOMES.map((outcome) => [outcome, { count: 0, durationMs: 0 }]));
+    const coveredAttemptKeys = new Set();
+    for (const point of artifact.points) {
+        if (point.kind !== "attempt-outcome")
+            continue;
+        const outcome = point.dimensions?.outcome ?? "unknown";
+        const key = attemptKeyOf(point.dimensions ?? {});
+        if (key !== undefined)
+            coveredAttemptKeys.add(key);
+        const matched = key === undefined ? undefined : spawnByAttemptKey.get(key);
+        const durationMs = matched === undefined ? 0 : matched.end - matched.start;
+        bump(dispositionTotals, outcome, durationMs);
+    }
+    let interruptedCount = 0;
+    let interruptedMs = 0;
+    for (const [key, interval] of spawnByAttemptKey) {
+        if (coveredAttemptKeys.has(key))
+            continue;
+        const isOpen = interval.span.endOffsetMs === undefined;
+        if (interval.span.dimensions.outcome === "interrupted" || isOpen) {
+            interruptedCount += 1;
+            interruptedMs += interval.end - interval.start;
+        }
+    }
+    dispositionTotals.set("interrupted", { count: interruptedCount, durationMs: interruptedMs });
+    // `bump` above may have created outcome keys outside the known vocabulary
+    // (SC-04's open outcome vocabulary) — surfaced after the known six, sorted.
+    const extraOutcomes = [...dispositionTotals.keys()]
+        .filter((outcome) => !KNOWN_OUTCOMES.includes(outcome))
+        .sort();
+    const dispositions = [...KNOWN_OUTCOMES, ...extraOutcomes].map((outcome) => ({
+        outcome,
+        ...(dispositionTotals.get(outcome) ?? { count: 0, durationMs: 0 }),
+    }));
+    // Rerun cost, grouped by trigger — never a single "waste" number (SC-06).
+    const agentRerunByReason = new Map();
+    let agentRerunTotalMs = 0;
+    for (const interval of topLevelIntervals) {
+        if (!AGENT_ATTEMPT_STAGES.has(interval.span.stage))
+            continue;
+        const reason = interval.span.dimensions.attemptReason;
+        if (reason === undefined || !AGENT_REPEAT_REASONS.has(reason))
+            continue;
+        const durationMs = interval.end - interval.start;
+        bump(agentRerunByReason, reason, durationMs);
+        agentRerunTotalMs += durationMs;
+    }
+    const verifyByWorkstreamPhase = new Map();
+    for (const interval of topLevelIntervals) {
+        if (interval.span.stage !== "verification-command")
+            continue;
+        const workstream = interval.span.dimensions.workstream ?? "";
+        const phase = interval.span.dimensions.attemptReason ?? "";
+        const key = `${workstream} ${phase}`;
+        const list = verifyByWorkstreamPhase.get(key) ?? [];
+        list.push(interval);
+        verifyByWorkstreamPhase.set(key, list);
+    }
+    const verifyRerunByPhase = new Map();
+    const verifyRerunByCommand = new Map();
+    let verifyRerunTotalMs = 0;
+    for (const [key, group] of verifyByWorkstreamPhase) {
+        const phase = key.split(" ")[1] ?? "";
+        const sorted = [...group].sort(compareIntervals);
+        sorted.forEach((interval, index) => {
+            // `post-implementer` verifies the initial attempt — only a rerun if it
+            // somehow fires again for the same workstream; every other phase this
+            // runner emits (post-recovery, post-informed-retry, test-critique-fix,
+            // fix-now) exists only because a prior attempt failed, so every
+            // occurrence counts (WS-02's phase vocabulary, §3.4).
+            const isRerun = phase === "post-implementer" ? index > 0 : ALWAYS_RERUN_VERIFY_PHASES.has(phase);
+            if (!isRerun)
+                return;
+            const durationMs = interval.end - interval.start;
+            verifyRerunTotalMs += durationMs;
+            bump(verifyRerunByPhase, phase, durationMs);
+            bump(verifyRerunByCommand, interval.span.dimensions.verifyCommand ?? "(unknown)", durationMs);
+        });
+    }
+    // Rankings — largest measured contributors, never graded (§3.5). Only
+    // top-level spans participate, so parent/child durations are never summed.
+    const stageGroups = new Map();
+    const workstreamGroups = new Map();
+    const roleGroups = new Map();
+    const verifyCommandGroups = new Map();
+    let largestAgentAttempt;
+    for (const interval of topLevelIntervals) {
+        const durationMs = interval.end - interval.start;
+        bump(stageGroups, interval.span.stage, durationMs);
+        bump(workstreamGroups, interval.span.dimensions.workstream ?? "run-level", durationMs);
+        if (interval.span.dimensions.role !== undefined)
+            bump(roleGroups, interval.span.dimensions.role, durationMs);
+        if (VERIFY_COMMAND_STAGES.has(interval.span.stage) && interval.span.dimensions.verifyCommand !== undefined) {
+            const command = interval.span.dimensions.verifyCommand;
+            const cur = verifyCommandGroups.get(command) ?? { count: 0, durationMs: 0, largestMs: 0 };
+            cur.count += 1;
+            cur.durationMs += durationMs;
+            cur.largestMs = Math.max(cur.largestMs, durationMs);
+            verifyCommandGroups.set(command, cur);
+        }
+        if (AGENT_ATTEMPT_STAGES.has(interval.span.stage) && interval.span.dimensions.attemptSeat !== undefined) {
+            if (largestAgentAttempt === undefined ||
+                durationMs > largestAgentAttempt.durationMs ||
+                (durationMs === largestAgentAttempt.durationMs && interval.span.id < largestAgentAttempt.spanId)) {
+                largestAgentAttempt = {
+                    spanId: interval.span.id,
+                    stage: interval.span.stage,
+                    ...(interval.span.dimensions.workstream !== undefined ? { workstream: interval.span.dimensions.workstream } : {}),
+                    ...(interval.span.dimensions.attemptSeat !== undefined ? { attemptSeat: interval.span.dimensions.attemptSeat } : {}),
+                    ...(interval.span.dimensions.attemptIndex !== undefined ? { attemptIndex: interval.span.dimensions.attemptIndex } : {}),
+                    durationMs,
+                };
+            }
+        }
+    }
+    const byVerifyCommand = [...verifyCommandGroups.entries()]
+        .map(([command, v]) => ({ command, invocations: v.count, totalMs: v.durationMs, largestMs: v.largestMs }))
+        .sort((a, b) => b.totalMs - a.totalMs || a.command.localeCompare(b.command));
+    // Observability coverage (§3.6) — over WS-03's own points only.
+    const coverageCounts = { observed: 0, estimated: 0, unavailable: 0, incomplete: 0 };
+    const unavailableRoles = new Set();
+    const providerPoints = [...artifact.points]
+        .filter((point) => point.kind === "provider-telemetry")
+        .sort((a, b) => a.id.localeCompare(b.id));
+    const roleInfo = new Map();
+    for (const point of artifact.points) {
+        if (!TELEMETRY_KINDS.has(point.kind))
+            continue;
+        coverageCounts[point.coverage] += 1;
+        if (point.kind === "provider-telemetry" && point.coverage === "unavailable" && point.dimensions?.role !== undefined) {
+            unavailableRoles.add(point.dimensions.role);
+        }
+    }
+    for (const point of providerPoints) {
+        const role = point.dimensions?.role;
+        if (role === undefined || (point.label !== "provider" && point.label !== "model"))
+            continue;
+        const info = roleInfo.get(role) ?? { role };
+        const field = point.label === "provider" ? "provider" : "model";
+        if (info[field] === undefined) {
+            info[field] = { coverage: point.coverage, ...(point.detail !== undefined ? { value: point.detail } : {}) };
+        }
+        roleInfo.set(role, info);
+    }
+    const byRoleCoverage = [...roleInfo.values()].sort((a, b) => a.role.localeCompare(b.role));
+    // Provider/model duration totals (§3.5): each role's already-computed
+    // duration total (`roleGroups`) is attributed to the provider/model
+    // identity WS-03 observed for that role — labelled `"unavailable"`, never
+    // dropped or blanked, when a role's provider telemetry is unavailable
+    // (e.g. a non-Claude role), so an entire role's measured time is never
+    // silently missing from these totals.
+    const providerGroups = new Map();
+    const modelGroups = new Map();
+    function labelFor(field) {
+        return field === undefined || field.coverage === "unavailable" ? "unavailable" : (field.value ?? "unavailable");
+    }
+    for (const [role, group] of roleGroups) {
+        const info = roleInfo.get(role);
+        const providerKey = labelFor(info?.provider);
+        const modelKey = labelFor(info?.model);
+        for (const [target, key] of [
+            [providerGroups, providerKey],
+            [modelGroups, modelKey],
+        ]) {
+            const cur = target.get(key) ?? { count: 0, durationMs: 0 };
+            cur.count += group.count;
+            cur.durationMs += group.durationMs;
+            target.set(key, cur);
+        }
+    }
+    const bytesByLabel = new Map();
+    for (const point of artifact.points) {
+        if (point.kind !== "prompt-component-size" || point.unit !== "bytes")
+            continue;
+        bytesByLabel.set(point.label ?? "(unlabeled)", (bytesByLabel.get(point.label ?? "(unlabeled)") ?? 0) + (point.value ?? 0));
+    }
+    const promptComponents = [...bytesByLabel.entries()]
+        .map(([label, bytes]) => ({ label, bytes }))
+        .sort((a, b) => b.bytes - a.bytes || a.label.localeCompare(b.label))
+        .slice(0, 5);
+    const overheadPoints = artifact.points.filter((point) => point.kind === "analytics-overhead");
+    const analyticsOverheadMs = overheadPoints.length > 0 ? overheadPoints.reduce((sum, point) => sum + (point.value ?? 0), 0) : undefined;
+    const publishPoints = artifact.points.filter((point) => point.kind === "publish-duration");
+    const publish = publishPoints.length > 0
+        ? { durationMs: publishPoints.reduce((sum, point) => sum + (point.value ?? 0), 0), invocations: publishPoints.length }
+        : undefined;
+    const evidenceMap = new Map();
+    for (const span of artifact.spans) {
+        for (const ref of span.dimensions.evidence ?? [])
+            evidenceMap.set(`${ref.kind}:${ref.ref}`, ref);
+    }
+    for (const point of artifact.points) {
+        for (const ref of point.evidence ?? [])
+            evidenceMap.set(`${ref.kind}:${ref.ref}`, ref);
+    }
+    const sortedEvidence = [...evidenceMap.values()].sort((a, b) => a.ref.localeCompare(b.ref));
+    const evidence = sortedEvidence.slice(0, 8).map((ref) => ({
+        kind: ref.kind,
+        locality: ref.locality,
+        ref: ref.ref,
+        ...(ref.note !== undefined ? { note: ref.note } : {}),
+    }));
+    // WS-06: cumulative (non-conserved) agent/verification time, at any span
+    // depth. `role` is not the same as "agent" — a verification-command span
+    // stamped with `role` (verifyAttempt) must land in the verification total,
+    // never the agent one, or every verify pass would inflate agent time.
+    let cumulativeAgentMs = 0;
+    let agentSpanCount = 0;
+    let cumulativeVerificationMs = 0;
+    let verificationSpanCount = 0;
+    for (const span of artifact.spans) {
+        const durationMs = Math.max(0, (span.endOffsetMs ?? totalElapsedMs) - span.startOffsetMs);
+        if (VERIFY_COMMAND_STAGES.has(span.stage)) {
+            // Role is not required here: an ordinary roleless verification-stage
+            // span (a deterministic check the runner ran itself) still counts.
+            // Role matters only to keep verification spans out of the agent total.
+            cumulativeVerificationMs += durationMs;
+            verificationSpanCount += 1;
+        }
+        else if (span.dimensions.role !== undefined) {
+            cumulativeAgentMs += durationMs;
+            agentSpanCount += 1;
+        }
+    }
+    // WS-06: reconcile the scheduling observations, sweep parallelism, and walk
+    // the critical path — all pure functions of the artifact already parsed
+    // above; see each function's own doc comment for the contract.
+    const scheduling = reconcileScheduling(artifact, diagnostics);
+    const parallelism = sweepWorkstreamConcurrency(topLevelIntervals);
+    const criticalPath = computeCriticalPath(topLevelIntervals, scheduling.allWaits, totalElapsedMs);
+    const concurrency = {
+        meanWorkstreamConcurrency: parallelism.meanWorkstreamConcurrency,
+        peakWorkstreamConcurrency: parallelism.peakWorkstreamConcurrency,
+        overlappedMs: parallelism.overlappedMs,
+        cumulativeAgentMs,
+        agentSpanCount,
+        cumulativeVerificationMs,
+        verificationSpanCount,
+        cumulativeWorkstreamMs: parallelism.cumulativeWorkstreamMs,
+        ...(scheduling.schedulerStartMs !== undefined ? { schedulerStartMs: scheduling.schedulerStartMs } : {}),
+        schedules: scheduling.schedules,
+        waitsByCause: scheduling.waitsByCause,
+        criticalPath,
+    };
+    // Diagnostics are pushed as each condition is discovered while walking
+    // `artifact.spans` in array order (unresolved-parent, invalid-interval,
+    // interval-exceeds-total); `sweepBucketOwnership`'s overlap diagnostics are
+    // already order-independent (found via sorted interval boundaries), but the
+    // other three are not — sorted here so the full summary stays
+    // order-independent (SC-09): a shuffled `spans` array must never change
+    // which diagnostics were found or their relative order, only the pass that
+    // happened to find them first. `reconcileScheduling`'s diagnostics are
+    // already order-independent too (grouped by (workstream, kind[, cause])
+    // key, never by array position), but the shared sort still needs a
+    // `pointIds` tie-break so two point-derived diagnostics with empty
+    // `spanIds` sort deterministically against each other.
+    diagnostics.sort((a, b) => a.kind.localeCompare(b.kind) ||
+        a.spanIds.join(",").localeCompare(b.spanIds.join(",")) ||
+        (a.pointIds ?? []).join(",").localeCompare((b.pointIds ?? []).join(",")) ||
+        a.message.localeCompare(b.message));
+    return {
+        totalElapsedMs,
+        attributedMs,
+        unattributedMs,
+        buckets,
+        diagnostics,
+        drillDowns,
+        dispositions,
+        rerun: {
+            agent: { totalMs: agentRerunTotalMs, byReason: rankedFromGroups(agentRerunByReason).map((r) => ({ key: r.key, count: r.count, durationMs: r.durationMs })) },
+            verification: {
+                totalMs: verifyRerunTotalMs,
+                byPhase: rankedFromGroups(verifyRerunByPhase).map((r) => ({ key: r.key, count: r.count, durationMs: r.durationMs })),
+                byCommand: rankedFromGroups(verifyRerunByCommand).map((r) => ({ key: r.key, count: r.count, durationMs: r.durationMs })),
+            },
+        },
+        rankings: {
+            byStage: rankedFromGroups(stageGroups),
+            byWorkstream: rankedFromGroups(workstreamGroups),
+            byRole: rankedFromGroups(roleGroups),
+            byProvider: rankedFromGroups(providerGroups),
+            byModel: rankedFromGroups(modelGroups),
+            byVerifyCommand,
+            ...(largestAgentAttempt !== undefined ? { largestAgentAttempt } : {}),
+        },
+        coverage: { counts: coverageCounts, unavailableRoles: [...unavailableRoles].sort(), byRole: byRoleCoverage },
+        promptComponents,
+        ...(analyticsOverheadMs !== undefined ? { analyticsOverheadMs } : {}),
+        ...(publish !== undefined ? { publish } : {}),
+        evidence,
+        evidenceTotalCount: evidenceMap.size,
+        concurrency,
+    };
+}
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
+function formatDuration(ms) {
+    if (!Number.isFinite(ms) || ms < 0)
+        ms = 0;
+    if (ms < 1000)
+        return `${Math.round(ms)}ms`;
+    const totalSeconds = ms / 1000;
+    if (totalSeconds < 60)
+        return `${totalSeconds.toFixed(1)}s`;
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = Math.round(totalSeconds - minutes * 60);
+    return `${minutes}m ${String(seconds).padStart(2, "0")}s`;
+}
+function plural(count, noun) {
+    return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
+/**
+ * One clause per known wait cause, for the "Where the time went" wait table.
+ * A cause with no entry here still renders — with no gloss — because the
+ * cause vocabulary is open (§3.3, §3.9): forgetting to add a gloss for a new
+ * cause degrades legibility, never correctness.
+ */
+const WAIT_CAUSE_GLOSS = {
+    dependency: "an author deferred re-authoring on an in-flight sibling's spec",
+    "concurrency-cap": "the shared --max-parallel budget was already saturated",
+    "integration-mutex": "another workstream held the serialized integration step",
+    "spec-pending": "dependencies had integrated but this workstream's own spec was still being authored",
+    "author-concurrency-cap": "the authoring half of the shared --max-parallel budget was saturated",
+    "dependency-landing": "derived by this report from the scheduler's derived start — not measured by the runner",
+};
+const CRITICAL_PATH_LEG_LIMIT = 40;
+function describeLeg(leg) {
+    switch (leg.kind) {
+        case "stage":
+            return leg.workstream !== undefined ? `${leg.workstream} ${leg.stage}` : `run-level ${leg.stage}`;
+        case "wait":
+            return `${leg.workstream} waiting (${leg.waitCause})`;
+        case "gap":
+            return "unexplained gap — nothing observed covers this interval";
+    }
+}
+function describeHandoff(leg) {
+    if (leg.handoff === undefined)
+        return "";
+    const from = leg.handoff.fromWorkstream ?? "run-level work";
+    const reason = leg.handoff.causeObserved
+        ? `that flow's own recorded wait was on \`${leg.handoff.cause}\``
+        : "no wait was recorded across this boundary";
+    return ` — took the wall clock over from ${from} (${reason})`;
+}
+/** Renders the gated "Concurrency and the critical path" subsection (§3.9) — only ever called when `peakWorkstreamConcurrency > 1`. */
+function renderConcurrencySection(summary) {
+    const c = summary.concurrency;
+    const lines = ["### Concurrency and the critical path", ""];
+    lines.push("Two or more workstreams ran at once in this run. The bucket table above is a partition of wall-clock " +
+        "time, so it says how the run's length was spent, not how much work was done — concurrent work shares " +
+        "the same wall clock.", "");
+    lines.push(`Parallelism: **${c.meanWorkstreamConcurrency.toFixed(1)}×** mean workstream concurrency (peak ` +
+        `${c.peakWorkstreamConcurrency}). ${formatDuration(c.overlappedMs)} of the ${formatDuration(summary.totalElapsedMs)} ` +
+        "elapsed had two or more workstreams live.", "");
+    lines.push(`Cumulative agent time: **${formatDuration(c.cumulativeAgentMs)}** across ${plural(c.agentSpanCount, "spawn")}. ` +
+        `Cumulative verification time: **${formatDuration(c.cumulativeVerificationMs)}** across ` +
+        `${plural(c.verificationSpanCount, "invocation")}. Both are sums over concurrent work and are deliberately ` +
+        "non-conserved — they can exceed the total elapsed above because the run did more work than it spent time.", "");
+    lines.push("The chain below is reconstructed from observed time: the run records why a workstream was waiting, not " +
+        "which workstream released it, so each step names the flow that held the wall clock before it rather than " +
+        "a recorded cause.", "");
+    const legs = c.criticalPath;
+    const shown = legs.length > CRITICAL_PATH_LEG_LIMIT ? legs.slice(0, CRITICAL_PATH_LEG_LIMIT - 1) : legs;
+    for (const leg of shown) {
+        lines.push(`- ${formatDuration(leg.startMs)}–${formatDuration(leg.endMs)}: ${describeLeg(leg)}${describeHandoff(leg)}`);
+    }
+    if (legs.length > CRITICAL_PATH_LEG_LIMIT) {
+        const rest = legs.slice(CRITICAL_PATH_LEG_LIMIT - 1);
+        const restMs = rest.reduce((sum, leg) => sum + leg.durationMs, 0);
+        lines.push(`- other: ${plural(rest.length, "further leg")}, chronologically after the above, spanning ` +
+            `${formatDuration(restMs)} combined (not shown individually)`);
+    }
+    lines.push("");
+    lines.push("Wait totals, by cause — per-cause totals, **not a partition of the wall clock**: two of these causes are " +
+        "measured on the author item and lie inside the same workstream's `spec-pending` window, so these rows " +
+        "must never be summed together or into a run total.", "");
+    if (c.waitsByCause.length === 0) {
+        lines.push("No scheduling waits were observed.");
+    }
+    else {
+        for (const wc of c.waitsByCause) {
+            const gloss = WAIT_CAUSE_GLOSS[wc.cause];
+            lines.push(`- \`${wc.cause}\`${wc.derived ? " (derived)" : ""}: ${formatDuration(wc.totalMs)} across ` +
+                `${plural(wc.workstreams, "workstream")}${gloss ? ` — ${gloss}` : ""}`);
+        }
+    }
+    lines.push("");
+    lines.push("Per-workstream schedule:", "");
+    if (c.schedules.length === 0) {
+        lines.push("No scheduling observations were recorded for any workstream.");
+    }
+    else {
+        for (const s of c.schedules) {
+            const parts = [];
+            parts.push(s.readyMs !== undefined ? `ready at ${formatDuration(s.readyMs)}` : "no ready instant observed");
+            if (s.scheduledMs !== undefined) {
+                parts.push(`scheduled at ${formatDuration(s.scheduledMs)}`);
+                if (s.queuedMs !== undefined)
+                    parts.push(`queued ${formatDuration(s.queuedMs)}`);
+            }
+            else if (s.readyMs !== undefined) {
+                parts.push("became ready but was never scheduled in this run");
+            }
+            lines.push(`- **${s.workstream}**: ${parts.join(", ")}`);
+            for (const w of s.waits) {
+                lines.push(`  - \`${w.cause}\`: ${formatDuration(w.waitedMs)}${w.derived ? " (derived by this report, not measured by the runner)" : ""}`);
+            }
+        }
+    }
+    lines.push("");
+    return lines;
+}
+/**
+ * Renders the aggregated summary into the "Where the time went" section
+ * (SC-10, SC-11) — human-first, concise, and never a score or a grade.
+ */
+export function renderWhereTheTimeWent(summary) {
+    const lines = ["## Where the time went", ""];
+    lines.push(`Total elapsed: **${formatDuration(summary.totalElapsedMs)}** — run start to the analytics snapshot taken ` +
+        "just before finalize and the report commit. The report write, the report commit, and publish are " +
+        "excluded from this total and, when observed, recorded separately (see Publish below).", "");
+    lines.push("### Time by bucket", "");
+    for (const bucket of summary.buckets) {
+        const cumulativeSuffix = bucket.cumulativeMs !== bucket.durationMs ? ` (cumulative ${formatDuration(bucket.cumulativeMs)})` : "";
+        lines.push(`- **${bucket.bucket}**: ${formatDuration(bucket.durationMs)} (${bucket.percent.toFixed(1)}%, ${plural(bucket.spanCount, "span")})${cumulativeSuffix}`);
+    }
+    lines.push("");
+    // WS-06: gated on observed overlap — a serial run (including a
+    // `--max-parallel 1` run) always has `peakWorkstreamConcurrency <= 1`, so
+    // this section, and the bucket-line cumulative suffix above, are never
+    // present there (SC-09, SC-11).
+    if (summary.concurrency.peakWorkstreamConcurrency > 1) {
+        lines.push(...renderConcurrencySection(summary));
+    }
+    lines.push("### Largest contributors", "");
+    const topStage = summary.rankings.byStage[0];
+    lines.push(topStage
+        ? `- Stage: \`${topStage.key}\` — ${formatDuration(topStage.durationMs)} across ${plural(topStage.count, "span")}`
+        : "- Stage: none observed.");
+    const topWorkstream = summary.rankings.byWorkstream[0];
+    lines.push(topWorkstream
+        ? `- Workstream: ${topWorkstream.key} — ${formatDuration(topWorkstream.durationMs)}`
+        : "- Workstream: none observed.");
+    const attempt = summary.rankings.largestAgentAttempt;
+    lines.push(attempt
+        ? `- Largest single agent attempt: \`${attempt.stage}\`` +
+            (attempt.workstream ? ` (${attempt.workstream}` : " (") +
+            `${attempt.attemptSeat ? `, ${attempt.attemptSeat}` : ""}` +
+            `${attempt.attemptIndex !== undefined ? ` #${attempt.attemptIndex}` : ""})` +
+            ` — ${formatDuration(attempt.durationMs)}`
+        : "- Largest single agent attempt: none observed.");
+    const topCommand = summary.rankings.byVerifyCommand[0];
+    lines.push(topCommand
+        ? `- Largest verification command: \`${topCommand.command}\` — ${formatDuration(topCommand.totalMs)} across ` +
+            `${plural(topCommand.invocations, "invocation")} (largest single run ${formatDuration(topCommand.largestMs)})`
+        : "- Largest verification command: none observed.");
+    lines.push("");
+    lines.push("### Attempts", "");
+    for (const disposition of summary.dispositions) {
+        lines.push(`- ${disposition.outcome}: ${plural(disposition.count, "attempt")} (${formatDuration(disposition.durationMs)})`);
+    }
+    lines.push("", `Agent time spent re-running after a prior attempt: **${formatDuration(summary.rerun.agent.totalMs)}**, by trigger:`);
+    if (summary.rerun.agent.byReason.length === 0) {
+        lines.push("- none observed");
+    }
+    else {
+        for (const group of summary.rerun.agent.byReason) {
+            lines.push(`- ${group.key}: ${plural(group.count, "attempt")} (${formatDuration(group.durationMs)})`);
+        }
+    }
+    lines.push("");
+    lines.push("### Verification", "");
+    lines.push(`Verification rerun time (passes caused by a retry, recovery, or fix — never the first pass over fresh ` +
+        `work): **${formatDuration(summary.rerun.verification.totalMs)}**`);
+    if (summary.rerun.verification.byPhase.length > 0) {
+        lines.push("", "By phase:");
+        for (const group of summary.rerun.verification.byPhase) {
+            lines.push(`- ${group.key}: ${plural(group.count, "invocation")} (${formatDuration(group.durationMs)})`);
+        }
+    }
+    if (summary.rankings.byVerifyCommand.length > 0) {
+        lines.push("", "Every configured command, all invocations:");
+        for (const command of summary.rankings.byVerifyCommand) {
+            lines.push(`- \`${command.command}\`: ${plural(command.invocations, "invocation")}, ${formatDuration(command.totalMs)} total`);
+        }
+    }
+    lines.push("");
+    lines.push("### Observability gaps", "");
+    lines.push(`Provider/prompt telemetry: ${summary.coverage.counts.observed} observed, ${summary.coverage.counts.estimated} ` +
+        `estimated, ${summary.coverage.counts.unavailable} unavailable, ${summary.coverage.counts.incomplete} incomplete.`);
+    if (summary.coverage.unavailableRoles.length > 0) {
+        lines.push(`Roles reporting unavailable provider telemetry (expected coverage for a non-Claude provider, never a ` +
+            `missing-time signal — their elapsed spans are still fully attributed above): ` +
+            `${summary.coverage.unavailableRoles.join(", ")}.`);
+    }
+    if (summary.rankings.byProvider.length > 0) {
+        lines.push("", "Time by provider (`unavailable` when a role's provider telemetry is unavailable, never a dropped total):");
+        for (const p of summary.rankings.byProvider) {
+            lines.push(`- ${p.key}: ${formatDuration(p.durationMs)} across ${plural(p.count, "span")}`);
+        }
+    }
+    if (summary.rankings.byModel.length > 0) {
+        lines.push("", "Time by model:");
+        for (const m of summary.rankings.byModel) {
+            lines.push(`- ${m.key}: ${formatDuration(m.durationMs)} across ${plural(m.count, "span")}`);
+        }
+    }
+    if (summary.promptComponents.length > 0) {
+        lines.push("", "Largest initial-context components: " +
+            summary.promptComponents.map((c) => `${c.label} (${c.bytes.toLocaleString("en-US")} bytes)`).join(", ") +
+            ".");
+    }
+    if (summary.diagnostics.length > 0) {
+        lines.push("", "Interval-consistency notes:");
+        for (const diagnostic of summary.diagnostics)
+            lines.push(`- ${diagnostic.message}`);
+    }
+    if (summary.analyticsOverheadMs !== undefined) {
+        lines.push("", `Analytics-recorder overhead (a diagnostic footnote, not part of the total above): ${formatDuration(summary.analyticsOverheadMs)}.`);
+    }
+    lines.push("");
+    lines.push("### Evidence", "");
+    if (summary.evidence.length === 0) {
+        lines.push("No canonical evidence references were recorded for this run.");
+    }
+    else {
+        for (const ref of summary.evidence) {
+            lines.push(`- local ${ref.kind}: \`${ref.ref}\`${ref.note ? ` — ${ref.note}` : ""}`);
+        }
+        if (summary.evidenceTotalCount > summary.evidence.length) {
+            lines.push(`(showing ${summary.evidence.length} of ${summary.evidenceTotalCount} recorded references)`);
+        }
+    }
+    lines.push("", "Every reference above resolves only on the machine that ran this build — it is local evidence, not a " +
+        "durable CI artifact.", "");
+    if (summary.publish !== undefined) {
+        lines.push("### Publish", "", `Publish ran after this report was already committed, so it is never reconciled into the total above: ` +
+            `${formatDuration(summary.publish.durationMs)} across ${plural(summary.publish.invocations, "invocation")}.`, "");
+    }
+    return lines;
+}
+function unavailableSection(reason) {
+    return ["## Where the time went", "", `Analytics unavailable — ${reason}.`, ""];
+}
+/**
+ * The run's own fail-open isolation boundary for analytics (D4, SC-13):
+ * always returns a `## Where the time went` section, never throws. A throw
+ * from `aggregate` (real or injected via `deps`, for tests), an `undefined`
+ * snapshot, or a throw while *obtaining* the snapshot all degrade to an
+ * explicit "analytics unavailable" placeholder — never suppress the rest of
+ * the report, which is built independently of this function's output.
+ *
+ * `artifact` accepts either a plain value (the common case, and every
+ * existing pure test) or a thunk. The thunk form matters at the real call
+ * site: `recorder.snapshot()` is documented as non-throwing, but evaluating
+ * it as a plain argument — `renderAnalyticsSection(recorder.snapshot())` —
+ * would run it *before* this function's own try/catch is reached, so any
+ * violation of that contract (a bug, or a test double standing in for the
+ * recorder) would still escape this boundary and, through the caller's own
+ * try/catch, suppress the whole report. Wrapping it in a thunk —
+ * `renderAnalyticsSection(() => recorder.snapshot())` — keeps that call
+ * inside the try below, so this function's "never throws" is true no matter
+ * what actually produced the artifact.
+ */
+export function renderAnalyticsSection(artifact, deps = {}) {
+    const aggregate = deps.aggregate ?? aggregateRunAnalytics;
+    try {
+        const resolved = typeof artifact === "function" ? artifact() : artifact;
+        if (resolved === undefined) {
+            return unavailableSection("no analytics snapshot was available when the report was rendered");
+        }
+        return renderWhereTheTimeWent(aggregate(resolved));
+    }
+    catch (error) {
+        return unavailableSection(error.message);
+    }
+}
+//# sourceMappingURL=run-analytics-report.js.map