shapeup-sdlc 1.7.0 → 3.0.1

package/kernel/probe/concurrency.mjs

@@ -0,0 +1,510 @@
+#!/usr/bin/env node
+// probe concurrency — "how many legs actually ran at once, and what did that buy?"
+//
+// WHY IT EXISTS. Fanning the scope loop out has three acceptance questions — did two scopes ever
+// run at the same time, did shared state survive it, did wall-clock improve — and all three are
+// MEASUREMENTS. The pipeline emitted no measurement: the first claim that legs ran in parallel came
+// from a probe that counted green results, which is satisfied by three legs run one after another.
+// This is the missing instrument. It writes nothing and answers only from records on disk.
+//
+// THE RULE IT IS BUILT AROUND. A predicate that an ABSENCE can satisfy must report that absence in
+// the same value. `max_concurrent: 1` over four legs and one usable record is not a small number,
+// it is a false one — and it reads exactly like a run that was genuinely sequential. So every
+// figure here travels with the completeness of the record set it came from and with a `bound`
+// saying whether it is exact or a floor, and a speedup that cannot be supported is `null` with the
+// reason, never a plausible-looking ratio.
+//
+// WHERE THE TWO ENDS OF A LEG COME FROM.
+//
+//   start  `receipts/dispatch.jsonl` — a PostToolUse row, written when the Skill RESOLVED. Measured
+//          across real runs it lands 1.8–47 s after the order was compiled, on legs that then ran
+//          for minutes: it is a start, and being hook-written and append-only it is the one start
+//          that survives a relaunch re-writing the order file.
+//   end    `legs.jsonl` — the reducer's leg-completion row. EXACT.
+//          Falling back, for a run recorded before that ledger existed: the last T0 trial the leg
+//          wrote inside its own dispatch window. That is a landmark near the end, not the end, so
+//          every figure derived through it is marked a LOWER bound.
+//
+// WHAT IS DELIBERATELY NOT USED: result-file mtimes. A trace that has been copied carries the copy
+// time on every file, so a measurement built on them is fabricated rather than approximate.
+//
+// Usage: node kernel/harness.mjs probe concurrency --slug <slug> [--cwd <dir>] [--run-root <dir>]
+//                                                  [--round N] [--gap-s N] [--format json|table]
+// Exit:  0 = a report was produced with at least one usable leg · 1 = ran, and no leg in scope had
+//        a usable interval (the report still prints, and says why) · 2 = malformed argv.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { runArgs } from "../lib/argv.mjs";
+import { localRoot, runIdFromRoot, RECEIPT_FILE } from "../lib/paths.mjs";
+
+/** The round-addressed order id forms `<scope>-r<N>-a<M>` and `<phase>-r<N>`. */
+const ROUND_SUFFIX = /^(.*?)-r(\d+)(?:-a(\d+))?$/;
+
+/** Default fan-out width when a run's `run-args.json` declares none — mirrors the orchestrator. */
+export const DEFAULT_MAX_PARALLEL_SCOPES = 4;
+
+/** Default relaunch gap, in seconds. A run resumed after this long is a different launch. */
+export const DEFAULT_GAP_S = 900;
+
+/**
+ * Read a JSONL ledger into rows, skipping torn lines rather than throwing.
+ * @param {string} path - Path to a `.jsonl` file.
+ * @returns {{rows:Array<object>, malformed:number, present:boolean}} Parsed rows and how many
+ *   lines could not be parsed — reported, because a ledger half of which is unreadable must not
+ *   look like a short one.
+ */
+export function readLedger(path) {
+  if (!existsSync(path)) return { rows: [], malformed: 0, present: false };
+  let malformed = 0;
+  const rows = [];
+  for (const line of readFileSync(path, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    try { rows.push(JSON.parse(line)); } catch { malformed++; }
+  }
+  return { rows, malformed, present: true };
+}
+
+/**
+ * Split an order id into the scope/phase name and the round-attempt address it encodes.
+ * @param {string} orderId - e.g. `todo-cli/foundation-r2-a1`.
+ * @returns {{name:(string|null), round:(number|null), attempt:(number|null)}}
+ */
+export function addressOf(orderId) {
+  const suffix = String(orderId ?? "").split("/").slice(1).join("/");
+  if (!suffix) return { name: null, round: null, attempt: null };
+  const m = suffix.match(ROUND_SUFFIX);
+  if (!m) return { name: suffix, round: null, attempt: null };
+  return { name: m[1], round: Number(m[2]), attempt: m[3] === undefined ? null : Number(m[3]) };
+}
+
+/**
+ * Every build dispatch's start, from the hook-written receipt ledger.
+ *
+ * BUILD LEGS ONLY, and the count of what was skipped travels with the answer. ORIENT, ANALYZE,
+ * WIRE, EVAL and GATE H are sequential phases in every lane; folding them into a concurrency figure
+ * would dilute exactly the number the fan-out is judged on. A leg qualifies by carrying an attempt
+ * address (`-r<N>-a<M>`), which only a scope build order does.
+ *
+ * @param {Array<object>} receipts - Rows from `receipts/dispatch.jsonl`.
+ * @returns {{starts:Array<object>, phase_dispatches:number}} Starts sorted by time.
+ */
+export function startsFrom(receipts) {
+  const starts = [];
+  let phase = 0;
+  for (const r of receipts) {
+    const { name, round, attempt } = addressOf(r.order_id);
+    const at = Date.parse(r.at);
+    if (attempt === null || !Number.isFinite(at)) { phase++; continue; }
+    starts.push({ order_id: r.order_id, scope_id: name, round, attempt, start: at, start_source: "dispatch-receipt", run_id: r.run_id ?? null });
+  }
+  starts.sort((a, b) => a.start - b.start || String(a.order_id).localeCompare(String(b.order_id)));
+  return { starts, phase_dispatches: phase };
+}
+
+/**
+ * Attach an end to every start.
+ *
+ * THE PAIRING PROBLEM THIS SOLVES. One order id is dispatched many times — a relaunch re-uses the
+ * path verbatim — so "the completion row for this order" is ambiguous and picking the newest would
+ * hand every earlier dispatch the last one's end. Each start therefore claims only what falls
+ * inside its own window: from its own instant up to the NEXT dispatch OF THE SAME SCOPE AND ROUND.
+ *
+ * The window is keyed by scope+round rather than by order id, and the difference is not cosmetic.
+ * Windowing by order id let one archived leg claim a T0 artifact written by a LATER dispatch of the
+ * same scope under a different attempt number — a leg that had actually died came back with a
+ * seventeen-minute duration. A leg for scope S in round R is over the moment anything else is
+ * dispatched for S in R, whatever attempt it is addressed by.
+ *
+ * Exact ends come from the leg ledger. When a start's window holds none — every run recorded before
+ * that ledger existed, and every leg that died before ingest — the last T0 trial the scope wrote
+ * inside the same window stands in, and the leg is marked a lower bound rather than a fact.
+ *
+ * @param {Array<object>} starts - From {@link startsFrom}.
+ * @param {Array<object>} legRows - Rows from `legs.jsonl`.
+ * @param {Array<object>} trials - Rows from `t0/trials.jsonl`.
+ * @returns {Array<object>} One leg per start, `end` null when nothing closed it.
+ */
+export function pairLegs(starts, legRows, trials) {
+  const sameLeg = (a, b) => a.scope_id === b.scope_id && a.round === b.round;
+  const nextOf = new Map();
+  for (let i = 0; i < starts.length; i++) {
+    for (let j = i + 1; j < starts.length; j++) {
+      if (sameLeg(starts[j], starts[i])) { nextOf.set(i, starts[j].start); break; }
+    }
+  }
+  return starts.map((s, i) => {
+    const until = nextOf.get(i) ?? Infinity;
+    const inWindow = (t) => Number.isFinite(t) && t >= s.start && t < until;
+
+    const landmarks = trials
+      .filter((t) => t.scope_id === s.scope_id && Number(t.round) === s.round && inWindow(Date.parse(t.at)))
+      .map((t) => Date.parse(t.at)).sort((a, b) => a - b);
+    // The INNER end, kept alongside the outer one rather than used only as a fallback. A T0 trial
+    // was written BY THE LEG, mid-flight, so `[start, inner_end]` is an interval the leg provably
+    // occupied. `ingested_at` is when the WRITER ran, which is normally the leg's last act and is
+    // sometimes not the leg at all — an out-of-band ingest (a repair, a `--no-receipt-check` rescue,
+    // a relaunch re-applying a result) stamps a later instant onto the same row and stretches the
+    // leg over time it was not running. That is not hypothetical: one leg ingested out of band, minutes
+    // after its own T0 landmark while its neighbours closed within seconds of theirs, is enough to
+    // report two legs overlapping on a run whose dial was 1 and which built one scope at a time.
+    const innerEnd = landmarks.length ? landmarks[landmarks.length - 1] : null;
+
+    const exact = legRows
+      .filter((r) => r.order_id === s.order_id && inWindow(Date.parse(r.ingested_at)))
+      .map((r) => Date.parse(r.ingested_at)).sort((a, b) => a - b);
+    if (exact.length) {
+      return { ...s, end: exact[exact.length - 1], end_source: "leg-record", bound: "exact", inner_end: innerEnd };
+    }
+    if (innerEnd !== null) {
+      return { ...s, end: innerEnd, end_source: "t0-landmark", bound: "lower", inner_end: innerEnd };
+    }
+    return { ...s, end: null, end_source: null, bound: null, inner_end: null };
+  });
+}
+
+/**
+ * Split legs into launches.
+ *
+ * A run keeps one `run_id` across every relaunch — the key is derived from the receipt, and a
+ * resumed run reads the same receipt — so a span taken over all of a run's legs fuses launches that
+ * were hours apart. Measured on one archived run: four launches under one key, 17:18 to 03:35, of
+ * which the great majority is a laptop being closed.
+ *
+ * There is no launch id in the record set, so this is a GAP HEURISTIC and it says so: the rule and
+ * its threshold are in the report, because a heuristic that hides is indistinguishable from a fact.
+ *
+ * @param {Array<object>} legs - Legs with a usable interval, sorted by start.
+ * @param {number} gapMs - A quiet period longer than this starts a new launch.
+ * @returns {Array<Array<object>>} One group per launch.
+ */
+export function segment(legs, gapMs) {
+  if (!legs.length) return [];
+  const out = [[legs[0]]];
+  let high = legs[0].end;
+  for (const leg of legs.slice(1)) {
+    if (leg.start - high > gapMs) { out.push([leg]); } else { out[out.length - 1].push(leg); }
+    high = Math.max(high, leg.end);
+  }
+  return out;
+}
+
+/**
+ * The greatest number of legs open at one instant, and when it happened.
+ *
+ * Ends are processed before starts at the same millisecond, so a leg that closes exactly as the
+ * next one opens is not counted as an overlap. Two legs are concurrent only if they were both
+ * genuinely running, and a tie at the boundary is the case where that is least certain.
+ *
+ * @param {Array<object>} legs - Legs with `start` and `end`.
+ * @param {string} [endField] - Which end to measure against: `end` (the outer end, an ingest) or
+ *   `inner_end` (the last T0 trial the leg wrote, provably mid-flight). Legs lacking the named field
+ *   are dropped, so the caller must read the returned `legs` count before trusting `max`.
+ * @returns {{max:(number|null), at:(number|null), legs:number}} `null` when there is nothing to
+ *   measure — never `0` or `1`, which a reader would take for a sequential run.
+ */
+export function maxConcurrent(legs, endField = "end") {
+  const usable = legs.filter((l) => Number.isFinite(l[endField]));
+  if (!usable.length) return { max: null, at: null, legs: 0 };
+  const events = [];
+  for (const l of usable) { events.push([l.start, 1]); events.push([l[endField], -1]); }
+  events.sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+  let open = 0, max = 0, at = null;
+  for (const [t, delta] of events) {
+    open += delta;
+    if (open > max) { max = open; at = t; }
+  }
+  return { max, at, legs: usable.length };
+}
+
+/**
+ * The waves the run actually ran, derived from the timings rather than from the scheduler.
+ *
+ * A wave is a connected component of overlapping intervals: legs that ran together, bounded by
+ * quiet moments where nothing was in flight. This is an INDEPENDENT reading of the schedule — if
+ * the scheduler claims a dependency ordering, this is where it either shows up or does not.
+ *
+ * @param {Array<object>} legs - Legs with a usable interval, sorted by start.
+ * @returns {Array<{from:string, to:string, scopes:string[]}>} Waves in start order.
+ */
+export function wavesObserved(legs) {
+  const waves = [];
+  for (const leg of legs) {
+    const last = waves[waves.length - 1];
+    if (last && leg.start < last.endMs) {
+      last.members.push(leg);
+      last.endMs = Math.max(last.endMs, leg.end);
+    } else {
+      waves.push({ startMs: leg.start, endMs: leg.end, members: [leg] });
+    }
+  }
+  return waves.map((w) => ({
+    from: new Date(w.startMs).toISOString(),
+    to: new Date(w.endMs).toISOString(),
+    scopes: [...new Set(w.members.map((m) => m.scope_id))].sort(),
+  }));
+}
+
+/**
+ * Summarise one launch: overlap, span, work, and whether a speedup can honestly be stated.
+ *
+ * WHY A SPEEDUP IS REFUSED ON ANY LOWER-BOUND LEG, and it is not caution. Truncating every leg at
+ * its T0 landmark shortens the numerator once per leg and the denominator only for whichever leg
+ * finished last, so the ratio moves in a direction that depends on the shape of the round. Measured
+ * on a real round that demonstrably ran four scopes at once, the truncated figure is 0.90 — a
+ * "speedup" below 1. A ratio of two lower bounds is not a bound on the ratio.
+ *
+ * @param {number} index - 1-based launch number.
+ * @param {Array<object>} legs - The launch's legs, each with a usable interval.
+ * @returns {object} The launch block of the report.
+ */
+export function summarise(index, legs) {
+  const { max, at } = maxConcurrent(legs);
+  // The same question asked of the inner intervals — dispatch to the leg's own T0 trial. Two legs
+  // overlapping THERE were both provably mid-flight at one instant; two legs overlapping only on the
+  // outer intervals may be one leg plus somebody else's later ingest of it.
+  const inner = maxConcurrent(legs, "inner_end");
+  const exact = legs.every((l) => l.bound === "exact");
+  const from = Math.min(...legs.map((l) => l.start));
+  const to = Math.max(...legs.map((l) => l.end));
+  const span = to - from;
+  const sum = legs.reduce((a, l) => a + (l.end - l.start), 0);
+  const bound = exact ? "exact" : "lower";
+  return {
+    launch: index,
+    from: new Date(from).toISOString(),
+    to: new Date(to).toISOString(),
+    legs: legs.length,
+    max_concurrent: max,
+    max_concurrent_at: at === null ? null : new Date(at).toISOString(),
+    max_concurrent_bound: bound,
+    // Reported beside the outer figure, never instead of it, and with its own coverage count: an
+    // inner figure over 2 of 6 legs is not evidence the other four ran alone.
+    max_concurrent_inner: inner.max,
+    max_concurrent_inner_legs: inner.legs,
+    // The two ends disagreeing is a fact about the RECORD, not about the run, and it is the only
+    // signal that separates a leg that ran long from a leg something ingested later.
+    ends_disputed: max !== null && inner.max !== null && inner.legs === legs.length && max > inner.max,
+    span_ms: span,
+    span_bound: bound,
+    sum_leg_ms: sum,
+    sum_leg_bound: bound,
+    speedup: exact && span > 0 ? Math.round((sum / span) * 100) / 100 : null,
+    speedup_refused_because: exact
+      ? (span > 0 ? null : "the launch's legs span zero milliseconds — nothing to divide by")
+      : `${legs.filter((l) => l.bound !== "exact").length} of ${legs.length} leg(s) end at a T0 landmark rather than a completion record, so both the span and the work sum are floors; their ratio bounds nothing`,
+    waves_observed: wavesObserved(legs),
+    scopes: [...new Set(legs.map((l) => l.scope_id))].sort(),
+  };
+}
+
+/**
+ * Which fan-out width the run was launched with — read, never assumed.
+ *
+ * The dial is written into `run-args.json` by the launcher. It is absent from every run recorded so
+ * far, so the honest answer is the effective default WITH the fact that it is a default: reporting
+ * `4` unqualified would assert an operator choice nobody made.
+ *
+ * @param {string} runRoot - The run's LOCAL root.
+ * @returns {{max_parallel_scopes:number, source:string}} The value and where it came from.
+ */
+export function dialFrom(runRoot) {
+  try {
+    const a = JSON.parse(readFileSync(join(runRoot, "run-args.json"), "utf8"));
+    const n = Number(a?.maxParallelScopes);
+    if (Number.isFinite(n) && n >= 1) return { max_parallel_scopes: n, source: "run-args" };
+    return { max_parallel_scopes: DEFAULT_MAX_PARALLEL_SCOPES, source: "default (run-args.json declares none)" };
+  } catch {
+    return { max_parallel_scopes: DEFAULT_MAX_PARALLEL_SCOPES, source: "default (no run-args.json)" };
+  }
+}
+
+/**
+ * The whole report for one run root.
+ *
+ * @param {string} runRoot - The run's LOCAL root (`<cwd>/.shapeup/<slug>`, or an archived copy).
+ * @param {object} [opts] - `{round, gapS}`.
+ * @returns {object} A byte-stable report — no clock reading anywhere in it, arrays sorted, key
+ *   order fixed by this literal — so two runs over one tree produce identical bytes.
+ */
+export function report(runRoot, { round = null, gapS = DEFAULT_GAP_S } = {}) {
+  const receipts = readLedger(join(runRoot, "receipts", "dispatch.jsonl"));
+  const legLedger = readLedger(join(runRoot, "legs.jsonl"));
+  const trials = readLedger(join(runRoot, "t0", "trials.jsonl"));
+
+  const { starts, phase_dispatches } = startsFrom(receipts.rows);
+  const scoped = round === null ? starts : starts.filter((s) => s.round === round);
+  const legs = pairLegs(scoped, legLedger.rows, trials.rows);
+  const usable = legs.filter((l) => l.end !== null);
+
+  const warnings = [];
+  if (!receipts.present) {
+    warnings.push("no receipts/dispatch.jsonl — nothing recorded a dispatch, so no leg has a start. " +
+      "An empty report here means the record set is empty, not that the run was sequential.");
+  }
+  if (!legLedger.present) {
+    warnings.push("no legs.jsonl — this run was recorded before leg completions were written, so every " +
+      "end falls back to the T0 landmark and every figure below is a floor.");
+  }
+  for (const l of [["receipts/dispatch.jsonl", receipts], ["legs.jsonl", legLedger], ["t0/trials.jsonl", trials]]) {
+    if (l[1].malformed) warnings.push(`${l[0]}: ${l[1].malformed} unparseable line(s) skipped`);
+  }
+  const unkeyed = legs.filter((l) => !l.run_id).length;
+  if (unkeyed) {
+    warnings.push(`${unkeyed} of ${legs.length} leg(s) carry no run_id — order_id alone repeats across ` +
+      "runs of one slug, so those rows cannot be attributed to this run rather than another.");
+  }
+
+  const launches = segment(usable, gapS * 1000).map((g, i) => summarise(i + 1, g));
+
+  const best = launches.reduce((a, b) => (b.max_concurrent > (a?.max_concurrent ?? -1) ? b : a), null);
+  // The launch the headline verdict is answered from, chosen on the INNER figure. Taking the inner
+  // number off `best` would compare two different launches: the widest outer overlap and the widest
+  // inner one need not be the same launch, and mixing them would let one launch's ingest artefact
+  // stand beside another launch's honest evidence.
+  const bestInner = launches.reduce((a, b) => (b.max_concurrent_inner > (a?.max_concurrent_inner ?? -1) ? b : a), null);
+  return {
+    schema_version: 1,
+    run_root: runRoot,
+    run_id: runIdFromRoot(runRoot),
+    receipt_present: existsSync(join(runRoot, RECEIPT_FILE)),
+    round,
+    dial: dialFrom(runRoot),
+    completeness: {
+      // The absence, in the same value as the number. `max_concurrent` below is meaningless without
+      // these four counts, so they are not an appendix.
+      legs_total: legs.length,
+      legs_exact: legs.filter((l) => l.bound === "exact").length,
+      legs_lower_bound: legs.filter((l) => l.bound === "lower").length,
+      no_completion_record: legs.filter((l) => l.end === null).length,
+      legs_unkeyed: unkeyed,
+      phase_dispatches_excluded: phase_dispatches,
+      end_sources: {
+        "leg-record": legs.filter((l) => l.end_source === "leg-record").length,
+        "t0-landmark": legs.filter((l) => l.end_source === "t0-landmark").length,
+        none: legs.filter((l) => l.end_source === null).length,
+      },
+    },
+    concurrency: {
+      max_concurrent: best ? best.max_concurrent : null,
+      bound: best ? best.max_concurrent_bound : null,
+      at: best ? best.max_concurrent_at : null,
+      launch: best ? best.launch : null,
+      max_concurrent_inner: bestInner ? bestInner.max_concurrent_inner : null,
+      // The acceptance predicate, answered rather than left to the reader — and `null` when the
+      // record set cannot answer it, which is a third state and not a "no".
+      //
+      // ANSWERED FROM THE INNER INTERVALS WHEN THEY COVER EVERY LEG, because that is the only form
+      // of the evidence an out-of-band ingest cannot fabricate. A run with dial 1 has been observed
+      // reporting `max_concurrent: 2 (exact)` because one leg was ingested long after it finished; the
+      // inner intervals said 1, which was the truth. Where the two disagree the answer is
+      // `"disputed"` rather than either number — a fourth state, and the honest one.
+      two_or_more_concurrent: !best ? null
+        : (bestInner && bestInner.max_concurrent_inner_legs === bestInner.legs)
+          ? (bestInner.max_concurrent_inner >= 2 ? true : (best.max_concurrent >= 2 ? "disputed" : false))
+          : best.max_concurrent >= 2,
+      disputed_because: (best && bestInner && bestInner.max_concurrent_inner_legs === bestInner.legs
+        && bestInner.max_concurrent_inner < 2 && best.max_concurrent >= 2)
+        ? "the overlap exists only between intervals that END AT AN INGEST; measured against each leg's own " +
+          "T0 trial — an instant the leg provably occupied — no two legs were open together. An ingest run " +
+          "outside its leg (a repair, a --no-receipt-check rescue, a relaunch re-applying a result) stamps a " +
+          "later end onto the row and manufactures exactly this overlap."
+        : null,
+    },
+    launches,
+    segmentation: {
+      rule: "a quiet period longer than gap_s starts a new launch",
+      gap_s: gapS,
+      launches: launches.length,
+      note: "heuristic: nothing in the record set identifies a launch, and one run_id spans every relaunch",
+    },
+    legs: legs.map((l) => ({
+      order_id: l.order_id,
+      scope_id: l.scope_id,
+      round: l.round,
+      attempt: l.attempt,
+      run_id: l.run_id,
+      started_at: new Date(l.start).toISOString(),
+      start_source: l.start_source,
+      ended_at: l.end === null ? null : new Date(l.end).toISOString(),
+      end_source: l.end_source,
+      duration_ms: l.end === null ? null : l.end - l.start,
+      bound: l.bound,
+      // The leg's own mid-flight landmark and how far its recorded end sits past it. Reported for the
+      // reader to judge rather than thresholded, deliberately: a leg that closed inside itself and one
+      // ingested out of band differ by orders of magnitude on any single machine, and by nothing
+      // reliable ACROSS machines — so no constant that separates them here would survive slower
+      // hardware. The lag is the fact; what counts as suspicious is the reader's call.
+      inner_ended_at: l.inner_end === null ? null : new Date(l.inner_end).toISOString(),
+      end_lag_ms: (l.end === null || l.inner_end === null) ? null : l.end - l.inner_end,
+    })),
+    warnings,
+  };
+}
+
+/**
+ * Render the report as a table for a human, from the already-built object.
+ * @param {object} r - A {@link report}.
+ * @returns {string} The human view.
+ */
+export function table(r) {
+  const c = r.completeness;
+  const lines = [
+    `run_root      ${r.run_root}`,
+    `run_id        ${r.run_id ?? "(none — records cannot be attributed to a run)"}`,
+    `dial          maxParallelScopes=${r.dial.max_parallel_scopes} (${r.dial.source})`,
+    `legs          ${c.legs_total} total · ${c.legs_exact} exact · ${c.legs_lower_bound} lower-bound · ${c.no_completion_record} with NO completion record` +
+      `${c.phase_dispatches_excluded ? ` (+${c.phase_dispatches_excluded} non-build dispatch(es) excluded)` : ""}`,
+    `concurrency   ${r.concurrency.max_concurrent ?? "unmeasurable"}` +
+      `${r.concurrency.max_concurrent === null ? "" : ` (${r.concurrency.bound}) at ${r.concurrency.at}`}` +
+      `${r.concurrency.max_concurrent_inner === null ? "" : ` · ${r.concurrency.max_concurrent_inner} measured inside the legs' own T0 windows`}`,
+    `≥2 concurrent ${r.concurrency.two_or_more_concurrent === null ? "UNKNOWN — no leg in scope has a usable interval" : r.concurrency.two_or_more_concurrent}`,
+    ...(r.concurrency.disputed_because ? [`  ! ${r.concurrency.disputed_because}`] : []),
+  ];
+  for (const l of r.launches) {
+    lines.push(`  launch ${l.launch}  ${l.from} → ${l.to}  legs=${l.legs} max=${l.max_concurrent} (${l.max_concurrent_bound})` +
+      `  span=${(l.span_ms / 1000).toFixed(1)}s  work=${(l.sum_leg_ms / 1000).toFixed(1)}s  speedup=${l.speedup ?? "refused"}`);
+    if (l.speedup === null) lines.push(`     refused: ${l.speedup_refused_because}`);
+    for (const w of l.waves_observed) lines.push(`     wave  ${w.scopes.join(" + ")}`);
+  }
+  for (const w of r.warnings) lines.push(`  ! ${w}`);
+  return lines.join("\n");
+}
+
+/** The typed argv contract (see `./lib/argv.mjs`). */
+export const ARGV_SPEC = {
+  usage: "harness.mjs probe concurrency (--slug <slug> | --run-root <dir>) [--cwd <dir>] [--round N] " +
+         "[--gap-s N] [--format json|table]",
+  _: { arity: 0, max: 0, name: "(no positional operands)" },
+  slug: { type: "str" },
+  // The archived-trace and post-export cases, and the same escape `verify t0 --out` has: a caller
+  // that already holds the run root should not have to reconstruct a slug from a directory name.
+  "run-root": { type: "path" },
+  cwd: { type: "path" },
+  round: { type: "int", min: 1 },
+  "gap-s": { type: "int", min: 1, default: DEFAULT_GAP_S },
+  format: { type: "enum", values: ["json", "table"], default: "json" },
+};
+
+/**
+ * Report a run's leg concurrency, span and observed waves.
+ *
+ * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
+ * @returns {void} Exits 0 when at least one leg had a usable interval, 1 when none did — and the
+ *   report prints either way, because "nothing was measurable" is the answer, not an error.
+ */
+export function cli(rawArgv) {
+  const args = runArgs(ARGV_SPEC, rawArgv);
+  if (!args.slug && !args.runRoot) {
+    process.stderr.write(JSON.stringify({ error: "missing_required", flag: "--slug", expected: "a slug, or --run-root <dir>" }) + "\n");
+    process.stderr.write(`usage: ${ARGV_SPEC.usage}\n`);
+    process.exit(2);
+  }
+  const runRoot = args.runRoot
+    ? resolve(args.runRoot)
+    : localRoot(resolve(args.cwd || process.cwd()), args.slug);
+
+  const r = report(runRoot, { round: args.round ?? null, gapS: args.gapS });
+  console.log(args.format === "table" ? table(r) : JSON.stringify(r));
+  process.exit(r.launches.length ? 0 : 1);
+}

package/{skills/tech-lead/scripts/aegis-digest.mjs → kernel/probe/digest.mjs}

@@ -10,8 +10,7 @@
 //
 // Zero dependencies, zero network — same discipline as oracles/*.
 
-import { isMain } from "./lib/is-main.mjs";
-import { runArgs } from "./lib/argv.mjs";
+import { runArgs } from "../lib/argv.mjs";
 
 const PATTERNS = [
   // Node stack frame:  "    at fn (path/to/file.js:12:34)"  or  "    at path/to/file.js:12:34"
@@ -92,16 +91,19 @@ export function digest(rawText) {
 // --- CLI ---------------------------------------------------------------------
 /** The typed argv contract (see `./lib/argv.mjs`). A bare `-`, or nothing, means stdin. */
 export const ARGV_SPEC = {
-  usage: "aegis-digest.mjs [<log-file>|-]   (no file → stdin)",
+  usage: "harness.mjs probe digest [<log-file>|-]   (no file → stdin)",
   _: { arity: 0, max: 1, name: "log-file" },
 };
 
 /**
- * CLI entry: read a log from a file arg or stdin, print the digested triples as JSON, exit 0.
- * @returns {Promise<void>} Resolves after printing.
+ * Digest a build log into AEGIS triples on stdout.
+ *
+ * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
+ * @returns {(Promise<void>|void)} Settles when the subcommand has written its output; most paths
+ *   call `process.exit()` with the subcommand's documented code rather than returning.
  */
-async function main() {
-  const arg = runArgs(ARGV_SPEC)._[0];
+export async function cli(rawArgv) {
+  const arg = runArgs(ARGV_SPEC, rawArgv)._[0];
   let raw;
   if (arg && arg !== "-") {
     const { readFileSync } = await import("node:fs");
@@ -119,6 +121,3 @@ async function main() {
   process.exit(0);
 }
 
-if (isMain(import.meta.url)) {
-  main();
-}

package/kernel/probe/eval.mjs

@@ -0,0 +1,77 @@
+// probe eval — "what did round N's EVAL WorkResult actually say?"
+//
+// CONTRACT. A bounded, read-only query over the evaluate WorkResult ingest already wrote. Prints
+// `{ok, overall, bug_count, report_path}` on stdout; exits 0 when found and readable, 1 when the
+// result is missing (nothing ran, or ingest hasn't landed yet), 2 on a bad argv. Writes nothing.
+//
+// WHY THIS EXISTS. `shapeup-run.js` cannot read a file itself (a Workflow script has no filesystem
+// of its own — see this repo's own note on why it may not call `Date.now()`), so every fact it
+// branches on has to cross an `agent()`/`query()` boundary. Before this command existed, the EVAL
+// round-loop branch (`verdict = e.overall === "PASS" ? "pass" : "fail"`) trusted the DISPATCHING
+// sub-agent's own end-of-turn summary — a value composed from memory/judgment after three other
+// steps (compile, dispatch, ingest), schema-checked for SHAPE only. Nothing re-verified that
+// summary against the WorkResult `reduce ingest` had just written to disk. Measured live
+// (2026-08-19, todo-cli): `results/evaluate-r1.json`'s `verdict.overall` was `"FAIL"` (2 cited
+// bugs, `spec-evaluator` correctly failing `SC-ERR`), and the run proceeded straight to QA and
+// GATE H anyway — the exact shape `verdict = e.overall === "PASS"` allows when `e.overall` is a
+// self-report that drifted from the artifact it was supposed to summarize. This command closes
+// that gap the same way `probe t0` already closes it for the T0 ratchet: a narrow, single-purpose
+// "transcribe this JSON verbatim" query over the artifact itself, not a multi-step summary.
+//
+// WHY IT READS `results/evaluate-r<N>.json` AND NOT THE `.md` REPORT. The WorkResult is the
+// machine-checked envelope `reduce ingest` validated against `EVAL`'s schema before ever touching
+// shared state; the `.md` report is prose for a human. Reading the prose to re-derive a verdict a
+// schema already carries structurally is the paraphrase channel this repo's hooks exist to close
+// everywhere else.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { runArgs } from "../lib/argv.mjs";
+import { resultsDir } from "../lib/paths.mjs";
+
+/**
+ * Read one round's EVAL verdict straight from the WorkResult `reduce ingest` wrote.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @param {number} round - The EVAL round (`evaluate-r<N>.json`).
+ * @returns {{found: boolean, overall: (string|null), bug_count: (number|null),
+ *   report_path: (string|null)}} `found: false` when no result exists yet — a fact, not a guess.
+ */
+export function evalVerdict(cwd, slug, round) {
+  const path = join(resultsDir(cwd, slug), `evaluate-r${round}.json`);
+  if (!existsSync(path)) return { found: false, overall: null, bug_count: null, report_path: null };
+  let doc;
+  try { doc = JSON.parse(readFileSync(path, "utf8")); }
+  catch { return { found: false, overall: null, bug_count: null, report_path: null }; }
+  const v = doc?.verdict || {};
+  const overall = v.overall === "PASS" || v.overall === "FAIL" ? v.overall : null;
+  return {
+    found: overall !== null,
+    overall,
+    bug_count: Array.isArray(v.bugs) ? v.bugs.length : null,
+    report_path: typeof v.report_path === "string" ? v.report_path : null,
+  };
+}
+
+export const ARGV_SPEC = {
+  usage: "harness.mjs probe eval --slug <slug> --round N [--cwd <dir>]",
+  _: { arity: 0, max: 0, name: "(no positional operands)" },
+  slug: { type: "str", required: true },
+  round: { type: "int", min: 1, required: true },
+  cwd: { type: "path" },
+};
+
+/**
+ * Report round N's EVAL verdict, mechanically, from the WorkResult on disk.
+ *
+ * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
+ * @returns {void} Exits 0 when a verdict was found, 1 when none exists yet for this round.
+ */
+export function cli(rawArgv) {
+  const args = runArgs(ARGV_SPEC, rawArgv);
+  const cwd = resolve(args.cwd || process.cwd());
+  const { found, overall, bug_count, report_path } = evalVerdict(cwd, args.slug, args.round);
+  console.log(JSON.stringify({ ok: found, overall, bug_count, report_path, round: args.round }));
+  process.exit(found ? 0 : 1);
+}