@wildorder/nightshift 0.17.0 → 0.18.0

package/dist/run-analytics-report.js

@@ -1,4 +1,4 @@
-import { BUCKETS, KNOWN_OUTCOMES, } from "./run-analytics.js";
+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);
 }
@@ -45,8 +45,17 @@ function findTopLevelAncestor(span, byId, topLevelIds) {
  * 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). Any sub-interval covered by more than one
- * span is recorded as an `overlap` diagnostic.
+ * 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]));
@@ -71,20 +80,433 @@ function sweepBucketOwnership(intervals, diagnostics) {
         const owner = covering[0];
         totals.set(owner.span.bucket, (totals.get(owner.span.bucket) ?? 0) + (b - a));
         if (covering.length > 1) {
-            const ids = covering.map((interval) => interval.span.id).sort();
-            const key = ids.join(",");
-            if (!seenOverlaps.has(key)) {
-                seenOverlaps.add(key);
+            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: "overlap",
-                    message: `top-level spans overlap in [${a}, ${b}]ms: ${ids.join(", ")} — ` +
-                        `attributed once, to ${owner.span.id} (${owner.span.bucket})`,
-                    spanIds: ids,
+                    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);
         }
     }
-    return totals;
+    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([
@@ -169,12 +591,24 @@ export function aggregateRunAnalytics(artifact) {
     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,
     }));
@@ -428,6 +862,48 @@ export function aggregateRunAnalytics(artifact) {
         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
@@ -435,9 +911,14 @@ export function aggregateRunAnalytics(artifact) {
     // 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.
+    // 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,
@@ -470,6 +951,7 @@ export function aggregateRunAnalytics(artifact) {
         ...(publish !== undefined ? { publish } : {}),
         evidence,
         evidenceTotalCount: evidenceMap.size,
+        concurrency,
     };
 }
 // ---------------------------------------------------------------------------
@@ -490,6 +972,108 @@ function formatDuration(ms) {
 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.
@@ -501,9 +1085,17 @@ export function renderWhereTheTimeWent(summary) {
         "excluded from this total and, when observed, recorded separately (see Publish below).", "");
     lines.push("### Time by bucket", "");
     for (const bucket of summary.buckets) {
-        lines.push(`- **${bucket.bucket}**: ${formatDuration(bucket.durationMs)} (${bucket.percent.toFixed(1)}%, ${plural(bucket.spanCount, "span")})`);
+        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