diff --git a/docs/dogfooding.md b/docs/dogfooding.md
index 2c39ca7..331da38 100644
--- a/docs/dogfooding.md
+++ b/docs/dogfooding.md
@@ -65,6 +65,339 @@ Config layers are `defaults ← user ← project ← env`, so an environment var
 beats the file (`PI_BGRUN_SHOW_COMPLETED=0`, `PI_BGRUN_MAX_LOG_BYTES=0`). To drop
 the setup, delete `$CONFIG_DIR/pi-bgrun.json`; nothing else depends on it.
 
+## How these numbers are produced
+
+Every number below comes from a session transcript, not from an impression of
+what the tool does. The method is fixed here so a later run is comparable to
+these ones — and because a fixture we can tune is also a fixture we could tune
+in our own favour, it is fixed *before* the runs, predictions included.
+
+### The protocol
+
+| element | definition |
+|---|---|
+| arms | **vanilla**: `pi -ne -ns` plus the provider extension. **bgrun**: the same, plus `-e extension/index.ts`. **vanilla-hinted** (control, below) |
+| model | one provider and model per comparison (`bifrost-openai/fireworks/deepseek-v4.1-flash` here) |
+| prompt | identical within a pair except the mechanism clause: `Run '<cmd>' in this repo and report the failure details.` vs `…as a background job with bgrun, and report the failure details once it finishes.` |
+| sessions | **live** for every bgrun arm: a one-shot `pi -p` exits before the wake is delivered, so those runs need a human present. Vanilla arms block and report on their own, so they are scripted |
+| samples | 3 per arm, reported as median **and** range. A single run is stated as such |
+| metrics | from the transcript: suite executions, blocked-on-output, idle, session wall, context chars, per-call (wait, size), the exact commands, and whether the failure diagnostic reached context at all |
+| re-derive | `bun scripts/measure-sessions.ts <session-dir…>` — the committed profiler, so any table here can be recomputed from the transcripts |
+
+The **vanilla-hinted** control matters: it asks vanilla pi to redirect the run to
+a file and grep it. That is the technique bgrun implements, hand-rolled by the
+agent, and it is the strongest baseline in the set — if bgrun cannot beat it, the
+tool is a convenience rather than a capability.
+
+### Pre-registered expectations
+
+Written down before the runs, including the cells where the tool is expected to
+*lose*. Cells that contradict their prediction are findings, not failures to
+explain away.
+
+| cell | scenario | predicted winner | of what, and what would falsify it |
+|---|---|---|---|
+| R1 | the repo's own suite: green, 224 tests, ~22s, ~340 lines | **vanilla** | nothing blocks and the output is small; bgrun adds a job, a wake and a read. Falsified if the digest makes the bgrun session cheaper overall |
+| R2 | red, failure **78–90 lines from the end** | **vanilla** | a `tail -40` window hits it, one call, no wait — the pytest/jest shape |
+| R3 | generated suite at the **standard density**: ~180s, **694** lines, failure 65% through | **bgrun** | the failure sits ~250 lines from the end, so no `head`/`tail` window reaches it and vanilla buys a second full run. The long-suite row measured below used the *verbose* density and is being re-run under this one |
+| R4 | **same volume, no time**: generated with `DUMMY_SLEEP_MS=20`, `DUMMY_LINES_PER_TEST=8` | **bgrun** on completeness, **vanilla** on cost | isolates volume from duration. If one or two greps find the failure, vanilla is cheaper and bgrun's advantage is time, not size |
+| R5 | **fail-fast**: `DUMMY_FAIL_FAST=1`, the run collapses at the failure | **vanilla** | when a failure ends the work early the blocking cost is small, and the wake is pure overhead |
+| C1 | start the long suite, then do an unrelated ~60s task in the same session | **bgrun** | overlap is the actual niche: wall ≈ max(180, 60) against 240. **Falsified if the agent waits anyway** — a plausible outcome worth measuring |
+| C2 | three long suites at once | **bgrun** | a foreground agent serialises them (≈3 × 180s); jobs run concurrently |
+| C3 | restart the session mid-run | **bgrun** | the log outlives the session; a foreground run's output dies with it |
+| C4 | "which part is it on right now?" | **bgrun** | `bgtail` answers mid-run; a foreground command cannot be asked |
+| D1 | a weaker or faster model | **unknown** | hypothesis: if bgrun's value is reliability (no guessing, no re-running), it should grow as the agent weakens. If the advantage holds only for the strong model, that story is wrong |
+
+C1–C4 are dialogues rather than fixtures: no generated suite can express them,
+because the thing under test is what the session does *while* a job runs and what
+survives afterwards.
+
+### The fixture, and why it is shaped that way
+
+`bun run bench:make-suite` generates the long, noisy, failing suite
+(`scripts/make-dummy-suite.ts`). It is generated rather than committed because
+`bun test` discovers `*.test.ts` anywhere in the tree and does **not** respect
+`.gitignore` (measured) — a committed fixture would run inside every developer's
+bare `bun test` and cost them minutes. So it defaults outside the repo, and the
+script refuses to write inside it, fatally, because it clears its output
+directory before writing and could otherwise delete tracked files.
+
+What it builds, and why each property is the thing under test:
+
+- **Long**: 300 tests over 10 files, ~180s by default. Every test awaits one
+  chain shared through `globalThis`, so wall-clock is `sleep × tests` whatever
+  the runner's scheduling does — bun 1.3.6 happens to run them sequentially, and
+  a concurrent scheduler would otherwise collapse a naive per-test sleep.
+- **Noisy**: each test logs a tunable number of lines. The default is **realistic**
+  (2, against bun's own ~1.5 lines per test); `DUMMY_LINES_PER_TEST=8` reproduces
+  the verbose density the earliest measurements here used, which matters when
+  comparing against them. Measured: **694** output lines at the default density,
+  **2,494** at `=8`.
+- **Failing in the middle**: one planted test asserts a marker pair at 65% of the
+  run, so no `head`/`tail` window reaches it and the failure's *position* is under
+  test rather than its existence. The 65% is measured, and now explained: bun 1.3.6
+  discovers these files in a **non-lexical** order (`2,3,1,8,9,10,5,4,6,7`,
+  measured twice), so `part-05` runs seventh of ten while `DUMMY_FAIL_FILE=5`
+  reads as 45%.
+- **Honest failure shape**: the failure block looks like a real assertion failure
+  (assertion, expected vs received, stack naming the generated file and line, and a
+  footer — ~19 lines) rather than a two-line stub, so the output volume a red run
+  really produces is not understated.
+- **Knobs for the negative cells**: `DUMMY_FAIL_FAST=1` ends the run at the
+  failure, which is the regime where a background job should have nothing to
+  offer; `DUMMY_FILES`/`DUMMY_TESTS_PER_FILE`/`DUMMY_FAIL_FILE`/`DUMMY_FAIL_STEP`
+  move the size and the failure's position. Measured at smoke scale: fail-fast
+  finished in **4.09s** against **6.29s**, i.e. it stops at the fraction of the run
+  that had already completed before the failure in bun's order — 65%, not the 45%
+  a lexical order would give.
+
+The script validates its own fixture: the planted failure must exist, or the
+generated run would silently invalidate the measurement it was made for.
+
+### What this method cannot see
+
+- It is one machine, one checkout, one model, and mostly n=3. The spread across
+  runs is large enough that single numbers are anecdotes.
+- Context is counted in characters of transcript text, not billed tokens.
+- The fixture is synthetic. Real suites fail in ways this one does not: flaky
+  tests, skips, retries, parallel workers, enormous stack traces.
+- Live sessions make bgrun's cells expensive to reproduce — a reviewer cannot
+  re-run them unattended, which is itself a property of the tool worth naming.
+- The metrics split into two kinds, and only one is stable: **executions and
+  blocked time are the mechanism's** (the agent cannot block on a job that runs
+  detached), while **context and wall-clock are the agent's** (it chooses what to
+  read and when to look). Stable columns are evidence about `bgrun`; unstable
+  ones are evidence about the agent's use of it, and the reports below say which
+  is which.
+
+### Running a cell by hand
+
+The vanilla cells are scripted (`pi -ne -ns -e <provider> -p --session-dir <dir> -n <label> "<prompt>"`).
+The bgrun cells cannot be: the wake needs a live session, so each is a real
+session with a human in it. Per run:
+
+1. Fresh session in a clean checkout, the bgrun extension loaded, nothing else in
+   the transcript — a resumed or reused session contaminates the context count.
+2. Send the cell's prompt verbatim (the mechanism clause is the only difference
+   from its pair), then **do nothing**: no follow-up nudges, no "is it done", no
+   hints. The wake is the mechanism under test; prodding it changes the run.
+3. Let the agent finish on its own, then note the session directory.
+4. `bun scripts/measure-sessions.ts <session-dir>` for the row.
+
+Two things worth resisting: re-running a cell whose number looks wrong (that is
+sampling on the outcome), and comparing a bgrun cell measured in a live session
+against a vanilla cell measured one-shot without saying so in the table.
+
+## Measured effect on context
+
+Three ways the same suite run (`bun test extension/index.test.ts`, 224 tests,
+~22s) lands in a pi session. Every arm: same provider and model
+(`bifrost-openai/fireworks/deepseek-v4.1-flash`), same checkout, extension
+discovery off (`-ne`) with only the provider extension loaded — plus this repo's
+extension in the bgrun arm.
+
+| arm | prompt | what pi chose | context chars |
+|---|---|---|---|
+| C | "run this **exact** command with your bash tool" | the command bare, blocking | **21,176** — one tool result carrying the full 241-line output (21,005) |
+| E | "run it and tell me whether it passed" | `bun test … 2>&1 \| tail -40`, blocking | **3,530** — last 40 lines only |
+| D | "start it as a background job" | `bgrun`, woke on the digest, one 60-line `bgtail` | **6,127** — full log still on disk |
+
+**Arm E, not arm C, is the naive baseline.** Asked neutrally, an agent bounds the
+output itself with `| tail -40`; arm C is what a directive prompt produces. So the
+claim is not "fewer context characters" — against a tail-ing agent bgrun costs
+*more* context (6,127 vs 3,530) and buys instead:
+
+- the session is not blocked for the run;
+- the exit status is real: `cmd | tail -40` reports *tail's* status, not the
+  command's, so a red suite reads as green (measured: direct run exit 1, piped run
+  exit 0);
+- nothing is truncated: exit code, stats, and all 240 log lines survive on disk,
+  where `| tail -40` discards everything before the last 40 lines. Runners that
+  print failures *in place* (bun, go, make) leave the failure diagnostic above
+  that window — the summary still names the failing test, so what is missing is
+  the *reason*, and a capable agent gets it back by running the suite again (see
+  [When the suite fails](#when-the-suite-fails) below);
+- the wake carries the digest (`224 pass / 0 fail`) in 368 characters, so the
+  common case needs no read at all;
+- further reads are bounded and incremental — delta `bgtail`, capped `bggrep`.
+
+"Context chars" counts every non-empty `text` and `thinking` content part in the
+session JSONL, so tool output counts wherever a provider files it: the same
+experiment with the full extension set on the `cursor` provider put the identical
+~21 KB in a `thinking` part rather than a tool result (21,522 vs 10,054 across that
+pair — not a controlled comparison, only a cross-provider sanity check).
+
+Caveats for the table above: n=1 per arm, one suite. The bgrun arm's 2.5 KB read is
+the agent's own choice, so a session that reads more of the log narrows the context
+gap by design — that is the escape hatch working, not a measurement flaw. The
+failure pair below is n=3 per arm.
+
+### The baseline is not stable
+
+That table is one run per arm, and the arm that matters — the neutral ask — is the
+least stable one. Three runs of it under the standard protocol (`R1`: one-shot
+`pi -p`, same command, same wording, same model) spent:
+
+| run | context chars | what it read |
+|---|---|---|
+| 1 | **4,894** | a bounded tail |
+| 2 | **5,018** | a bounded tail |
+| 3 | **21,787** | the whole 241-line run |
+
+Same prompt, same command, **4.4×** the context, because the window is the agent's
+guess and the guess varies. The bgrun column has no equivalent mode: the log's size
+is fixed on disk and the digest is what the wake carries (368 chars), so the cheap
+outcome does not depend on the model choosing well that day. That is a claim about
+**variance, not about the median** — and it is the more useful claim, because the
+median vanilla run is cheaper than bgrun and always will be.
+
+### When the suite fails
+
+Same setup and the same ask ("report the failure details"), but every run in a
+**live session** — a one-shot harness cannot hold a session open for the wake, which
+is why this pair is measured by hand. Identical command: the repo's suite plus a
+fixture whose first test fails — 340 lines, 23 s, exit 1, with the failure
+diagnostic at lines 250–262, i.e. **78–90 lines from the end**. Three runs per arm:
+
+| | vanilla pi | bgrun |
+|---|---|---|
+| suite executions | 3, 4, 1 — median **3** | 1, 1, 1 — median **1** |
+| blocked waiting on output | 66.0s, 45.4s, 22.1s — median **45.4s** | 0.0s, 0.0s, 0.0s |
+| session wall | 81.6s, 56.5s, 31.8s — median **56.5s** | 32.9s, 29.3s, 33.6s — median **32.9s** |
+| context chars | 23,597, 12,791, 4,722 — median **12,791** | 6,277, 10,603, 7,087 — median **7,087** |
+| diagnostic reached context | yes, all three | yes, all three |
+
+The spread is the agent guessing where the failure sits. Vanilla's three runs each
+opened with a different window, against the same command:
+
+| run | first window | hit | executions | context |
+|---|---|---|---|---|
+| 1 | `… \| head -200` | no | 3 | 23,597 |
+| 2 | `… \| tail -60` | no | 4 | 12,791 |
+| 3 | `… \| tail -100` | yes | 1 | 4,722 |
+
+`tail -100` reaches past line 250; `tail -60` does not; `head -200` misses *and*
+carries 17.6 KB of the wrong output. So a run costs one execution or four depending
+on a guess, at 22s per losing bet. bgrun never varied — one execution, nothing
+blocked, ~30s, every time — because **the log removes the guess**: whatever window
+the agent picks, the output is still there to read.
+
+Two honest notes. bgrun's *best* case is not better than vanilla's: run 3 was
+cheaper (4,722 chars against bgrun's 6,277–10,603) and about as fast. What bgrun
+buys is the absence of the bad case — 4 executions, 82s, 23.6 KB — not a better
+median. And the position of the failure is what makes it a guess: a runner that
+summarises failures at the very end (pytest, jest) would be hit by `tail -40` every
+time.
+
+Three further vanilla runs of the same command and ask under the standard protocol
+(`R2`: one-shot `pi -p`) came out better than the three above — executions **1, 3,
+1**; blocked **21.8s, 66.2s, 21.9s**; context **3,641 / 23,034 / 4,719** chars. Six
+vanilla runs of the same command therefore read: median one execution and ~4.7 KB,
+worst four executions, 66.2s blocked and 23 KB. Rounding that to "the agent runs it
+three times" would overstate the typical case, so both samples stay here. The
+spread is the finding, and in all six runs the tail *did* eventually reach the
+diagnostic — this fixture punishes a bad window with another run, not with a missed
+failure. At 22s a run that is a tolerable tax; at 180s it is the whole afternoon,
+which is what the next section measures.
+
+### When the suite is long and noisy
+
+The repo's own suite is 340 lines in 22s — neither. This section uses a generated
+one (`bun run bench:make-suite`, see `scripts/make-dummy-suite.ts`): 300 tests over
+10 files, ~180s, ~2,760 lines as generated at the time (2,494 with the current
+generator at that same density, 694 at the realistic default), failing 65% of the
+way through so no `head`/`tail`
+window reaches it. Nothing about the command telegraphs its volume. Note the
+density, though: this run used the fixture's then-default of 8 log lines per test,
+which is *verbose* — bun's own reporter prints ~1.5 lines per test, which is what
+the generator now defaults to. So the volume here is an upper bound on what a real
+300-test suite emits; the R4 cell exists to separate volume from duration. One run
+per arm, both in live sessions:
+
+| | vanilla pi | bgrun |
+|---|---|---|
+| suite executions | **2** | **1** |
+| blocked waiting on output | **359.9s** | **0.0s** |
+| session wall | 372.7s | 189.4s |
+| tool calls | 4 | 5 |
+| context chars | 10,016 | 8,049 |
+| failure found | yes | yes |
+
+Vanilla opened with `… 2>&1 | head -100` — the first ~4% of the run, while the
+failure sits at 65% — so it paid a **second full 180s execution** into a file before
+it could grep and slice the block. bgrun ran the suite once, took the wake when it
+came, and read the log afterwards.
+
+Worth noting on the bgrun side: two of its five calls came *before* the wake —
+`bgstatus` (200 chars) and a 40-line `bgtail` (2,031 chars), together **28% of its
+context**, spent learning what the wake then delivered for free. That is the
+behaviour the guidance now discourages: do not poll a job you just started.
+
+This row is the **verbose-density** variant of the long-suite cell, measured
+before the fixture gained a realistic default. Under the standard protocol it is
+R3 with 694 lines of output instead of ~2,760, and it needs re-measuring before its
+numbers can sit next to R1/R2's — the failure's distance from the end changes with
+the density, and that distance is the whole mechanism. The vanilla half is
+scriptable and cheap; the bgrun half needs a live session, like every other bgrun
+cell.
+
+## Where bgrun helps, and where it does not
+
+The summary the measurements above actually support — kept separate from the
+sales pitch, because the interesting boundary is where the tool stops paying for
+itself.
+
+### Where it helps
+
+- **Long runs.** The blocking cost scales with runtime, and a losing guess costs
+  another whole run: on the 180s fixture, vanilla spent **359.9s** waiting across
+  two executions while bgrun spent **0.0s** across one.
+- **Output no window reaches.** The failure at 65% of 2,760 lines is invisible to
+  `head`/`tail`; a log on disk is still complete after the fact, and `bggrep`
+  addresses it.
+- **Doing something else meanwhile.** The genuine niche, and the least measured
+  cell so far (C1): a job runs while the session works on something else, and
+  three jobs run at once where a foreground agent can only serialise them (C2).
+- **When the session might not survive the run.** The log outlives the session:
+  a restart, a resume, a later session, or another agent can still read it, where
+  a foreground run's output is gone with the context that held it (C3).
+- **Asking about a run in progress** — `bgtail` mid-run (C4); a foreground command
+  cannot be asked where it is, only finished.
+- **When nobody wants to read the log at all.** The digest puts `224 pass / 0 fail`
+  in the wake in 368 characters, which is the common case needing no read.
+
+### Where it is weak, or not obviously better
+
+- **Against an agent that bounds its own output.** Asked neutrally, pi runs
+  `| tail -40` and spends **3,530** chars; bgrun spent **6,127**. bgrun costs
+  *more* context in the simple case — it buys non-blocking and completeness, not
+  economy.
+- **When the failure is at the end of the output.** pytest and jest summarise
+  where the tail already reaches, so one call hits it with no wait (R2).
+- **Against an agent that hand-rolls the technique.** In R3, vanilla's second
+  execution redirected to a file and grepped it — that *is* bgrun's mechanism,
+  reached without the tool. What remains is convenience: the wake, the exit
+  status, the bookkeeping, the bounded reads.
+- **Short commands.** Nothing to overlap mid-run and nothing worth surviving; the
+  tool's own guidance says not to bother.
+- **Fail-fast runs** (R5): the failure ends the work early, so there is little
+  waiting to avoid and the wake is overhead.
+- **For a human at a terminal.** `&`, `tmux`, a split pane, or just watching it
+  covers the same ground. The advantage is specific to an agent that shares one
+  context and cannot see a background process unless it is told. In CI, none of
+  this applies.
+- **The tool's own papercuts, found by measuring it** — which is the argument for
+  measuring: a pre-wake poll cost **28%** of one bgrun session's context (the
+  guidance now discourages it, #27); `bggrep` line numbers were window-relative,
+  not file-relative (#25, open); re-reading a log re-paid for the same lines until
+  delta `bgtail` shipped (#4).
+
+The strongest defensible version of the claim is the one the data shows: bgrun
+does not make the best case better — vanilla's `tail -100` run beat every bgrun
+run on cost — it removes the worst case, which is an agent guessing a window four
+times into a 180-second command. Where a session can afford to wait, or the
+failure sits where a tail finds it, plain `bash` is the better tool.
+
 ## See also
 
 - README: [Digest scorecard (opt-in)](../README.md#digest-scorecard-opt-in) — the
diff --git a/package.json b/package.json
index b8c9adb..951e8b0 100644
--- a/package.json
+++ b/package.json
@@ -28,7 +28,7 @@
     ]
   },
   "scripts": {
-    "test": "bun test extension/index.test.ts",
+    "test": "bun test extension/index.test.ts scripts/measure-sessions.test.ts",
     "lint": "tsc --noEmit",
     "lint:pr-title": "bun scripts/check-conventional-commit.ts",
     "bench:make-suite": "bun scripts/make-dummy-suite.ts"
diff --git a/scripts/make-dummy-suite.ts b/scripts/make-dummy-suite.ts
index f4daa4b..1f8739a 100755
--- a/scripts/make-dummy-suite.ts
+++ b/scripts/make-dummy-suite.ts
@@ -15,24 +15,57 @@
  *
  * WHAT IT GENERATES
  * -----------------
- * A suite that is long, noisy, and fails somewhere easy to miss:
+ * A suite that is long, noisy, structured like a real runner's output, and fails
+ * somewhere easy to miss:
  *   - LONG: every test awaits one chain shared through globalThis, so the total
  *     wall-clock is sleeps x tests however the runner schedules them. (bun 1.3.6
  *     happens to run these sequentially, but the chain makes the duration
  *     independent of that: a concurrent scheduler would otherwise collapse it.)
- *   - NOISY: each test logs 8 lines, so a run produces thousands of lines.
- *   - FAILING: one test in the middle asserts a planted marker pair, so the
- *     failure sits far from both ends of the output.
+ *   - NOISY: each test logs DUMMY_LINES_PER_TEST lines (2 by default), so a run
+ *     produces hundreds to thousands of lines without being a per-test drip: each
+ *     file opens with a banner, and the run closes with a summary block.
+ *   - FAILING: one test in the middle asserts a planted marker pair and prints a
+ *     full assertion-failure block (expected vs received, stack trace naming the
+ *     generated file and line), so the failure sits far from both ends of the
+ *     output and looks like one a real suite would emit.
  *
  * USAGE
  * -----
- *   bun scripts/make-dummy-suite.ts                      # ~180s, ~2,500 lines
+ *   bun scripts/make-dummy-suite.ts                      # ~180s at the default density
  *   DUMMY_SLEEP_MS=20 bun scripts/make-dummy-suite.ts    # fast smoke version
+ *   DUMMY_FAIL_FAST=1 DUMMY_SLEEP_MS=20 bun scripts/make-dummy-suite.ts
  *   bun test /tmp/pi-bgrun-dummy-suite                   # run the suite
  *
- * Tunables (defaults in brackets): DUMMY_OUT_DIR
- * [<system tmpdir>/pi-bgrun-dummy-suite], DUMMY_SLEEP_MS [600], DUMMY_FILES [10],
- * DUMMY_TESTS_PER_FILE [30], DUMMY_FAIL_FILE [5], DUMMY_FAIL_STEP [15].
+ * TUNABLES AND THE AXIS EACH ONE ISOLATES
+ * ---------------------------------------
+ * The comparison is not a single number, so each knob moves one axis of the
+ * methodology while the others are held fixed:
+ *   - DUMMY_SLEEP_MS [600] — the TIME axis. The sleeps are the wall-clock cost a
+ *     background job is supposed to absorb; scaling them scales the run without
+ *     touching its volume or where it fails.
+ *   - DUMMY_LINES_PER_TEST [2] — the VOLUME axis. How noisy a run is, independent
+ *     of how long it takes. 2 lines matches a normal `bun test` reporting density
+ *     (~1–1.5 lines per test); 8 is the verbose/CI-log mode this fixture was
+ *     FIRST measured at, kept as a knob so a volume-only effect is not mistaken
+ *     for a time effect.
+ *   - DUMMY_FILES [10], DUMMY_TESTS_PER_FILE [30] — how the volume is distributed
+ *     across files, i.e. the shape of the run rather than its size.
+ *   - DUMMY_FAIL_FILE [5], DUMMY_FAIL_STEP [15] — the FAILURE POSITION. Where in
+ *     the run the planted failure lands, so a measurement can tell "the tool
+ *     survived a long run" apart from "the tool survived a long run up to the
+ *     failure".
+ *   - DUMMY_FAIL_FAST [0] — the cost of a failure. 0 lets the suite run to the
+ *     end after the failure (the default, and what a real test command does if it
+ *     does not stop early). 1 collapses the run after the planted failure: every
+ *     later test short-circuits with a single "skipped" line, so wall-clock ends
+ *     near the failure instead of at the end. That is the regime where the very
+ *     property a background job exploits — the run is long — disappears, so it is
+ *     where bgrun should NOT be expected to win.
+ *   - DUMMY_OUT_DIR [<system tmpdir>/pi-bgrun-dummy-suite] — where the suite is
+ *     written; outside the repo by default and guarded against the repo.
+ *
+ * All earlier measurements of this fixture used 8 lines per test. Anything quoted
+ * from those runs must say so, because the default density is now 2.
  */
 import {
   existsSync,
@@ -68,6 +101,16 @@ function canonical(path: string): string {
   return tail.length > 0 ? join(real, ...tail) : real;
 }
 
+// Text that lands inside the generated file's template literals survives one more
+// round of interpolation, so escape the two sequences the generated code would
+// otherwise re-evaluate (a backtick would end the literal; ${ would interpolate).
+function escapeForTemplate(text: string): string {
+  return text
+    .replace(/\\/g, "\\\\")
+    .replace(/`/g, "\\`")
+    .replace(/\$\{/g, "\\${");
+}
+
 const repoRoot = canonical(resolve(dirname(fileURLToPath(import.meta.url)), ".."));
 const outDir = resolve(
   process.env.DUMMY_OUT_DIR ?? join(tmpdir(), "pi-bgrun-dummy-suite"),
@@ -77,6 +120,8 @@ const files = Number(process.env.DUMMY_FILES ?? 10);
 const perFile = Number(process.env.DUMMY_TESTS_PER_FILE ?? 30);
 const failFile = Number(process.env.DUMMY_FAIL_FILE ?? 5);
 const failStep = Number(process.env.DUMMY_FAIL_STEP ?? 15);
+const linesPerTest = Number(process.env.DUMMY_LINES_PER_TEST ?? 2);
+const failFast = Number(process.env.DUMMY_FAIL_FAST ?? 0);
 
 for (const [name, value] of Object.entries({
   sleepMs,
@@ -84,12 +129,19 @@ for (const [name, value] of Object.entries({
   perFile,
   failFile,
   failStep,
+  linesPerTest,
 })) {
   if (!Number.isInteger(value) || value < 1) {
     console.error(`error: ${name} must be a positive integer (got ${value})`);
     process.exit(2);
   }
 }
+// Fail-fast is a boolean switch, not a count: anything other than 0/1 would be a
+// typo silently ignored by the generated `=== 1` test.
+if (failFast !== 0 && failFast !== 1) {
+  console.error(`error: DUMMY_FAIL_FAST must be 0 or 1 (got ${failFast})`);
+  process.exit(2);
+}
 // The planted failure IS the fixture: a run that passes while this script's report
 // claims it fails would quietly invalidate whatever used it.
 if (failFile > files || failStep > perFile) {
@@ -127,20 +179,74 @@ if (
 rmSync(outDir, { recursive: true, force: true });
 mkdirSync(outDir, { recursive: true });
 
+const total = files * perFile;
+
 for (let i = 1; i <= files; i++) {
   const n = String(i).padStart(2, "0");
   const failing = i === failFile;
-  writeFileSync(
-    join(outDir, `part-${n}.test.ts`),
-    `// Generated by scripts/make-dummy-suite.ts — do not edit; regenerate instead.
-import { test, describe } from "node:test";
+  const filePath = join(outDir, `part-${n}.test.ts`);
+  const failStepLabel = String(failStep).padStart(2, "0");
+
+  // A full assertion failure, not a one-liner: the fixture's failure should cost
+  // the lines a real one costs, so measurements of failing output are not flattered
+  // by a terse stub. The markers are exact strings other measurements grep for.
+  const failureBlock = escapeForTemplate(
+    [
+      "AssertionError [ERR_ASSERTION]: Expected values to be strictly deep-equal:",
+      "+ actual - expected",
+      "",
+      "  {",
+      '+   actual: "DIAGNOSTIC_MARKER_UPSTREAM",',
+      "+   got: 1",
+      '-   expected: "DIAGNOSTIC_MARKER_DOWNSTREAM",',
+      "-   got: 2",
+      "  }",
+      "",
+      `    at TestContext.<anonymous> (${filePath}:__FAIL_LINE__:9)`,
+      "    at Test.runInAsyncScope (node:async_hooks:206:9)",
+      "    at Test.run (node:internal/test_runner/test:773:25)",
+      "    at Test.start (node:internal/test_runner/test:672:17)",
+      "    at node:internal/test_runner/test:1175:29",
+      "    at processTicksAndRejections (node:internal/process/task_queues:95:5)",
+      "",
+      `load part ${n} > step ${failStepLabel}`,
+      "  the two diagnostic markers must match; they did not, so the load run stops here.",
+    ].join("\n"),
+  );
+
+  // The counters come from the run, not from arithmetic over the knobs: the runner
+  // picks its own file order, so only the generated code knows how many tests ran
+  // before the failure and how many short-circuited. Deliberately NOT escaped — the
+  // `${...}` here must stay live so the generated file interpolates them at runtime.
+  const summaryBlock = [
+    "──────────────────────────────────────────────",
+    `load run summary: ${files} files, ${total} tests`,
+    "  pass  ${g.__passed ?? 0}",
+    "  fail  ${g.__failed === true ? 1 : 0}",
+    "  skip  ${g.__skipped ?? 0}",
+    `the planted failure is part ${String(failFile).padStart(2, "0")} step ${failStepLabel}; its markers are the comparison pair`,
+    "──────────────────────────────────────────────",
+  ].join("\n");
+
+  let content = `// Generated by scripts/make-dummy-suite.ts — do not edit; regenerate instead.
+import { test, describe, before } from "node:test";
 import assert from "node:assert/strict";
 
 // Fixture purpose: this suite exists to occupy real wall-clock time and produce
 // real output volume. The delay IS the thing under measurement, so a fake timer
 // cannot stand in for it — hence a genuine setTimeout. It is generated outside
 // the repo so it never runs in CI or in a bare \`bun test\`.
-const g = globalThis as unknown as { __chain?: Promise<void> };
+//
+// ONE CHAIN, SHARED VIA globalThis: every test awaits this promise, so the run's
+// wall-clock is sleeps x tests however the runner schedules them. Without it a
+// concurrent scheduler would overlap the delays and collapse the measurement.
+const g = globalThis as unknown as {
+  __chain?: Promise<void>;
+  __failed?: boolean;
+  __done?: number;
+  __passed?: number;
+  __skipped?: number;
+};
 function step(): Promise<void> {
   const hold = new Promise<void>((resolve) => setTimeout(resolve, ${sleepMs}));
   g.__chain = (g.__chain ?? Promise.resolve()).then(() => hold);
@@ -148,36 +254,73 @@ function step(): Promise<void> {
 }
 
 describe("load part ${n}", () => {
+  before(() => {
+    console.log(\`=== part-${n}.test.ts (file ${i} of ${files}) ===\`);
+  });
   for (let k = 1; k <= ${perFile}; k++) {
     const which = k;
     test(\`step \${String(which).padStart(2, "0")}\`, async () => {
-      for (let line = 1; line <= 8; line++) {
-        console.log(\`[part ${n} step \${which}] stage \${line}/8 — building, linking, checking\`);
-      }
+      try {
+${
+  failFast === 1
+    ? `        if (g.__failed === true) {
+          g.__skipped = (g.__skipped ?? 0) + 1;
+          console.log(\`[part ${n} step \${which}] skipped — the run already failed\`);
+          return;
+        }
+`
+    : ""
+}        for (let line = 1; line <= ${linesPerTest}; line++) {
+          console.log(\`[part ${n} step \${which}] stage \${line}/${linesPerTest} — building, linking, checking\`);
+        }
 ${
   failing
-    ? `      if (which === ${failStep}) {
-        assert.deepEqual(
-          { actual: "DIAGNOSTIC_MARKER_UPSTREAM", got: 1 },
-          { expected: "DIAGNOSTIC_MARKER_DOWNSTREAM", got: 2 },
-        );
-      }
+    ? `        if (which === ${failStep}) {
+          g.__failed = true;
+          console.error(\`${failureBlock}\`);
+          assert.deepEqual(
+            { actual: "DIAGNOSTIC_MARKER_UPSTREAM", got: 1 },
+            { expected: "DIAGNOSTIC_MARKER_DOWNSTREAM", got: 2 },
+          );
+        }
 `
     : ""
-}      await step();
+}        await step();
+        g.__passed = (g.__passed ?? 0) + 1;
+      } finally {
+        // The counter, not the runner, places the summary: whichever test runs
+        // last prints it, so the block lands at the end of the fixture's output
+        // however the runner orders the files.
+        g.__done = (g.__done ?? 0) + 1;
+        if (g.__done === ${total}) {
+          console.log(\`${summaryBlock}\`);
+        }
+      }
     });
   }
 });
-`,
-  );
+`;
+
+  if (failing) {
+    // The stack trace must name the line the assertion actually sits on; we only
+    // know that once the whole file is assembled, so substitute the placeholder.
+    const failLine =
+      content.split("\n").findIndex((line) => line.includes("assert.deepEqual")) + 1;
+    content = content.replace("__FAIL_LINE__", String(failLine));
+  }
+
+  writeFileSync(filePath, content);
 }
 
-const total = files * perFile;
 console.log(
   `generated ${files} files in ${outDir}\n` +
     `  tests:    ${total} (${files} files x ${perFile})\n` +
+    `  density:  ${linesPerTest} log lines/test${
+      linesPerTest === 8 ? " (the original fixture density)" : ""
+    }\n` +
     `  runtime:  ~${((sleepMs * total) / 1000).toFixed(0)}s (${sleepMs}ms x ${total})\n` +
-    `  output:   ~${total * 9} log lines, plus the summary\n` +
-    `  failing:  part ${String(failFile).padStart(2, "0")} step ${failStep}, exit 1\n` +
+    `  output:   ~${total * linesPerTest} log lines, plus per-file banners and the summary\n` +
+    `  failing:  part ${String(failFile).padStart(2, "0")} step ${failStep}, exit 1` +
+    `${failFast === 1 ? " (fail-fast: the run stops there)" : ""}\n` +
     `  run it:   bun test ${outDir}`,
 );
diff --git a/scripts/measure-sessions.test.ts b/scripts/measure-sessions.test.ts
new file mode 100755
index 0000000..6bc18b4
--- /dev/null
+++ b/scripts/measure-sessions.test.ts
@@ -0,0 +1,268 @@
+#!/usr/bin/env bun
+/**
+ * Tests for scripts/measure-sessions.ts.
+ *
+ * The transcripts here are SYNTHETIC and written to a temp dir, not checked in:
+ * what needs proving is the metric contract (how a wait becomes blockedSeconds,
+ * what counts as an execution, how an arm is inferred), and a fixture that pins
+ * that is far smaller than a real session — and cannot silently rot when the
+ * agent's wording changes. The real-session numbers are re-derived by running the
+ * CLI against captured transcripts, which is the tool's whole point.
+ *
+ * node:test rather than bun:test, matching extension/index.test.ts: these run
+ * under both runners with @types/node alone.
+ */
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { after, test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  DOWNSTREAM_MARKER,
+  UPSTREAM_MARKER,
+  expandTarget,
+  formatReport,
+  measureSession,
+  resolveTargets,
+  summarize,
+  toCsv,
+} from "./measure-sessions.ts";
+
+const root = mkdtempSync(join(tmpdir(), "measure-sessions-test-"));
+after(() => rmSync(root, { recursive: true, force: true }));
+
+type Entry = Record<string, unknown>;
+
+function at(seconds: number): string {
+  return new Date(Date.UTC(2026, 0, 1, 0, 0, seconds)).toISOString();
+}
+
+function assistant(second: number, parts: Entry[]): Entry {
+  return {
+    type: "message",
+    timestamp: at(second),
+    message: { role: "assistant", content: parts },
+  };
+}
+
+function toolCall(id: string, name: string, command: string): Entry {
+  return { type: "toolCall", id, name, arguments: { command } };
+}
+
+function toolResult(second: number, id: string, text: string): Entry {
+  return {
+    type: "message",
+    timestamp: at(second),
+    message: {
+      role: "toolResult",
+      toolCallId: id,
+      content: [{ type: "text", text }],
+    },
+  };
+}
+
+/** Write a session directory holding one transcript; return the directory. */
+function session(name: string, entries: Entry[], junkLines: string[] = []): string {
+  const dir = join(root, name);
+  mkdirSync(dir, { recursive: true });
+  const lines = [...entries.map((entry) => JSON.stringify(entry)), ...junkLines];
+  writeFileSync(join(dir, `${name}.jsonl`), `${lines.join("\n")}\n`);
+  return dir;
+}
+
+test("blocking foreground run: the suite wait is blocked, the rest is idle", () => {
+  const dir = session("blocking", [
+    assistant(0, [toolCall("c1", "bash", "bun test extension/index.test.ts")]),
+    toolResult(20, "c1", "229 pass"),
+    assistant(30, [{ type: "text", text: "all green" }]),
+  ]);
+
+  const measured = measureSession("blocking", dir);
+  assert.equal(measured.arm, "vanilla");
+  assert.equal(measured.wallSeconds, 30);
+  assert.equal(measured.executions, 1);
+  assert.equal(measured.foregroundExecutions, 1);
+  assert.equal(measured.handoffs, 0);
+  assert.equal(measured.blockedSeconds, 20);
+  assert.equal(measured.idleSeconds, 10);
+  assert.equal(measured.toolCalls, 1);
+  assert.equal(measured.calls[0].waitSeconds, 20);
+  assert.equal(measured.calls[0].resultChars, 8);
+});
+
+test("several calls: every call is measured, only suite runs count as executions", () => {
+  const dir = session("several", [
+    assistant(0, [toolCall("c1", "bash", "bun test a")]),
+    toolResult(5, "c1", "a"),
+    assistant(6, [toolCall("c2", "bash", "bun test b")]),
+    toolResult(12, "c2", "bb"),
+    assistant(13, [toolCall("c3", "bash", "ls")]),
+    toolResult(14, "c3", "ccc"),
+  ]);
+
+  const measured = measureSession("several", dir);
+  assert.equal(measured.toolCalls, 3);
+  assert.equal(measured.executions, 2);
+  assert.equal(measured.blockedSeconds, 11);
+  assert.deepEqual(measured.commands, ["bun test a", "bun test b", "ls"]);
+  assert.deepEqual(
+    measured.calls.map((call) => call.waitSeconds),
+    [5, 6, 1],
+  );
+  assert.deepEqual(
+    measured.calls.map((call) => call.resultChars),
+    [1, 2, 3],
+  );
+  // cum_ctx is a running total, so it must strictly grow.
+  assert.ok(
+    measured.calls[2].cumulativeContextChars >
+      measured.calls[0].cumulativeContextChars,
+  );
+});
+
+test("no suite execution: mentioning the fixture is not executing it", () => {
+  const dir = session("no-exec", [
+    assistant(0, [toolCall("c1", "bash", "cat long-job.sh")]),
+    toolResult(1, "c1", "#!/bin/sh"),
+  ]);
+
+  const measured = measureSession("no-exec", dir);
+  assert.equal(measured.executions, 0);
+  assert.equal(measured.foregroundExecutions, 0);
+  assert.equal(measured.blockedSeconds, 0);
+  assert.equal(measured.toolCalls, 1);
+  // The session still reports: zero executions is a measurement, not a skip.
+  assert.equal(measured.wallSeconds, 1);
+});
+
+test("no suite execution: a session with no tool calls reports zeros", () => {
+  const dir = session("silent", [assistant(0, [{ type: "text", text: "hello" }])]);
+  const measured = measureSession("silent", dir);
+  assert.equal(measured.toolCalls, 0);
+  assert.equal(measured.executions, 0);
+  assert.equal(measured.wallSeconds, 0);
+});
+
+test("bgrun detection: a handoff is an execution, not a block", () => {
+  const dir = session("bg", [
+    assistant(0, [toolCall("c1", "bgrun", "bun test extension/index.test.ts")]),
+    toolResult(0, "c1", "started: job-1"),
+    assistant(10, [toolCall("c2", "bgstatus", "job-1")]),
+    toolResult(10, "c2", "running"),
+  ]);
+
+  const measured = measureSession("bg", dir);
+  assert.equal(measured.arm, "bgrun");
+  assert.equal(measured.handoffs, 1);
+  assert.equal(measured.foregroundExecutions, 0);
+  assert.equal(measured.executions, 1);
+  // The handoff returned instantly, so nothing was blocked on suite output.
+  assert.equal(measured.blockedSeconds, 0);
+  assert.equal(measured.idleSeconds, measured.wallSeconds);
+});
+
+test("diagnostic reach reads the LAST assistant text, not tool results", () => {
+  const dir = session("fixture-red", [
+    assistant(0, [
+      toolCall("c1", "bash", "bun test extension/index.test.ts"),
+      { type: "text", text: `saw ${UPSTREAM_MARKER} earlier` },
+    ]),
+    toolResult(5, "c1", `log body mentions ${DOWNSTREAM_MARKER}`),
+    assistant(6, [{ type: "text", text: "done" }]),
+  ]);
+
+  const measured = measureSession("fixture-red", dir);
+  assert.equal(measured.diagnosticUpstream, false);
+  assert.equal(measured.diagnosticDownstream, false);
+
+  const reached = measureSession(
+    "fixture-red-2",
+    session("fixture-red-2", [
+      assistant(0, [toolCall("c1", "bash", "bun test")]),
+      toolResult(5, "c1", "log"),
+      assistant(6, [{ type: "text", text: UPSTREAM_MARKER }]),
+    ]),
+  );
+  assert.equal(reached.diagnosticUpstream, true);
+  assert.equal(reached.diagnosticDownstream, false);
+});
+
+test("tolerance: unknown entries, junk lines and unmatched results are skipped", () => {
+  const dir = session(
+    "ragged",
+    [
+      assistant(0, [toolCall("c1", "bash", "bun test")]),
+      { type: "session_info", timestamp: at(1) },
+      { type: "model_change", timestamp: at(2) },
+      {
+        type: "message",
+        timestamp: at(3),
+        message: { role: "toolResult", content: [] },
+      },
+      toolResult(4, "c1", "ok"),
+    ],
+    ["{ this is not json", ""],
+  );
+
+  const measured = measureSession("ragged", dir);
+  assert.equal(measured.executions, 1);
+  assert.equal(measured.toolCalls, 2);
+  // The unmatched (toolCallId-less) result pairs by arrival order, which is c1.
+  assert.equal(measured.calls[0].tool, "bash");
+  assert.equal(measured.calls[1].tool, "?");
+});
+
+const paired = (dirA: string, dirB: string) => {
+  const sessions = [measureSession("a", dirA), measureSession("b", dirB)];
+  return { sessions, summaries: summarize(sessions) };
+};
+
+const runDir = (name: string, waitSeconds: number): string =>
+  session(name, [
+    assistant(0, [toolCall("c1", "bash", "bun test")]),
+    toolResult(waitSeconds, "c1", "x"),
+  ]);
+
+test("a summary needs two sessions of one arm and keeps the spread", () => {
+  const { sessions, summaries } = paired(runDir("agg-a", 4), runDir("agg-b", 10));
+
+  assert.equal(summaries.length, 1);
+  assert.equal(summaries[0].arm, "vanilla");
+  assert.deepEqual(summaries[0].metrics.blocked_s, { median: 7, min: 4, max: 10 });
+
+  const report = formatReport(sessions, summaries, []);
+  assert.ok(report.includes("blocked_s"));
+  assert.ok(report.includes("7.0 [4.0–10.0]"));
+  // A single-session arm gets no median rather than a degenerate one.
+  assert.ok(formatReport(sessions, summarize([sessions[0]]), []).includes("1 session"));
+});
+
+test("--csv emits a row per session plus a summary row and quotes commas", () => {
+  const { sessions, summaries } = paired(runDir("csv-a", 4), runDir("csv-b", 10));
+  const rows = toCsv(sessions, summaries).split("\n");
+
+  assert.ok(rows[0].startsWith("row,label,arm,sessions,execs"));
+  assert.equal(rows.filter((row) => row.startsWith("session,")).length, 2);
+  assert.equal(rows.filter((row) => row.startsWith("summary,")).length, 1);
+  // Median and range both survive the CSV form.
+  assert.ok(rows[rows.length - 1].includes("7.0 [4.0-10.0]"));
+
+  const commaDir = session("csv-comma", [
+    assistant(0, [toolCall("c1", "bash", "bun test a,b")]),
+    toolResult(4, "c1", "x"),
+  ]);
+  const commaRow = toCsv([measureSession("csv-comma", commaDir)], []).split("\n")[1];
+  assert.ok(commaRow.includes('"bun test a,b"'));
+});
+
+test("target resolution expands globs and reports misses", () => {
+  const first = session("glob-a", [assistant(0, [{ type: "text", text: "x" }])]);
+  session("glob-b", [assistant(0, [{ type: "text", text: "y" }])]);
+
+  assert.deepEqual(expandTarget(join(root, "glob-*")), [first, join(root, "glob-b")]);
+
+  const { paths, missing } = resolveTargets([join(root, "glob-*"), "no-such-dir"]);
+  assert.equal(paths.length, 2);
+  assert.deepEqual(missing, ["no-such-dir"]);
+});
diff --git a/scripts/measure-sessions.ts b/scripts/measure-sessions.ts
new file mode 100755
index 0000000..4913c6f
--- /dev/null
+++ b/scripts/measure-sessions.ts
@@ -0,0 +1,739 @@
+#!/usr/bin/env bun
+/**
+ * measure-sessions.ts — re-derive the benchmark numbers from pi session transcripts.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * The numbers in docs/dogfooding.md were first produced by two throwaway Python
+ * profilers (`/tmp/arm_profile.py`, `/tmp/agg_arms.py`). Those scripts are gone the
+ * moment the machine is, and a benchmark whose source is unreproducible is not
+ * evidence — it is a claim. This is the committed port: one dependency-free CLI
+ * that turns a directory of `*.jsonl` transcripts into the same per-session and
+ * per-arm numbers, so anyone can re-run the comparison and check it.
+ *
+ * It is deliberately faithful where the accounting is meaningful and explicit
+ * where it changes:
+ *
+ *   wallSeconds      first → last `message` entry timestamp. The session's own
+ *                    clock; not wall time on the host, not the fixture's runtime.
+ *   executions       suite runs the session actually STARTED: a foreground `bash`
+ *                    call whose command *executes* the suite, plus every `bgrun`
+ *                    handoff. `cat long-job.sh` is not an execution — the command
+ *                    must invoke it. A bgrun handoff counts because the work did
+ *                    happen; it is reported separately (foregroundExecutions /
+ *                    handoffs) because the two arms wait for it differently.
+ *   blockedSeconds   sum of the waits on those foreground suite runs. This is the
+ *                    time the session could not proceed: the number the whole
+ *                    comparison is about.
+ *   idleSeconds      wallSeconds − blockedSeconds. Deliberately NOT the sum of
+ *                    sleep/wait calls: in a bgrun session the agent is not blocked
+ *                    on the suite but is still working (polling bgstatus, reading
+ *                    the log), and charging that as "idle" would flatter the tool.
+ *                    What is left over here is time neither spent blocked nor
+ *                    avoided, whatever the agent did with it.
+ *   agentSleepSeconds sum over calls whose command is a bare `sleep`/`wait`. The
+ *                    throwaway profilers called this "agent-chosen idle"; it is
+ *                    kept as its own column so this tool's numbers stay
+ *                    cross-checkable against theirs for sessions that use it.
+ *   contextChars     total characters of text/thinking the session accumulated
+ *                    across all `message` entries (assistant + tool results + the
+ *                    rest). What the model paid for, not what the terminal showed.
+ *   diagnosticReach  whether the LAST assistant text carries
+ *                    DIAGNOSTIC_MARKER_UPSTREAM / DIAGNOSTIC_MARKER_DOWNSTREAM.
+ *                    For the failing fixtures that is the only measure of whether
+ *                    the failure detail reached the model at all — a run can be
+ *                    fast because the agent never saw what broke.
+ *
+ * TOLERANCE
+ * ---------
+ * Transcripts are append-only and not every line is a `message` (session,
+ * session_info, model_change, …), and a crashed writer can leave a half-line.
+ * Anything that is not a parsable `message` is skipped, never fatal: a benchmark
+ * tool that dies on an unknown record would only ever measure clean runs.
+ *
+ * USAGE
+ * -----
+ *   bun scripts/measure-sessions.ts <dir-or-glob...> [--csv]
+ *
+ * A target is a session directory (its first `*.jsonl`, sorted, is the transcript),
+ * a transcript file, or a glob. Shells expand globs, but a quoted pattern still
+ * works here — expansion is built in so the invocation is reproducible either way.
+ * Output is one row per session, the per-call ledger, then a median+range summary
+ * per arm. Never a single aggregate: the spread IS the finding.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+/** "The run under test": an actual suite invocation, or the long-job script being
+ * executed. Kept textually identical to the throwaway profilers so the numbers
+ * refer to the same event. */
+export const SUITE_PATTERN =
+  /(?:\bbun test\b)|(?:(?:^|[;&|]\s*)(?:sh|bash|\.\/)\s*\S*long-job\.sh)/;
+
+/** A call the agent chose to spend time in rather than use. */
+export const IDLE_PATTERN = /^\s*(sleep|wait)\b/;
+
+export const UPSTREAM_MARKER = "DIAGNOSTIC_MARKER_UPSTREAM";
+export const DOWNSTREAM_MARKER = "DIAGNOSTIC_MARKER_DOWNSTREAM";
+
+export type Arm = "bgrun" | "vanilla";
+
+/** One tool call, paired with the result it produced. */
+export interface CallMeasurement {
+  /** Tool name exactly as the transcript records it (`bash`, `bgrun`, `read`, …). */
+  tool: string;
+  /** The command/id/path argument, verbatim — the "exact shell command invoked". */
+  command: string;
+  /** Seconds between the assistant's toolCall and its toolResult. */
+  waitSeconds: number;
+  /** Characters in the result's text/thinking parts. */
+  resultChars: number;
+  /** Running context total after this call — where it sits in the ledger. */
+  cumulativeContextChars: number;
+  /** True when the call shared an assistant message with an earlier toolCall, so the
+   * timestamp pairs the BATCH's result with it, not the call's own. */
+  batched: boolean;
+  /** True when this call actually started the suite (foreground or handoff). */
+  suiteExecution: boolean;
+}
+
+export interface SessionMeasurement {
+  /** Directory name of the session (or the transcript's parent directory). */
+  label: string;
+  /** Absolute path of the transcript the numbers came from. */
+  transcript: string;
+  /** Inferred from the transcript: `bgrun` if it made bgrun calls, else `vanilla`. */
+  arm: Arm;
+  wallSeconds: number;
+  /** Foreground suite runs + bgrun handoffs. */
+  executions: number;
+  foregroundExecutions: number;
+  handoffs: number;
+  blockedSeconds: number;
+  idleSeconds: number;
+  agentSleepSeconds: number;
+  contextChars: number;
+  toolCalls: number;
+  calls: CallMeasurement[];
+  /** Every command/id/path seen, in call order. */
+  commands: string[];
+  diagnosticUpstream: boolean;
+  diagnosticDownstream: boolean;
+}
+
+/** Text/thinking characters a `message` entry contributes to context. */
+function textLength(entry: Record<string, unknown>): number {
+  const message = entry.message as { content?: unknown } | undefined;
+  const content = message?.content;
+  if (!Array.isArray(content)) return 0;
+  let total = 0;
+  for (const part of content) {
+    if (typeof part !== "object" || part === null) continue;
+    const record = part as { text?: unknown; thinking?: unknown };
+    // `||`, not `??`: an empty `text` falls through to `thinking`, matching the
+    // original profilers exactly.
+    const text = record.text || record.thinking;
+    if (typeof text === "string") total += text.length;
+  }
+  return total;
+}
+
+/** Concatenated text of one message (thinking excluded), for marker scans. */
+function messageText(entry: Record<string, unknown>): string {
+  const message = entry.message as { content?: unknown } | undefined;
+  const content = message?.content;
+  if (!Array.isArray(content)) return "";
+  let out = "";
+  for (const part of content) {
+    if (typeof part !== "object" || part === null) continue;
+    const text = (part as { text?: unknown }).text;
+    if (typeof text === "string") out += text;
+  }
+  return out;
+}
+
+/** Epoch milliseconds, or null when the entry carries no usable timestamp. */
+function timestampOf(entry: Record<string, unknown>): number | null {
+  const raw = entry.timestamp;
+  if (typeof raw !== "string") return null;
+  const parsed = Date.parse(raw);
+  return Number.isNaN(parsed) ? null : parsed;
+}
+
+/**
+ * Read one transcript into the raw ledger. Tolerant by construction: non-JSON
+ * lines, non-`message` entries, and results with no matching call are all
+ * survivable — see the TOLERANCE note in the file header.
+ */
+function readTranscript(transcript: string): {
+  rows: Omit<CallMeasurement, "suiteExecution">[];
+  wallSeconds: number;
+  contextChars: number;
+  lastAssistantText: string;
+  sawBgrun: boolean;
+} {
+  const rows: Omit<CallMeasurement, "suiteExecution">[] = [];
+  const pending = new Map<
+    string,
+    { tool: string; command: string; at: number | null }
+  >();
+  const batched = new Set<string>();
+  let first: number | null = null;
+  let last: number | null = null;
+  let cumulative = 0;
+  let lastAssistantText = "";
+  let sawBgrun = false;
+
+  let text: string;
+  try {
+    text = readFileSync(transcript, "utf8");
+  } catch {
+    return { rows, wallSeconds: 0, contextChars: 0, lastAssistantText, sawBgrun };
+  }
+
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let entry: Record<string, unknown>;
+    try {
+      entry = JSON.parse(trimmed) as Record<string, unknown>;
+    } catch {
+      continue;
+    }
+    if (entry.type !== "message") continue;
+
+    const at = timestampOf(entry);
+    if (at !== null) {
+      if (first === null) first = at;
+      last = at;
+    }
+    const message = entry.message as
+      | { role?: unknown; content?: unknown; toolCallId?: unknown }
+      | undefined;
+    const role = message?.role;
+
+    if (role === "assistant") {
+      const ids: string[] = [];
+      for (const part of Array.isArray(message?.content) ? message.content : []) {
+        if (typeof part !== "object" || part === null) continue;
+        const call = part as {
+          type?: unknown;
+          id?: unknown;
+          name?: unknown;
+          arguments?: Record<string, unknown>;
+        };
+        if (call.type !== "toolCall") continue;
+        const args = call.arguments ?? {};
+        const command = String(args.command ?? args.id ?? args.path ?? "");
+        const tool = String(call.name ?? "?");
+        if (tool === "bgrun") sawBgrun = true;
+        const id = typeof call.id === "string" ? call.id : `${rows.length}:${ids.length}`;
+        ids.push(id);
+        pending.set(id, { tool, command, at });
+      }
+      // Everything after the first call in one assistant message resolves at the
+      // batch's summary timestamp, not its own — flagged so the wait is read right.
+      for (const id of ids.slice(1)) batched.add(id);
+      cumulative += textLength(entry);
+      const assistantText = messageText(entry);
+      if (assistantText) lastAssistantText = assistantText;
+      continue;
+    }
+
+    if (role === "toolResult") {
+      const resultChars = textLength(entry);
+      cumulative += resultChars;
+      const toolCallId = message?.toolCallId;
+      let matched = typeof toolCallId === "string" ? pending.get(toolCallId) : undefined;
+      let matchedId = typeof toolCallId === "string" ? toolCallId : "";
+      if (!matched && pending.size > 0) {
+        // Interactive transcripts may omit toolCallId; pair in arrival order,
+        // which is insertion order for a Map.
+        matchedId = pending.keys().next().value as string;
+        matched = pending.get(matchedId);
+      }
+      const tool = matched?.tool ?? "?";
+      const command = matched?.command ?? "(unmatched)";
+      const startedAt = matched?.at ?? null;
+      if (matchedId) pending.delete(matchedId);
+      rows.push({
+        tool,
+        command,
+        waitSeconds:
+          at !== null && startedAt !== null ? (at - startedAt) / 1000 : 0,
+        resultChars,
+        cumulativeContextChars: cumulative,
+        batched: batched.has(matchedId),
+      });
+      continue;
+    }
+
+    cumulative += textLength(entry);
+  }
+
+  return {
+    rows,
+    wallSeconds: first !== null && last !== null ? (last - first) / 1000 : 0,
+    contextChars: cumulative,
+    lastAssistantText,
+    sawBgrun,
+  };
+}
+
+/** Measure one session directory (or transcript file) under a given label. */
+export function measureSession(label: string, target: string): SessionMeasurement {
+  const transcript = transcriptIn(target);
+  if (transcript === null) {
+    // A caller-visible zero row: a session with no suite execution still has to
+    // report, so "nothing ran" is a measurement, not an omission.
+    return {
+      label,
+      transcript: target,
+      arm: "vanilla",
+      wallSeconds: 0,
+      executions: 0,
+      foregroundExecutions: 0,
+      handoffs: 0,
+      blockedSeconds: 0,
+      idleSeconds: 0,
+      agentSleepSeconds: 0,
+      contextChars: 0,
+      toolCalls: 0,
+      calls: [],
+      commands: [],
+      diagnosticUpstream: false,
+      diagnosticDownstream: false,
+    };
+  }
+  const raw = readTranscript(transcript);
+  const calls: CallMeasurement[] = raw.rows.map((row) => ({
+    ...row,
+    suiteExecution:
+      (row.tool === "bash" && SUITE_PATTERN.test(row.command)) ||
+      row.tool === "bgrun",
+  }));
+  const foreground = calls.filter((c) => c.tool === "bash" && c.suiteExecution);
+  const handoffs = calls.filter((c) => c.tool === "bgrun");
+  const blockedSeconds = foreground.reduce((sum, c) => sum + c.waitSeconds, 0);
+  const sleeps = calls.filter((c) => IDLE_PATTERN.test(c.command));
+  return {
+    label,
+    transcript,
+    arm: raw.sawBgrun ? "bgrun" : "vanilla",
+    wallSeconds: raw.wallSeconds,
+    executions: foreground.length + handoffs.length,
+    foregroundExecutions: foreground.length,
+    handoffs: handoffs.length,
+    blockedSeconds,
+    // Literal definition, not clamped: a negative difference would itself be a
+    // finding (a wait timestamped outside the span) and must not be hidden as 0.
+    idleSeconds: raw.wallSeconds - blockedSeconds,
+    agentSleepSeconds: sleeps.reduce((sum, c) => sum + c.waitSeconds, 0),
+    contextChars: raw.contextChars,
+    toolCalls: calls.length,
+    calls,
+    commands: calls.map((c) => c.command),
+    diagnosticUpstream: raw.lastAssistantText.includes(UPSTREAM_MARKER),
+    diagnosticDownstream: raw.lastAssistantText.includes(DOWNSTREAM_MARKER),
+  };
+}
+
+/** First sorted `*.jsonl` in a directory; the path itself for a file; null if neither. */
+function transcriptIn(target: string): string | null {
+  let stats;
+  try {
+    stats = statSync(target);
+  } catch {
+    return null;
+  }
+  if (stats.isFile()) return target;
+  if (!stats.isDirectory()) return null;
+  const files = readdirSync(target)
+    .filter((name) => name.endsWith(".jsonl"))
+    .sort();
+  return files.length > 0 ? join(target, files[0]) : null;
+}
+
+/** Directory that names the session, whichever form the target took. */
+function labelFor(target: string): string {
+  let stats;
+  try {
+    stats = statSync(target);
+  } catch {
+    return basename(target);
+  }
+  return basename(stats.isDirectory() ? target : dirname(target));
+}
+
+const GLOB_CHARS = /[*?[{]/;
+
+/** Translate one path segment of a glob into a matcher. */
+function segmentRegExp(segment: string): RegExp {
+  let out = "";
+  for (let i = 0; i < segment.length; i++) {
+    const ch = segment[i];
+    if (ch === "*") out += "[^/]*";
+    else if (ch === "?") out += "[^/]";
+    else if (ch === "[" ) {
+      const end = segment.indexOf("]", i + 1);
+      if (end === -1) out += "\\[";
+      else {
+        out += `[${segment.slice(i + 1, end).replace(/\\/g, "\\\\")}]`;
+        i = end;
+      }
+    } else out += ch.replace(/[.+^${}()|\\\]]/g, "\\$&");
+  }
+  return new RegExp(`^${out}$`);
+}
+
+/**
+ * Expand a target into existing paths. The shell usually does this, but a quoted
+ * pattern must still work — the benchmark has to be reproducible from the exact
+ * command line in the docs, whatever the reader's shell does with `*`.
+ */
+export function expandTarget(target: string): string[] {
+  if (!GLOB_CHARS.test(target)) return existsSync(target) ? [target] : [];
+  const absolute = target.startsWith("/");
+  let frontier = [absolute ? "/" : "."];
+  for (const segment of target.split("/")) {
+    if (segment === "" || segment === ".") continue;
+    if (!GLOB_CHARS.test(segment)) {
+      frontier = frontier
+        .map((base) => join(base, segment))
+        .filter((path) => existsSync(path));
+      continue;
+    }
+    const matcher = segmentRegExp(segment);
+    const hidden = segment.startsWith(".");
+    const next: string[] = [];
+    for (const base of frontier) {
+      let entries: string[];
+      try {
+        entries = readdirSync(base);
+      } catch {
+        continue;
+      }
+      for (const name of entries) {
+        // Shell globs skip dotfiles unless the pattern asks for them; mirror that
+        // so discovery does not silently widen.
+        if (name.startsWith(".") && !hidden) continue;
+        if (matcher.test(name)) next.push(join(base, name));
+      }
+    }
+    frontier = next;
+  }
+  return frontier.sort();
+}
+
+/** Expand every target, preserving argument order and dropping duplicates. */
+export function resolveTargets(
+  targets: string[],
+): { paths: string[]; missing: string[] } {
+  const paths: string[] = [];
+  const missing: string[] = [];
+  const seen = new Set<string>();
+  for (const target of targets) {
+    const expanded = expandTarget(target);
+    if (expanded.length === 0) {
+      missing.push(target);
+      continue;
+    }
+    for (const path of expanded) {
+      if (seen.has(path)) continue;
+      seen.add(path);
+      paths.push(path);
+    }
+  }
+  return { paths, missing };
+}
+
+function median(values: number[]): number {
+  const sorted = [...values].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 1
+    ? sorted[mid]
+    : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+
+export interface Summary {
+  arm: Arm;
+  sessions: number;
+  metrics: Record<string, { median: number; min: number; max: number }>;
+  /** Sessions whose last assistant text carried at least one diagnostic marker. */
+  diagnosticReach: number;
+}
+
+const SUMMARY_METRICS: Array<[string, (s: SessionMeasurement) => number]> = [
+  ["execs", (s) => s.executions],
+  ["wall_s", (s) => s.wallSeconds],
+  ["blocked_s", (s) => s.blockedSeconds],
+  ["idle_s", (s) => s.idleSeconds],
+  ["sleep_s", (s) => s.agentSleepSeconds],
+  ["ctx_chars", (s) => s.contextChars],
+];
+
+/** Median and range per arm — only where more than one session exists. */
+export function summarize(sessions: SessionMeasurement[]): Summary[] {
+  const arms: Arm[] = ["vanilla", "bgrun"];
+  const summaries: Summary[] = [];
+  for (const arm of arms) {
+    const group = sessions.filter((s) => s.arm === arm);
+    if (group.length < 2) continue;
+    const metrics: Summary["metrics"] = {};
+    for (const [key, pick] of SUMMARY_METRICS) {
+      const values = group.map(pick);
+      metrics[key] = {
+        median: median(values),
+        min: Math.min(...values),
+        max: Math.max(...values),
+      };
+    }
+    summaries.push({
+      arm,
+      sessions: group.length,
+      metrics,
+      diagnosticReach: group.filter((s) => s.diagnosticUpstream || s.diagnosticDownstream)
+        .length,
+    });
+  }
+  return summaries;
+}
+
+function seconds(value: number): string {
+  return value.toFixed(1);
+}
+
+function chars(value: number): string {
+  return Math.round(value).toLocaleString("en-US");
+}
+
+function diagnosticLabel(session: SessionMeasurement): string {
+  const marks: string[] = [];
+  if (session.diagnosticUpstream) marks.push("up");
+  if (session.diagnosticDownstream) marks.push("down");
+  return marks.length > 0 ? marks.join("+") : "none";
+}
+
+const TABLE_COLUMNS: Array<[string, (s: SessionMeasurement) => string, number]> = [
+  ["label", (s) => s.label, 22],
+  ["arm", (s) => s.arm, 7],
+  ["execs", (s) => String(s.executions), 5],
+  ["fg", (s) => String(s.foregroundExecutions), 3],
+  ["handoff", (s) => String(s.handoffs), 7],
+  ["wall_s", (s) => seconds(s.wallSeconds), 7],
+  ["blocked_s", (s) => seconds(s.blockedSeconds), 9],
+  ["idle_s", (s) => seconds(s.idleSeconds), 7],
+  ["sleep_s", (s) => seconds(s.agentSleepSeconds), 7],
+  ["ctx_chars", (s) => chars(s.contextChars), 9],
+  ["diag", (s) => diagnosticLabel(s), 8],
+  ["calls", (s) => String(s.toolCalls), 5],
+];
+
+function pad(value: string, width: number): string {
+  return value.length >= width ? value + " " : value.padEnd(width);
+}
+
+/** Human-readable report: session rows, the per-call ledger, then arm summaries. */
+export function formatReport(
+  sessions: SessionMeasurement[],
+  summaries: Summary[],
+  missing: string[],
+): string {
+  const lines: string[] = [];
+  lines.push(
+    TABLE_COLUMNS.map(([header, , width]) => pad(header, width)).join("").trimEnd(),
+  );
+  for (const session of sessions) {
+    lines.push(
+      TABLE_COLUMNS.map(([, render, width]) => pad(render(session), width))
+        .join("")
+        .trimEnd(),
+    );
+  }
+
+  for (const session of sessions) {
+    lines.push("");
+    lines.push(`${session.label}  ${session.transcript}`);
+    if (session.calls.length === 0) {
+      lines.push("  (no tool calls)");
+      continue;
+    }
+    lines.push(
+      `  ${pad("#", 3)}${pad("tool", 10)}${pad("wait_s", 8)}${pad("result", 8)}${pad(
+        "cum_ctx",
+        10,
+      )}command`,
+    );
+    session.calls.forEach((call, index) => {
+      const command = call.command.replace(/\s+/g, " ").trim();
+      lines.push(
+        `  ${pad(String(index + 1), 3)}${pad(call.tool, 10)}${pad(
+          seconds(call.waitSeconds),
+          8,
+        )}${pad(String(call.resultChars), 8)}${pad(
+          chars(call.cumulativeContextChars),
+          10,
+        )}${command}${call.batched ? " [batched]" : ""}`,
+      );
+    });
+  }
+
+  lines.push("");
+  lines.push("summary (median [min–max]; arms with a single session have no median)");
+  for (const arm of ["vanilla", "bgrun"] as Arm[]) {
+    const count = sessions.filter((s) => s.arm === arm).length;
+    if (count === 0) continue;
+    const summary = summaries.find((s) => s.arm === arm);
+    if (!summary) {
+      lines.push(`  ${arm} (1 session — median/range need ≥2)`);
+      continue;
+    }
+    lines.push(`  ${summary.arm} (${summary.sessions} sessions)`);
+    for (const [key] of SUMMARY_METRICS) {
+      const m = summary.metrics[key];
+      const value =
+        key === "ctx_chars"
+          ? `${chars(m.median)} [${chars(m.min)}–${chars(m.max)}]`
+          : `${seconds(m.median)} [${seconds(m.min)}–${seconds(m.max)}]`;
+      lines.push(`    ${pad(key, 11)}${value}`);
+    }
+    lines.push(
+      `    ${pad("diag_reach", 11)}${summary.diagnosticReach}/${summary.sessions}`,
+    );
+  }
+
+  if (missing.length > 0) {
+    lines.push("");
+    lines.push(`no match: ${missing.join(", ")}`);
+  }
+  return lines.join("\n");
+}
+
+function csvCell(value: string): string {
+  return /[",\n]/.test(value) ? `"${value.replace(/"/g, '""')}"` : value;
+}
+
+const CSV_COLUMNS = [
+  "row",
+  "label",
+  "arm",
+  "sessions",
+  "execs",
+  "foreground_execs",
+  "handoffs",
+  "wall_s",
+  "blocked_s",
+  "idle_s",
+  "sleep_s",
+  "ctx_chars",
+  "tool_calls",
+  "diag",
+  "commands",
+  "calls",
+] as const;
+
+/** Machine-readable table. Summary rows carry `median [min–max]` per metric cell. */
+export function toCsv(
+  sessions: SessionMeasurement[],
+  summaries: Summary[],
+): string {
+  const lines: string[] = [CSV_COLUMNS.join(",")];
+  for (const session of sessions) {
+    lines.push(
+      [
+        "session",
+        session.label,
+        session.arm,
+        "",
+        String(session.executions),
+        String(session.foregroundExecutions),
+        String(session.handoffs),
+        seconds(session.wallSeconds),
+        seconds(session.blockedSeconds),
+        seconds(session.idleSeconds),
+        seconds(session.agentSleepSeconds),
+        String(Math.round(session.contextChars)),
+        String(session.toolCalls),
+        diagnosticLabel(session),
+        session.commands.join(" ; "),
+        session.calls
+          .map((c) => `${c.tool}@${seconds(c.waitSeconds)}s/${c.resultChars}`)
+          .join(" ; "),
+      ]
+        .map(csvCell)
+        .join(","),
+    );
+  }
+  for (const summary of summaries) {
+    const range = (key: string): string => {
+      const m = summary.metrics[key];
+      const format = key === "ctx_chars" ? chars : seconds;
+      return `${format(m.median)} [${format(m.min)}-${format(m.max)}]`;
+    };
+    lines.push(
+      [
+        "summary",
+        `median [min-max] ${summary.arm} (n=${summary.sessions})`,
+        summary.arm,
+        String(summary.sessions),
+        range("execs"),
+        "",
+        "",
+        range("wall_s"),
+        range("blocked_s"),
+        range("idle_s"),
+        range("sleep_s"),
+        range("ctx_chars"),
+        "",
+        `${summary.diagnosticReach}/${summary.sessions}`,
+        "",
+        "",
+      ]
+        .map(csvCell)
+        .join(","),
+    );
+  }
+  return lines.join("\n");
+}
+
+function main(argv: string[]): number {
+  const targets: string[] = [];
+  let csv = false;
+  for (const arg of argv) {
+    if (arg === "--csv") csv = true;
+    else if (arg === "--help" || arg === "-h") {
+      console.log("usage: bun scripts/measure-sessions.ts <dir-or-glob...> [--csv]");
+      return 0;
+    } else if (arg.startsWith("--")) {
+      console.error(`unknown flag: ${arg}`);
+      return 2;
+    } else targets.push(arg);
+  }
+  if (targets.length === 0) {
+    console.error("usage: bun scripts/measure-sessions.ts <dir-or-glob...> [--csv]");
+    return 2;
+  }
+
+  const { paths, missing } = resolveTargets(targets);
+  const sessions: SessionMeasurement[] = [];
+  for (const path of paths) {
+    const session = measureSession(labelFor(path), path);
+    if (session.calls.length === 0 && !existsSync(session.transcript)) {
+      // A directory with no transcript is not a session; say so rather than
+      // reporting a fake zero row.
+      console.error(`no transcript in ${path}`);
+      continue;
+    }
+    sessions.push(session);
+  }
+  const summaries = summarize(sessions);
+  if (csv) console.log(toCsv(sessions, summaries));
+  else console.log(formatReport(sessions, summaries, missing));
+  return 0;
+}
+
+// Guarded so tests can import the measurement functions without running the CLI.
+if ((import.meta as { main?: boolean }).main) {
+  process.exitCode = main(process.argv.slice(2));
+}