From 0f390d5ed9fc248fbab00c083853d4923e7bb299 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 6 Sep 2026 18:37:12 -0400
Subject: [PATCH 1/2] =?UTF-8?q?feat(readers):=20open=20.jsonl.gz=20+=20beh?=
 =?UTF-8?q?avior=5Fv2=20run=20logs=20everywhere=20=E2=80=94=20shared=20js/?=
 =?UTF-8?q?runlog-format.js=20(PR=203=20of=20runlog-behavior-v2-plan)=20?=
 =?UTF-8?q?=E2=80=94=20Studio=20v0.73?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reader side of docs/development/runlog-behavior-v2-plan.md (Part 3). Stacks on
the Studio PR (v0.72). With this, everything that opens a run-log FILE inflates
gzip on the magic bytes and expands behavior_v2's compact arena echoes back to
the v1 `arena_command` object at parse time, so every existing consumer
(p3LedEpochs, stall forensics, replay frame decoding) is unchanged.

- js/runlog-format.js (new; classic dual-export, vendored byte-identical at
  dashboard/data-browser/vendor/): isGzip, isRunlogName, stripGz, inflateIfGzip,
  readRunlogText (string|bytes|ArrayBuffer|Blob → text), readRunlogPrefixText
  (truncation-tolerant gunzip for the catalog's 64 KB metadata reads),
  isArenaArray, expandV2Line (exact v1 key order; timeout ⇒ status/echo/ok all
  null), compactV1Line, detectFormat, createNormalizer() (per-file state
  machine), convertV1ToV2Text / convertV2ToV1Text (JS mirror of the bridge
  converter, for tests + parity).
- Dashboard: analysis-core.js parseJsonl normalizes every line, run.logFormat +
  run.rawBytes, parseFilename strips .gz; github-repo.js fetchRaw reads bytes and
  inflates (prefix mode inflates a truncated gz); app.js loaders (repo / URL /
  local server / dropped file) go through readRunlogText, catalog filters accept
  .jsonl.gz, new size column (compressed size; inflated size + format in the
  hover), ?v= cache busters bumped, file input accepts .gz.
- Replay: js/runlog-replay.js parseRunLog normalizes records (loads
  js/runlog-format.js first in arena_studio.html; degrades to "v2 echoes
  skipped" + console warning under a stale cache); js/arena-studio-alt.js replay
  picker lists .jsonl.gz and inflates the picked file. arena_replay_viewer.html
  (protocol-fed) and js/studio-runlog-adapter.js (no file reads) unchanged.
- Tests: tests/test-runlog-format.js (new, 86 checks, in pixi run test — also
  enforces the vendored copy); tests/test-runlog-replay.js v2 case identical to
  the equivalent v1 (76 checks); dashboard test-analysis.js re-reads the P3
  fixture as v2 + gz asserting identical frames, arena_command objects,
  preference indices, LED epochs and page CSV rows, plus metadata from a gz
  prefix; dashboard/data-browser/tests/corpus-v2-parity.js runs the same over a
  whole clone (164/164 on cshl-2026-course origin/main).
- Browser-verified: the dashboard opens a converted .jsonl.gz via ?data= (52,369
  frames / 29 steps, size column "1.6 MB gz", no console errors).
- Docs: dashboard README, release notes v0.73, plan doc status + PR 3 notes,
  CLAUDE.md reader rule.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 CLAUDE.md                                     |   7 +-
 arena_studio.html                             |   5 +-
 dashboard/data-browser/README.md              |  23 +-
 dashboard/data-browser/analysis-core.js       |  20 +-
 dashboard/data-browser/app.js                 |  81 ++-
 dashboard/data-browser/github-repo.js         |  47 +-
 dashboard/data-browser/index.html             |   9 +-
 dashboard/data-browser/styles.css             |   6 +
 .../data-browser/tests/corpus-v2-parity.js    | 178 +++++++
 dashboard/data-browser/tests/test-analysis.js |  85 ++++
 .../data-browser/vendor/runlog-format.js      | 481 ++++++++++++++++++
 .../development/arena-studio-release-notes.md |   9 +
 docs/development/runlog-behavior-v2-plan.md   |  43 +-
 js/arena-studio-alt.js                        |  14 +-
 js/runlog-format.js                           | 481 ++++++++++++++++++
 js/runlog-replay.js                           |  27 +-
 pixi.toml                                     |   2 +-
 tests/test-runlog-format.js                   | 466 +++++++++++++++++
 tests/test-runlog-replay.js                   |  98 ++++
 19 files changed, 2025 insertions(+), 57 deletions(-)
 create mode 100644 dashboard/data-browser/tests/corpus-v2-parity.js
 create mode 100644 dashboard/data-browser/vendor/runlog-format.js
 create mode 100644 js/runlog-format.js
 create mode 100644 tests/test-runlog-format.js

diff --git a/CLAUDE.md b/CLAUDE.md
index 2614fb4..db626f2 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -296,8 +296,11 @@ fix flows to every page automatically; two hand-written HTML pages never will.
   `commitRunLog` gzips the bridge export (`GH.gzipBytes`) and commits
   `runlogs/<bench>/<name>.jsonl.gz` via `GH.commitFile`, which routes >30 MiB payloads
   through the Git Database API (`GH.directCommitLarge`) because the Contents API
-  rejects ~35 MiB+ files. Every reader (dashboard, replay viewer, adapter) must inflate
-  on the gzip magic and accept both `behavior_v1` and `behavior_v2` line formats. The
+  rejects ~35 MiB+ files. Every reader must go through **`js/runlog-format.js`**
+  (`readRunlogText` to inflate on the gzip magic, `createNormalizer().normalize(rec)` per
+  parsed line so `behavior_v2` `["a",…]` echoes become the v1 `arena_command` object) —
+  the dashboard uses an exact vendored copy at `dashboard/data-browser/vendor/`, and
+  `tests/test-runlog-format.js` fails when the copies diverge (re-copy after editing). The
   log level is a runtime setting (File ▾ → Run logging, localStorage `studio_log_level`,
   default `behavior_v2`); the runner asserts it via `log_control` and the bridge ACKS
   the level it will actually write (`bridge.waitForLogLevelAck`) — a pre-3.0 bridge
diff --git a/arena_studio.html b/arena_studio.html
index a5928ab..0f23f4c 100644
--- a/arena_studio.html
+++ b/arena_studio.html
@@ -2918,7 +2918,7 @@ <h2 id="modalTitle">Import error</h2>
 </div>
 
 <footer id="footer">
-  <span class="foot-left">Arena Studio v0.72 | 2026-09-06 17:54 ET · <a href="https://github.com/reiserlab/webDisplayTools" target="_blank" rel="noopener" title="webDisplayTools on GitHub: source, issues, and release notes (docs/development/arena-studio-release-notes.md)">GitHub</a></span>
+  <span class="foot-left">Arena Studio v0.73 | 2026-09-06 18:29 ET · <a href="https://github.com/reiserlab/webDisplayTools" target="_blank" rel="noopener" title="webDisplayTools on GitHub: source, issues, and release notes (docs/development/arena-studio-release-notes.md)">GitHub</a></span>
   <!-- Course-repo quick-links: open protocols / logs / patterns in a new tab.
        Hrefs built from the configured repo + bench id (updateGhQuickLinks). -->
   <span id="ghQuickLinks" title="Open the course repo on GitHub (new tab)">
@@ -2950,7 +2950,8 @@ <h2 id="modalTitle">Import error</h2>
 <script src="js/studio-runlog-adapter.js"></script>
 <script src="js/kinematics.js"></script> <!-- shared scope/dashboard kinematic derivations -->
 <script src="js/studio-github.js"></script>
-<script src="js/runlog-replay.js?v=20260712-stackfix"></script>
+<script src="js/runlog-format.js?v=20260906-1829"></script>
+<script src="js/runlog-replay.js?v=20260906-1829"></script>
 <script src="js/runtime-controls.js"></script>
 <script src="js/arena-replay-viewer-protocol.js"></script>
 
diff --git a/dashboard/data-browser/README.md b/dashboard/data-browser/README.md
index 81de483..4401091 100644
--- a/dashboard/data-browser/README.md
+++ b/dashboard/data-browser/README.md
@@ -197,6 +197,11 @@ value still pre-fills the local-server path.
 - `plot-specs.js`: protocol adapters and Plotly figure/CSV specifications
 - `github-repo.js`: PAT storage and private GitHub Contents API reads
 - `vendor/kinematics.js`: unchanged shared Arena Studio FicTrac math
+- `vendor/runlog-format.js`: exact copy of `webDisplayTools/js/runlog-format.js` — run-log
+  FILE decoding shared with the Studio's replay: gzip (`.jsonl.gz`, Studio v0.72+) and the
+  `behavior_v2` compact arena echoes, expanded to the v1 `arena_command` object at parse
+  time so every metric sees one shape. `tests/test-runlog-format.js` (repo root) fails if
+  the two copies diverge.
 
 ## Validation
 
@@ -209,6 +214,18 @@ node dashboard/data-browser/tests/test-github-client.js
 
 The analysis test parses live p0, p1, p2, current P3, and legacy P3 fixtures;
 validates stimulus alignment, P2 occupancy, P3 phase normalization, logged LED
-settings, and skipped-frame QC; builds every protocol page; and checks two-fly
-aggregation. The GitHub test verifies that the token appears only in the
-Authorization header.
+settings, and skipped-frame QC; builds every protocol page; checks two-fly
+aggregation; and re-reads the P3 fixture as `behavior_v2` + gzip asserting identical
+frames, events, preference indices and page CSV rows. The GitHub test verifies that
+the token appears only in the Authorization header.
+
+```bash
+node dashboard/data-browser/tests/corpus-v2-parity.js [/path/to/cshl-2026-course]
+```
+
+runs that v1-vs-v2.gz comparison over EVERY log in a course-repo clone (the
+behavior_v2 corpus gate; prints a Markdown table).
+
+Both `.jsonl` and `.jsonl.gz` open from the repo, a local server, a URL or a dropped
+file; the catalog shows the committed (compressed) size, with the inflated size and
+line format in the hover once a run is loaded.
diff --git a/dashboard/data-browser/analysis-core.js b/dashboard/data-browser/analysis-core.js
index 63bb6d6..48bae80 100644
--- a/dashboard/data-browser/analysis-core.js
+++ b/dashboard/data-browser/analysis-core.js
@@ -4,6 +4,14 @@
     const K =
         global.Kinematics ||
         (typeof require === 'function' ? require('./vendor/kinematics.js') : null);
+    // Run-log FILE format (gzip + behavior_v1/v2 line formats): the shared
+    // js/runlog-format.js, vendored byte-identical like kinematics. parseJsonl
+    // takes TEXT — loaders inflate with F.readRunlogText first — and normalizes
+    // every line through F.createNormalizer() so behavior_v2's compact arena
+    // echoes reach every consumer as the v1 `arena_command` object.
+    const F =
+        global.RunlogFormat ||
+        (typeof require === 'function' ? require('./vendor/runlog-format.js') : null);
     const DEFAULT_BALL_DIAMETER_MM = 9;
     const DEFAULT_SMOOTH_WINDOW_S = 0.5;
     const ANALOG_OFF_FLOOR_MV = 4900;
@@ -175,7 +183,8 @@
 
     function parseFilename(sourceName) {
         const fileName = safeText(sourceName).split('/').pop() || 'runlog.jsonl';
-        const stem = fileName.replace(/\.jsonl$/i, '');
+        // `.jsonl.gz` (Studio v0.72+) and `.jsonl` share the same stem grammar.
+        const stem = fileName.replace(/\.gz$/i, '').replace(/\.jsonl$/i, '');
         const fields = stem.split('__');
         return {
             fileName,
@@ -719,6 +728,7 @@
         let schema = [];
         let metadata = {};
         let sessionStartMs = NaN;
+        const normalizer = F ? F.createNormalizer() : null;
 
         for (let index = 0; index < lines.length; index += 1) {
             const line = lines[index].trim();
@@ -726,6 +736,9 @@
             let rec;
             try {
                 rec = JSON.parse(line);
+                // behavior_v2: ["a", …] arena echoes → the v1 arena_command object
+                // (needs the v2 frame_schema's t0, which precedes them in the file).
+                if (normalizer) rec = normalizer.normalize(rec);
             } catch (error) {
                 parseErrors.push({ lineNumber: index + 1, message: error.message });
                 continue;
@@ -763,7 +776,10 @@
             events,
             steps,
             parseErrors,
-            sessionStartMs
+            sessionStartMs,
+            // 'behavior_v2' | 'behavior_v1' | 'full' | 'legacy' | 'unknown'
+            logFormat: normalizer ? normalizer.format : 'unknown',
+            rawBytes: text ? text.length : 0
         };
         deriveSignals(run, options);
         assignFramesToSteps(run);
diff --git a/dashboard/data-browser/app.js b/dashboard/data-browser/app.js
index 460aa2e..97823d6 100644
--- a/dashboard/data-browser/app.js
+++ b/dashboard/data-browser/app.js
@@ -1,6 +1,7 @@
 'use strict';
 
 const A = window.DashboardAnalysis;
+const F = window.RunlogFormat; // run-log file format: gzip + behavior_v1/v2 (vendor/runlog-format.js)
 const P = window.DashboardPlots;
 const G = window.DashboardGitHub;
 const ANALYSIS_AXES_KEY = 'dashboard_analysis_axes';
@@ -501,7 +502,7 @@ const CATALOG_COLUMNS = [
         narrowHide: true,
         defaultHidden: true,
         cell: (d) =>
-            `<span class="run-size">${Number.isFinite(d.size) ? (d.size / 1048576).toFixed(1) + ' MB' : ''}</span>`,
+            `<span class="run-size" title="${escapeHtml(sizeTitle(d))}">${escapeHtml(sizeLabel(d))}</span>`,
         sort: (d) => d.size || 0
     }
 ];
@@ -631,6 +632,28 @@ function renderCatalog() {
     renderFocusOptions();
 }
 
+// Catalog size column: the committed size (gzip for `.jsonl.gz`); the hover adds
+// the inflated size once the run has been loaded.
+function formatBytes(n) {
+    if (!Number.isFinite(n) || n <= 0) return '';
+    return n >= 1e6 ? `${(n / 1e6).toFixed(1)} MB` : `${Math.max(1, Math.round(n / 1e3))} KB`;
+}
+function sizeLabel(descriptor) {
+    const label = formatBytes(descriptor.size);
+    if (!label) return '';
+    return /\.gz$/i.test(descriptor.path || descriptor.sourceName || '') ? `${label} gz` : label;
+}
+function sizeTitle(descriptor) {
+    const gz = /\.gz$/i.test(descriptor.path || descriptor.sourceName || '');
+    const run = state.runs.get(descriptor.key);
+    const parts = [];
+    if (Number.isFinite(descriptor.size))
+        parts.push(`${gz ? 'compressed (gzip)' : 'file'} size ${formatBytes(descriptor.size)}`);
+    if (run && run.rawBytes) parts.push(`${formatBytes(run.rawBytes)} of JSONL text`);
+    if (run && run.logFormat) parts.push(`format ${run.logFormat}`);
+    return parts.join(' · ');
+}
+
 function renderFocusOptions() {
     if (!state.catalog.length) {
         els.focusRunSelect.innerHTML = '<option value="">No runs available</option>';
@@ -716,7 +739,8 @@ async function ensureRun(descriptor) {
         setStatus('', `Fetching ${descriptor.runId}`);
         const response = await fetch(descriptor.url);
         if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);
-        text = await response.text();
+        // bytes, not text: `.jsonl.gz` inflates on the gzip magic
+        text = await F.readRunlogText(new Uint8Array(await response.arrayBuffer()));
     } else {
         throw new Error(`No loader for ${descriptor.runId}`);
     }
@@ -729,11 +753,12 @@ async function loadFiles(files) {
     let firstKey = '';
     for (const file of files) {
         const key = `file:${file.name}:${file.size}:${file.lastModified}`;
-        const text = await file.text();
+        const text = await F.readRunlogText(file); // inflates `.jsonl.gz`
         const result = await parseAndAddText(text, file.name, {
             key,
             path: file.name,
-            sourceType: 'file'
+            sourceType: 'file',
+            size: file.size
         });
         if (!firstKey) firstKey = result.descriptor.key;
     }
@@ -745,7 +770,8 @@ async function loadUrl(url) {
     setStatus('', `Fetching ${url}`);
     const response = await fetch(url);
     if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);
-    const text = await response.text();
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    const text = await F.readRunlogText(bytes); // inflates `.jsonl.gz`
     const sourceName = decodeURIComponent(
         new URL(url, window.location.href).pathname.split('/').pop() || 'runlog.jsonl'
     );
@@ -754,7 +780,8 @@ async function loadUrl(url) {
         key,
         path: url,
         url,
-        sourceType: 'url'
+        sourceType: 'url',
+        size: bytes.length
     });
     await focusDescriptor(result.descriptor.key, true);
     setStatus('ok', `Loaded ${result.descriptor.runId}`);
@@ -836,7 +863,7 @@ async function browseGithub() {
     setStatus('', `Indexing ${state.github.selectedFolders.join(', ')}`);
     try {
         const directFiles = state.github.rootItems.filter(
-            (item) => item.type === 'file' && item.name.toLowerCase().endsWith('.jsonl')
+            (item) => item.type === 'file' && F.isRunlogName(item.name)
         );
         const directoryFiles = await G.mapLimit(directories, 4, async (directory, index) => {
             setStatus('', `Indexing runlog folders ${index + 1}/${directories.length}`);
@@ -846,7 +873,7 @@ async function browseGithub() {
         const files = [
             ...directFiles.map((item) => ({ ...item, rigFolder: 'runlogs root' })),
             ...directoryFiles.flat()
-        ].filter((item) => item.type === 'file' && item.name.toLowerCase().endsWith('.jsonl'));
+        ].filter((item) => item.type === 'file' && F.isRunlogName(item.name));
         // Per-folder index.json → start / duration / end state without downloading
         // logs (browsers can't Range-read a tail from GitHub — CORS preflight 403).
         const indexByFolder = new Map();
@@ -949,16 +976,29 @@ async function listDirectoryLinks(directoryUrl) {
 async function fetchUrlPrefix(url, bytes) {
     const response = await fetch(url, { headers: { Range: `bytes=0-${bytes - 1}` } });
     if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);
-    if (!response.body || !response.body.getReader) return (await response.text()).slice(0, bytes);
+    if (!response.body || !response.body.getReader) {
+        const all = new Uint8Array(await response.arrayBuffer());
+        return (await F.readRunlogPrefixText(all.subarray(0, bytes))).slice(0, bytes);
+    }
+    // Stream bytes; a plain file stops at the run_metadata line, a `.jsonl.gz`
+    // prefix is inflated (truncation-tolerant) once the byte budget is read.
     const reader = response.body.getReader();
     const decoder = new TextDecoder();
+    const chunks = [];
+    let total = 0;
     let text = '';
+    let gzip = null;
     try {
-        while (text.length < bytes) {
+        while (total < bytes) {
             const part = await reader.read();
             if (part.done) break;
-            text += decoder.decode(part.value, { stream: true });
-            if (text.includes('"run_metadata"')) break;
+            chunks.push(part.value);
+            total += part.value.length;
+            if (gzip === null) gzip = F.isGzip(part.value);
+            if (!gzip) {
+                text += decoder.decode(part.value, { stream: true });
+                if (text.includes('"run_metadata"')) break;
+            }
         }
     } finally {
         try {
@@ -967,7 +1007,14 @@ async function fetchUrlPrefix(url, bytes) {
             /* already complete */
         }
     }
-    return text;
+    if (!gzip) return text;
+    const all = new Uint8Array(total);
+    let at = 0;
+    for (const c of chunks) {
+        all.set(c, at);
+        at += c.length;
+    }
+    return F.readRunlogPrefixText(all);
 }
 
 async function scanLocal() {
@@ -977,13 +1024,11 @@ async function scanLocal() {
     setStatus('', `Scanning ${base.pathname}`);
     try {
         const first = await listDirectoryLinks(base);
-        const direct = first.filter((url) => url.pathname.toLowerCase().endsWith('.jsonl'));
+        const direct = first.filter((url) => F.isRunlogName(url.pathname));
         const directories = first.filter((url) => url.pathname.endsWith('/'));
         const childFiles = await Promise.all(
             directories.map(async (directory) =>
-                (await listDirectoryLinks(directory)).filter((url) =>
-                    url.pathname.toLowerCase().endsWith('.jsonl')
-                )
+                (await listDirectoryLinks(directory)).filter((url) => F.isRunlogName(url.pathname))
             )
         );
         const files = [...direct, ...childFiles.flat()];
@@ -1954,7 +1999,7 @@ document.body.addEventListener('dragover', (event) => event.preventDefault());
 document.body.addEventListener('drop', async (event) => {
     event.preventDefault();
     const files = [...((event.dataTransfer && event.dataTransfer.files) || [])].filter((file) =>
-        /\.(jsonl|ndjson|json)$/i.test(file.name)
+        F.isRunlogName(file.name)
     );
     if (!files.length) return;
     try {
diff --git a/dashboard/data-browser/github-repo.js b/dashboard/data-browser/github-repo.js
index 9fc6a8e..fd3b1ad 100644
--- a/dashboard/data-browser/github-repo.js
+++ b/dashboard/data-browser/github-repo.js
@@ -8,6 +8,12 @@
     const BENCH_KEY = 'studio_bench_id';
     const FOLDERS_KEY_PREFIX = 'dashboard_runlog_folders:';
     const DEFAULT_REPO = 'reiserlab/cshl-2026-course';
+    // Run logs are committed as `.jsonl.gz` since Studio v0.72; fetchRaw reads
+    // BYTES and lets the shared format module inflate (magic-detected, so a raw
+    // `.jsonl` still works). Vendored byte-identical copy of js/runlog-format.js.
+    const F =
+        global.RunlogFormat ||
+        (typeof require === 'function' ? require('./vendor/runlog-format.js') : null);
 
     function currentToken() {
         return sessionStorage.getItem(TOKEN_KEY) || localStorage.getItem(TOKEN_KEY) || '';
@@ -175,21 +181,37 @@
         if (prefixBytes) requestHeaders.Range = `bytes=0-${Math.max(1023, prefixBytes - 1)}`;
         const response = await fetch(contentsUrl(repo, path, ref), { headers: requestHeaders });
         if (!response.ok) throw new Error(`GitHub HTTP ${response.status}`);
-        if (!prefixBytes || !response.body || !response.body.getReader) return response.text();
+        const inflateAll = (bytes) =>
+            F ? F.readRunlogText(bytes) : new TextDecoder().decode(bytes);
+        if (!prefixBytes || !response.body || !response.body.getReader) {
+            return inflateAll(new Uint8Array(await response.arrayBuffer()));
+        }
 
+        // Prefix read (catalog metadata): stream bytes until the budget is spent, or
+        // — for a plain-text file — until a complete run_metadata line is in hand.
+        // A gzip prefix cannot be scanned as text; it is inflated (truncation-
+        // tolerant) once the budget is read, which still yields the file's head.
         const reader = response.body.getReader();
         const decoder = new TextDecoder();
+        const chunks = [];
+        let total = 0;
         let text = '';
+        let gzip = null;
         try {
-            while (text.length < prefixBytes) {
+            while (total < prefixBytes) {
                 const part = await reader.read();
                 if (part.done) break;
-                text += decoder.decode(part.value, { stream: true });
-                if (
-                    text.includes('"run_metadata"') &&
-                    text.split(/\r?\n/).some((line) => line.includes('"run_metadata"'))
-                )
-                    break;
+                chunks.push(part.value);
+                total += part.value.length;
+                if (gzip === null) gzip = F ? F.isGzip(part.value) : false;
+                if (!gzip) {
+                    text += decoder.decode(part.value, { stream: true });
+                    if (
+                        text.includes('"run_metadata"') &&
+                        text.split(/\r?\n/).some((line) => line.includes('"run_metadata"'))
+                    )
+                        break;
+                }
             }
         } finally {
             try {
@@ -198,7 +220,14 @@
                 /* response may already be complete */
             }
         }
-        return text;
+        if (!gzip) return text;
+        const all = new Uint8Array(total);
+        let at = 0;
+        for (const c of chunks) {
+            all.set(c, at);
+            at += c.length;
+        }
+        return F.readRunlogPrefixText(all);
     }
 
     function fetchPrefix(repoValue, path, ref, bytes) {
diff --git a/dashboard/data-browser/index.html b/dashboard/data-browser/index.html
index 2354fba..46a89c5 100644
--- a/dashboard/data-browser/index.html
+++ b/dashboard/data-browser/index.html
@@ -8,10 +8,11 @@
   <link rel="stylesheet" href="styles.css?v=20260906-3">
   <script defer src="https://cdn.plot.ly/plotly-3.6.0.min.js" charset="utf-8"></script>
   <script defer src="vendor/kinematics.js?v=20260710-1647"></script>
-  <script defer src="analysis-core.js?v=20260906-4"></script>
+  <script defer src="vendor/runlog-format.js?v=20260907-1"></script>
+  <script defer src="analysis-core.js?v=20260907-1"></script>
   <script defer src="plot-specs.js?v=20260906"></script>
-  <script defer src="github-repo.js?v=20260906-3"></script>
-  <script defer src="app.js?v=20260906-4"></script>
+  <script defer src="github-repo.js?v=20260907-1"></script>
+  <script defer src="app.js?v=20260907-1"></script>
 </head>
 <body>
   <header class="app-header">
@@ -40,7 +41,7 @@ <h2>Data</h2>
       <div class="source-grid">
         <label class="file-button command-button">
           Open JSONL files
-          <input id="fileInput" type="file" accept=".jsonl,.ndjson,.json,text/plain" multiple>
+          <input id="fileInput" type="file" accept=".jsonl,.gz,.ndjson,.json,text/plain" multiple title="Open run logs (.jsonl or gzipped .jsonl.gz; behavior_v1 and behavior_v2 formats)">
         </label>
 
         <div class="inline-control url-loader">
diff --git a/dashboard/data-browser/styles.css b/dashboard/data-browser/styles.css
index a835c92..3a4cbdb 100644
--- a/dashboard/data-browser/styles.css
+++ b/dashboard/data-browser/styles.css
@@ -534,6 +534,12 @@ main {
   line-height: 1.2;
 }
 
+.run-row .run-size {
+  color: var(--text-dim, #8b949e);
+  font-size: 0.85em;
+  white-space: nowrap;
+}
+
 .run-row .run-sex {
   color: #d4b5e9;
   text-transform: uppercase;
diff --git a/dashboard/data-browser/tests/corpus-v2-parity.js b/dashboard/data-browser/tests/corpus-v2-parity.js
new file mode 100644
index 0000000..9a60be4
--- /dev/null
+++ b/dashboard/data-browser/tests/corpus-v2-parity.js
@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+/**
+ * corpus-v2-parity.js — the dashboard's half of the behavior_v2 corpus gate
+ * (docs/development/runlog-behavior-v2-plan.md, Part 3 §4).
+ *
+ * For EVERY run log under a course-repo clone: parse the v1 file, convert it to
+ * behavior_v2 in memory (js/runlog-format.js, the JS mirror of the bridge's
+ * converter), gzip it, read it back through the SAME loader path the dashboard
+ * uses (readRunlogText → parseJsonl) and assert the analysis is identical:
+ * frame count + first/last frame, event count, step summaries, every P3
+ * preference index, and — for every P3 run — the CSV rows of every built page.
+ * Prints a Markdown table; exit 1 on any difference. Needs the clone (not part of
+ * `pixi run test`, like test-analysis.js).
+ *
+ *   node dashboard/data-browser/tests/corpus-v2-parity.js [ROOT]
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const zlib = require('zlib');
+const A = require('../analysis-core.js');
+const P = require('../plot-specs.js');
+const F = require('../vendor/runlog-format.js');
+
+const root =
+    process.argv[2] || path.join(process.env.HOME || '', 'Documents/GitHub/cshl-2026-course');
+const OPTS = { ballDiameterMm: 9, smoothWindowS: 0.5 };
+
+function walk(dir) {
+    const out = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name === '.git') continue;
+        const p = path.join(dir, entry.name);
+        if (entry.isDirectory()) out.push(...walk(p));
+        else if (F.isRunlogName(entry.name)) out.push(p);
+    }
+    return out.sort();
+}
+
+function stripVolatile(run) {
+    // Everything analysis-relevant, minus what legitimately differs between the
+    // v1 and the v2.gz read: the file name, and the frame_schema line itself (a
+    // legacy/full-level file has none; its v2 conversion inserts one).
+    const events = run.events.filter((e) => e.type !== 'frame_schema');
+    // lineNumber is a file position (shifts by one when a schema line is inserted),
+    // not an analysis value.
+    const frame = (f) => (f ? { ...f, lineNumber: undefined } : null);
+    return {
+        frames: run.frames.length,
+        firstFrame: frame(run.frames[0]),
+        lastFrame: frame(run.frames[run.frames.length - 1]),
+        events: events.length,
+        eventShapes: events.map((e) => `${e.type}/${e.event || ''}/${e.phase || ''}`).join(','),
+        steps: run.steps.map((s) => ({
+            index: s.index,
+            condition: s.condition,
+            startMs: s.startMs,
+            endMs: s.endMs,
+            frameCount: s.frameCount,
+            meanForward: s.meanForward,
+            meanTurning: s.meanTurning,
+            missingFrames: s.missingFrames
+        })),
+        metadata: run.metadata,
+        family: run.protocolInfo.family,
+        totalMissingFrames: run.totalMissingFrames,
+        parseErrors: run.parseErrors.length
+    };
+}
+
+function pagesCsv(run) {
+    return P.buildPages([run], { mode: 'single', showIndividuals: true }).map((page) => ({
+        id: page.id,
+        csv: page.csvRows || []
+    }));
+}
+
+async function checkFile(file) {
+    const rel = path.relative(root, file);
+    const row = { file: rel, ok: true, notes: [] };
+    try {
+        const raw = fs.readFileSync(file);
+        const v1Text = await F.readRunlogText(new Uint8Array(raw));
+        const fmt = F.detectFormat(v1Text);
+        row.fmt = fmt;
+        const v2Text = fmt === 'behavior_v2' ? v1Text : F.convertV1ToV2Text(v1Text);
+        const gz = zlib.gzipSync(Buffer.from(v2Text));
+        const readBack = await F.readRunlogText(new Uint8Array(gz));
+        const name = path.basename(file);
+        const r1 = A.parseJsonl(v1Text, name, rel, OPTS);
+        const r2 = A.parseJsonl(readBack, name + '.gz', rel + '.gz', OPTS);
+        row.frames = r1.frames.length;
+        row.v1 = raw.length;
+        row.v2gz = gz.length;
+        row.logFormat = r2.logFormat;
+        const s1 = JSON.stringify(stripVolatile(r1));
+        const s2 = JSON.stringify(stripVolatile(r2));
+        if (s1 !== s2) {
+            row.ok = false;
+            row.notes.push('run summary differs');
+        }
+        if (r2.id !== r1.id) {
+            row.ok = false;
+            row.notes.push('run id differs');
+        }
+        const isP3 = /^p3/.test(r1.protocolInfo.family);
+        row.p3 = isP3;
+        if (isP3) {
+            const pi1 = r1.steps.map((s) => A.p3PreferenceIndex(r1, s, 0));
+            const pi2 = r2.steps.map((s) => A.p3PreferenceIndex(r2, s, 0));
+            if (JSON.stringify(pi1) !== JSON.stringify(pi2)) {
+                row.ok = false;
+                row.notes.push('P3 preference indices differ');
+            }
+            const c1 = JSON.stringify(pagesCsv(r1));
+            const c2 = JSON.stringify(pagesCsv(r2));
+            row.csvRows = pagesCsv(r1).reduce((n, p) => n + p.csv.length, 0);
+            if (c1 !== c2) {
+                row.ok = false;
+                row.notes.push('P3 page CSV rows differ');
+            }
+        }
+    } catch (e) {
+        row.ok = false;
+        row.notes.push(`${e.constructor.name}: ${e.message}`);
+    }
+    return row;
+}
+
+(async () => {
+    const files = walk(root);
+    if (!files.length) {
+        console.error(`no run logs under ${root}`);
+        process.exit(2);
+    }
+    console.error(`[parity] ${files.length} files under ${root}`);
+    const rows = [];
+    for (const file of files) {
+        const row = await checkFile(file);
+        rows.push(row);
+        console.error(
+            `[parity] ${row.ok ? 'ok  ' : 'FAIL'} ${row.file}${row.notes.length ? ' — ' + row.notes.join('; ') : ''}`
+        );
+    }
+    const ok = rows.filter((r) => r.ok).length;
+    const p3 = rows.filter((r) => r.p3);
+    const mb = (n) => (n / 1e6).toFixed(1);
+    const out = [];
+    out.push(`## Dashboard v1 vs v2.gz parity — ${files.length} run logs under \`${root}\``);
+    out.push('');
+    out.push(
+        `**${ok} / ${rows.length} identical** (frames, events, step summaries, metadata, run id${p3.length ? `; plus every P3 preference index and every P3 page's CSV rows for the ${p3.length} P3 runs` : ''}). Formats: ` +
+            Object.entries(rows.reduce((m, r) => ((m[r.fmt] = (m[r.fmt] || 0) + 1), m), {}))
+                .map(([k, v]) => `${v} ${k}`)
+                .join(', ') +
+            '.'
+    );
+    out.push('');
+    const bad = rows.filter((r) => !r.ok);
+    if (bad.length) {
+        out.push('### FAILURES');
+        for (const r of bad) out.push(`- \`${r.file}\`: ${r.notes.join('; ')}`);
+        out.push('');
+    }
+    out.push('<details><summary>All files</summary>');
+    out.push('');
+    out.push('| file | fmt | ok | frames | P3 csv rows | v1 MB | v2.gz MB |');
+    out.push('|---|---|---|---:|---:|---:|---:|');
+    for (const r of rows)
+        out.push(
+            `| ${r.file} | ${r.fmt || '?'} | ${r.ok ? '✓' : '✗'} | ${r.frames ?? ''} | ${r.csvRows ?? ''} | ${r.v1 ? mb(r.v1) : ''} | ${r.v2gz ? mb(r.v2gz) : ''} |`
+        );
+    out.push('');
+    out.push('</details>');
+    console.log(out.join('\n'));
+    process.exit(bad.length ? 1 : 0);
+})();
diff --git a/dashboard/data-browser/tests/test-analysis.js b/dashboard/data-browser/tests/test-analysis.js
index fc4407a..ed619d7 100644
--- a/dashboard/data-browser/tests/test-analysis.js
+++ b/dashboard/data-browser/tests/test-analysis.js
@@ -5,6 +5,8 @@ const fs = require('fs');
 const path = require('path');
 const A = require('../analysis-core.js');
 const P = require('../plot-specs.js');
+const F = require('../vendor/runlog-format.js');
+const zlib = require('zlib');
 
 const repo = process.argv[2] || '/Users/reiserm/Documents/GitHub/cshl-2026-course';
 const bench = path.join(repo, 'runlogs', 'bench02');
@@ -607,3 +609,86 @@ console.log(
     assert.strictEqual(A.runIndexLookup({ runs: 'nope' }).size, 0);
     console.log('runlog index lookup OK');
 }
+
+// ── behavior_v2 + gzip: the same run read as v1 .jsonl and as v2 .jsonl.gz must
+// produce identical analysis (runlog-behavior-v2-plan.md Part 3 §4). The v2 text is
+// generated from the v1 fixture by the JS mirror of the bridge converter.
+(async () => {
+    const v1Path = path.join(bench, fixtures.p3);
+    const v1Text = fs.readFileSync(v1Path, 'utf8');
+    assert.strictEqual(F.detectFormat(v1Text), 'behavior_v1');
+    const v2Text = F.convertV1ToV2Text(v1Text);
+    assert.strictEqual(F.detectFormat(v2Text), 'behavior_v2');
+    const v2Lines = v2Text.trim().split('\n');
+    const compact = v2Lines.filter((l) => l.startsWith('["a",')).length;
+    assert.ok(compact > 1000, `compact arena echoes present (${compact})`);
+    assert.ok(v2Text.length < v1Text.length * 0.6, 'v2 text is much smaller');
+    // Byte identity is not expected (the bridge escapes non-ASCII as \u2192, JS
+    // emits the literal arrow); JSON identity line by line is the lossless claim.
+    const parseAll = (text) =>
+        text
+            .trim()
+            .split('\n')
+            .map((line) => JSON.parse(line));
+    assert.deepStrictEqual(
+        parseAll(F.convertV2ToV1Text(v2Text)),
+        parseAll(v1Text),
+        'v2 → v1 restores every fixture line'
+    );
+    const gz = new Uint8Array(zlib.gzipSync(Buffer.from(v2Text)));
+    assert.ok(F.isGzip(gz));
+    const name = fixtures.p3.split('/').pop();
+    const readBack = await F.readRunlogText(gz);
+    assert.strictEqual(readBack, v2Text, 'gz inflates to the v2 text');
+    const p3v2 = A.parseJsonl(readBack, name + '.gz', v1Path + '.gz', {
+        ballDiameterMm: 9,
+        smoothWindowS: 0.5
+    });
+    assert.strictEqual(p3.logFormat, 'behavior_v1');
+    assert.strictEqual(p3v2.logFormat, 'behavior_v2');
+    assert.strictEqual(p3v2.id, p3.id, 'same run id from .jsonl.gz');
+    assert.strictEqual(A.parseFilename(name + '.gz').runId, A.parseFilename(name).runId);
+    assert.strictEqual(p3v2.frames.length, p3.frames.length, 'same frame count');
+    assert.deepStrictEqual(p3v2.frames[0], p3.frames[0]);
+    assert.deepStrictEqual(p3v2.frames[p3.frames.length - 1], p3.frames[p3.frames.length - 1]);
+    assert.strictEqual(p3v2.events.length, p3.events.length, 'same event count (expanded echoes)');
+    const arena1 = p3.events.filter((e) => e.event === 'arena_command');
+    const arena2 = p3v2.events.filter((e) => e.event === 'arena_command');
+    assert.strictEqual(arena2.length, arena1.length, 'same arena_command count');
+    assert.deepStrictEqual(
+        arena2.map(({ lineNumber, ...rest }) => rest),
+        arena1.map(({ lineNumber, ...rest }) => rest),
+        'every expanded arena_command equals the v1 object'
+    );
+    assert.strictEqual(p3v2.parseErrors.length, 0);
+    assert.strictEqual(p3v2.steps.length, p3.steps.length);
+    const pi1 = p3.steps.map((s) => A.p3PreferenceIndex(p3, s, 0));
+    const pi2 = p3v2.steps.map((s) => A.p3PreferenceIndex(p3v2, s, 0));
+    assert.deepStrictEqual(pi2, pi1, 'identical P3 preference indices');
+    assert.deepStrictEqual(A.p3LedEpochs(p3v2), A.p3LedEpochs(p3), 'identical LED epochs');
+    const pages1 = P.buildPages([p3], { mode: 'single', showIndividuals: true });
+    const pages2 = P.buildPages([p3v2], { mode: 'single', showIndividuals: true });
+    assert.strictEqual(pages2.length, pages1.length);
+    pages1.forEach((page, i) => {
+        assert.strictEqual(pages2[i].id, page.id);
+        assert.deepStrictEqual(
+            pages2[i].csvRows,
+            page.csvRows,
+            `identical CSV rows for ${page.id}`
+        );
+    });
+    // and the prefix read used by the catalog still finds run_metadata in a .gz head
+    const head = await F.readRunlogPrefixText(gz.subarray(0, 65536));
+    const desc = A.parseMetadataPrefix(head, name + '.gz', v1Path + '.gz');
+    assert.strictEqual(desc.runId, p3.descriptor.runId, 'metadata from a gz prefix');
+    console.log(
+        'behavior_v2 + gzip parity OK:',
+        compact,
+        'compact echoes;',
+        pages1.length,
+        'pages identical'
+    );
+})().catch((e) => {
+    console.error(e);
+    process.exit(1);
+});
diff --git a/dashboard/data-browser/vendor/runlog-format.js b/dashboard/data-browser/vendor/runlog-format.js
new file mode 100644
index 0000000..ff3845e
--- /dev/null
+++ b/dashboard/data-browser/vendor/runlog-format.js
@@ -0,0 +1,481 @@
+/**
+ * runlog-format.js — ONE place that knows how a run-log FILE is encoded, shared by
+ * every reader: the analysis dashboard (dashboard/data-browser, via an exact
+ * vendored copy), the replay parser (js/runlog-replay.js) and the Alt Studio
+ * replay picker (js/arena-studio-alt.js). Plan: docs/development/runlog-behavior-v2-plan.md.
+ *
+ * Two orthogonal encodings, both lossless:
+ *   1. gzip — since Studio v0.72 run logs are committed as `<name>.jsonl.gz`.
+ *      Detect by the magic bytes (1f 8b), never by name alone: `inflateIfGzip`,
+ *      `readRunlogText` (any of string / bytes / ArrayBuffer / Blob|File → text),
+ *      `readRunlogPrefixText` (a truncated prefix of a .gz still inflates to the
+ *      run_metadata line near the top — the catalog reads 64 KB prefixes).
+ *   2. line format — `behavior_v1` (pre-2026-09) vs `behavior_v2` (bridge ≥ 3.0):
+ *      identical frame arrays [ms,fc,idx,ft,x,y,hd]; v2 writes each browser
+ *      `arena_command` echo as the compact array
+ *        ["a", t_off, dt, hex, status, rx_off(, error)]
+ *      with ms offsets from the v2 frame_schema line's `t0`. `expandV2Line`
+ *      rebuilds the EXACT v1 object (key order type,event,t,dt,len,head,status,
+ *      echo,ok,error,dir,rx_ms) so every existing consumer keeps working; readers
+ *      call `createNormalizer()` and pass each parsed line through `normalize()`.
+ *      Timeout rule (verified on the course corpus, bridge.py mirrors it): when
+ *      `status` is null then `echo` and `ok` are null too — NOT false.
+ *      A v2 file may still carry a verbatim v1 `arena_command` object (an echo the
+ *      bridge could not compact, e.g. a bulk command with a truncated ` …` head)
+ *      and a converted legacy file may carry `"cols": null` in its schema.
+ *
+ * `compactV1Line` / `convertV1ToV2Text` / `convertV2ToV1Text` are the JS mirror of
+ * the bridge's converter — used by the tests and the corpus parity script so the
+ * readers can be exercised on v2 data generated from every existing v1 log.
+ *
+ * LOADING: classic <script src> (window-global `RunlogFormat` + CommonJS), no ES
+ * `export` — same rule as arena-session.js (see CLAUDE.md). Load it BEFORE
+ * js/runlog-replay.js. The dashboard's copy at dashboard/data-browser/vendor/ must
+ * stay byte-identical (tests/test-runlog-format.js enforces it).
+ */
+(function (global) {
+    'use strict';
+
+    const GZIP_MAGIC_0 = 0x1f;
+    const GZIP_MAGIC_1 = 0x8b;
+    const ARENA_TAG = 'a';
+    const ARENA_DIR = 'browser→bridge';
+    const BEHAVIOR_V2_ARENA_COLS = ['t_off', 'dt', 'hex', 'status', 'rx_off'];
+    const ARENA_COMMAND_KEYS = [
+        'type',
+        'event',
+        't',
+        'dt',
+        'len',
+        'head',
+        'status',
+        'echo',
+        'ok',
+        'error',
+        'dir',
+        'rx_ms'
+    ];
+    const RUNLOG_NAME_RE = /\.(jsonl|ndjson|json)(\.gz)?$/i;
+
+    // ── bytes / gzip ────────────────────────────────────────────────────────────
+    function toBytes(input) {
+        if (input instanceof Uint8Array) return input;
+        if (typeof ArrayBuffer !== 'undefined' && input instanceof ArrayBuffer)
+            return new Uint8Array(input);
+        if (input && ArrayBuffer.isView && ArrayBuffer.isView(input))
+            return new Uint8Array(input.buffer, input.byteOffset, input.byteLength);
+        if (typeof input === 'string') return new TextEncoder().encode(input);
+        throw new Error(
+            'RunlogFormat: cannot read bytes from ' + Object.prototype.toString.call(input)
+        );
+    }
+
+    function isGzip(bytes) {
+        let u8;
+        try {
+            u8 = toBytes(bytes);
+        } catch (_) {
+            return false;
+        }
+        return u8.length >= 2 && u8[0] === GZIP_MAGIC_0 && u8[1] === GZIP_MAGIC_1;
+    }
+
+    function isRunlogName(name) {
+        return RUNLOG_NAME_RE.test(String(name || ''));
+    }
+
+    /** `run.jsonl.gz` → `run.jsonl` (filename parsers key on the .jsonl stem). */
+    function stripGz(name) {
+        return String(name || '').replace(/\.gz$/i, '');
+    }
+
+    function concatBytes(chunks) {
+        let n = 0;
+        for (const c of chunks) n += c.length;
+        const out = new Uint8Array(n);
+        let at = 0;
+        for (const c of chunks) {
+            out.set(c, at);
+            at += c.length;
+        }
+        return out;
+    }
+
+    /**
+     * gunzip. `tolerateTruncation` returns what could be inflated from a cut-off
+     * stream (a file prefix) instead of throwing at the missing trailer.
+     */
+    async function inflate(bytes, tolerateTruncation) {
+        const u8 = toBytes(bytes);
+        if (typeof DecompressionStream !== 'undefined') {
+            const stream = new Blob([u8]).stream().pipeThrough(new DecompressionStream('gzip'));
+            const reader = stream.getReader();
+            const chunks = [];
+            try {
+                for (;;) {
+                    const part = await reader.read();
+                    if (part.done) break;
+                    chunks.push(part.value);
+                }
+            } catch (err) {
+                if (!tolerateTruncation) throw err;
+            }
+            return concatBytes(chunks);
+        }
+        if (typeof require === 'function') {
+            const zlib = require('zlib');
+            const buf = zlib.gunzipSync(
+                Buffer.from(u8.buffer, u8.byteOffset, u8.byteLength),
+                tolerateTruncation ? { finishFlush: zlib.constants.Z_SYNC_FLUSH } : undefined
+            );
+            return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+        }
+        throw new Error('RunlogFormat: no gzip support (DecompressionStream missing)');
+    }
+
+    /** Bytes in → bytes out, inflated when they start with the gzip magic. */
+    async function inflateIfGzip(bytes) {
+        const u8 = toBytes(bytes);
+        return isGzip(u8) ? inflate(u8, false) : u8;
+    }
+
+    function decodeText(u8) {
+        return new TextDecoder('utf-8').decode(u8);
+    }
+
+    /**
+     * The one entry point for loaders: string (returned as-is), Uint8Array /
+     * ArrayBuffer / typed array, or a Blob|File (anything with arrayBuffer()) →
+     * the log TEXT, inflated when gzipped.
+     */
+    async function readRunlogText(input) {
+        if (typeof input === 'string') return input;
+        if (input && typeof input.arrayBuffer === 'function' && !(input instanceof Uint8Array)) {
+            input = await input.arrayBuffer();
+        }
+        return decodeText(await inflateIfGzip(toBytes(input)));
+    }
+
+    /**
+     * A possibly TRUNCATED prefix of a file (the catalog's 64 KB metadata read) →
+     * as much text as can be recovered; gzip prefixes inflate partially.
+     */
+    async function readRunlogPrefixText(input) {
+        if (typeof input === 'string') return input;
+        const u8 = toBytes(input);
+        if (!isGzip(u8)) return decodeText(u8);
+        try {
+            return decodeText(await inflate(u8, true));
+        } catch (_) {
+            return '';
+        }
+    }
+
+    // ── behavior_v2 line format ─────────────────────────────────────────────────
+    function isInt(v) {
+        return Number.isInteger(v);
+    }
+
+    function isArenaArray(value) {
+        return (
+            Array.isArray(value) &&
+            (value.length === 6 || value.length === 7) &&
+            value[0] === ARENA_TAG
+        );
+    }
+
+    function isSchemaRecord(rec) {
+        return (
+            !!rec && !Array.isArray(rec) && typeof rec === 'object' && rec.type === 'frame_schema'
+        );
+    }
+
+    function hexBytes(hex) {
+        if (typeof hex !== 'string' || hex.length % 2 || !/^[0-9a-f]*$/.test(hex)) return null;
+        const parts = [];
+        for (let i = 0; i < hex.length; i += 2) parts.push(hex.slice(i, i + 2));
+        return parts;
+    }
+
+    /**
+     * ["a", t_off, dt, hex, status, rx_off(, error)] → the exact v1 arena_command
+     * object. `schema` is the v2 frame_schema record (uses its `t0`) or a number.
+     * Throws on a malformed array.
+     */
+    function expandV2Line(arr, schema) {
+        if (!isArenaArray(arr)) throw new Error('RunlogFormat: not a compact arena array');
+        const t0 = typeof schema === 'number' ? schema : schema && schema.t0;
+        const tOff = arr[1];
+        const dt = arr[2];
+        const hex = arr[3];
+        const status = arr[4];
+        const rxOff = arr[5];
+        const error = arr.length === 7 ? arr[6] : null;
+        if (!isInt(t0) || !isInt(tOff) || !isInt(rxOff))
+            throw new Error('RunlogFormat: t0/t_off/rx_off must be integers');
+        if (typeof dt !== 'number') throw new Error('RunlogFormat: dt must be a number');
+        const parts = hexBytes(hex);
+        if (!parts) throw new Error('RunlogFormat: malformed hex ' + JSON.stringify(hex));
+        if (status !== null && !isInt(status))
+            throw new Error('RunlogFormat: status must be int or null');
+        if (status !== null && parts.length < 2)
+            throw new Error('RunlogFormat: status present but no command byte');
+        if (error !== null && typeof error !== 'string')
+            throw new Error('RunlogFormat: error must be a string');
+        return {
+            type: 'log',
+            event: 'arena_command',
+            t: t0 + tOff,
+            dt: dt,
+            len: parts.length,
+            head: parts.join(' '),
+            status: status,
+            echo: status === null ? null : parseInt(parts[1], 16),
+            ok: status === null ? null : status === 0,
+            error: error,
+            dir: ARENA_DIR,
+            rx_ms: t0 + rxOff
+        };
+    }
+
+    /**
+     * v1 arena_command object → compact array, or null when the object does not fit
+     * the fixed shape (then it stays verbatim). Mirrors bridge.py's invariants.
+     */
+    function compactV1Line(obj, t0) {
+        if (!obj || Array.isArray(obj) || typeof obj !== 'object') return null;
+        if (obj.type !== 'log' || obj.event !== 'arena_command') return null;
+        const keys = Object.keys(obj);
+        if (keys.length !== ARENA_COMMAND_KEYS.length) return null;
+        for (const k of ARENA_COMMAND_KEYS) if (!(k in obj)) return null;
+        if (obj.dir !== ARENA_DIR) return null;
+        if (!isInt(t0) || !isInt(obj.t) || !isInt(obj.rx_ms)) return null;
+        if (typeof obj.dt !== 'number') return null;
+        if (typeof obj.head !== 'string' || !obj.head) return null;
+        const parts = obj.head.split(' ');
+        if (!parts.every((p) => /^[0-9a-f]{2}$/.test(p))) return null;
+        if (obj.len !== parts.length) return null;
+        if (obj.status === null) {
+            if (obj.echo !== null || obj.ok !== null) return null;
+        } else {
+            if (!isInt(obj.status)) return null;
+            if (parts.length < 2 || obj.echo !== parseInt(parts[1], 16)) return null;
+            if (typeof obj.ok !== 'boolean' || obj.ok !== (obj.status === 0)) return null;
+        }
+        if (obj.error !== null && typeof obj.error !== 'string') return null;
+        const arr = [ARENA_TAG, obj.t - t0, obj.dt, parts.join(''), obj.status, obj.rx_ms - t0];
+        if (obj.error !== null) arr.push(obj.error);
+        return arr;
+    }
+
+    /**
+     * 'behavior_v2' | 'behavior_v1' | 'full' | 'legacy' | 'unknown' from either the
+     * log text (first `maxLines` lines) or an array of parsed records. The schema
+     * line decides; without one, "a" arrays mean v2, fictrac_frame objects with the
+     * 25-column array mean `full`, other content is a pre-#140 log.
+     */
+    function detectFormat(input, maxLines) {
+        let records = input;
+        if (typeof input === 'string') {
+            records = [];
+            const lines = input.split(/\r?\n/);
+            const n = Math.min(lines.length, maxLines || 200);
+            for (let i = 0; i < n; i++) {
+                const ln = lines[i].trim();
+                if (!ln) continue;
+                try {
+                    records.push(JSON.parse(ln));
+                } catch (_) {
+                    /* torn line */
+                }
+            }
+        }
+        if (!Array.isArray(records) || !records.length) return 'unknown';
+        let sawFull = false;
+        let sawAny = false;
+        for (const o of records) {
+            sawAny = true;
+            if (isSchemaRecord(o)) return String(o.level || 'behavior_v1');
+            if (isArenaArray(o)) return 'behavior_v2';
+            if (
+                o &&
+                typeof o === 'object' &&
+                o.type === 'fictrac_frame' &&
+                Array.isArray(o.fictrac)
+            )
+                sawFull = true;
+        }
+        if (!sawAny) return 'unknown';
+        return sawFull ? 'full' : 'legacy';
+    }
+
+    /**
+     * Per-file state machine for readers: feed every parsed line through
+     * `normalize(rec)`; it remembers the frame_schema (v1 or v2), expands compact
+     * arena arrays to v1 objects, and passes everything else through untouched.
+     * `format` reports what the file turned out to be once enough lines went by.
+     */
+    function createNormalizer() {
+        const state = {
+            schema: null,
+            level: null,
+            orphanArena: 0,
+            sawFull: false,
+            sawAny: false
+        };
+        return {
+            get schema() {
+                return state.schema;
+            },
+            get level() {
+                return state.level;
+            },
+            get orphanArena() {
+                return state.orphanArena;
+            },
+            get format() {
+                if (state.level) return state.level;
+                if (!state.sawAny) return 'unknown';
+                return state.sawFull ? 'full' : 'legacy';
+            },
+            normalize(rec) {
+                state.sawAny = true;
+                if (isSchemaRecord(rec)) {
+                    state.schema = rec;
+                    state.level = String(rec.level || 'behavior_v1');
+                    return rec;
+                }
+                if (isArenaArray(rec)) {
+                    if (!state.schema || !isInt(state.schema.t0)) {
+                        // No t0 → the timestamps could not be trusted; leave the array
+                        // (readers ignore it as a frame row) and count it.
+                        state.orphanArena++;
+                        if (!state.level) state.level = 'behavior_v2';
+                        return rec;
+                    }
+                    if (!state.level) state.level = 'behavior_v2';
+                    return expandV2Line(rec, state.schema);
+                }
+                if (
+                    rec &&
+                    typeof rec === 'object' &&
+                    !Array.isArray(rec) &&
+                    rec.type === 'fictrac_frame' &&
+                    Array.isArray(rec.fictrac)
+                )
+                    state.sawFull = true;
+                return rec;
+            }
+        };
+    }
+
+    // ── whole-text converters (JS mirror of bridge.py --convert; tests + parity) ──
+    function parseLines(text) {
+        const out = [];
+        for (const line of String(text).split(/\r?\n/)) {
+            const ln = line.trim();
+            if (!ln) continue;
+            out.push(JSON.parse(ln));
+        }
+        return out;
+    }
+
+    function dumpLines(records) {
+        return records.map((r) => JSON.stringify(r)).join('\n') + (records.length ? '\n' : '');
+    }
+
+    function isSession(o) {
+        return o && typeof o === 'object' && !Array.isArray(o) && o.type === 'session';
+    }
+
+    /** behavior_v1 / legacy / full text → behavior_v2 text (lossless). */
+    function convertV1ToV2Text(text) {
+        const records = parseLines(text);
+        const schemaIdx = records.findIndex(isSchemaRecord);
+        let cols = null;
+        if (schemaIdx >= 0) {
+            const sch = records[schemaIdx];
+            if (sch.level === 'behavior_v2') throw new Error('already behavior_v2');
+            cols = sch.cols;
+        }
+        let t0 = null;
+        for (const o of records) {
+            if (isSession(o) && isInt(o.ms)) {
+                t0 = o.ms;
+                break;
+            }
+        }
+        if (t0 === null) {
+            const a = records.find(
+                (o) =>
+                    o && typeof o === 'object' && !Array.isArray(o) && o.event === 'arena_command'
+            );
+            t0 = a && isInt(a.t) ? a.t : 0;
+        }
+        const schema = {
+            type: 'frame_schema',
+            level: 'behavior_v2',
+            cols: cols,
+            arena_cols: BEHAVIOR_V2_ARENA_COLS.slice(),
+            t0: t0
+        };
+        const insertAt =
+            schemaIdx >= 0 ? schemaIdx : records.length && isSession(records[0]) ? 1 : 0;
+        const out = [];
+        records.forEach((o, i) => {
+            if (i === schemaIdx) {
+                out.push(schema);
+                return;
+            }
+            if (schemaIdx < 0 && i === insertAt) out.push(schema);
+            if (o && typeof o === 'object' && !Array.isArray(o) && o.event === 'arena_command') {
+                const arr = compactV1Line(o, t0);
+                out.push(arr || o);
+            } else out.push(o);
+        });
+        if (schemaIdx < 0 && insertAt >= records.length) out.push(schema);
+        return dumpLines(out);
+    }
+
+    /** behavior_v2 text → behavior_v1 text (the exact inverse). */
+    function convertV2ToV1Text(text) {
+        const records = parseLines(text);
+        const schemaIdx = records.findIndex(isSchemaRecord);
+        if (schemaIdx < 0 || records[schemaIdx].level !== 'behavior_v2')
+            throw new Error('not a behavior_v2 log');
+        const sch = records[schemaIdx];
+        const out = [];
+        records.forEach((o, i) => {
+            if (i === schemaIdx) {
+                if (sch.cols !== null && sch.cols !== undefined)
+                    out.push({ type: 'frame_schema', level: 'behavior_v1', cols: sch.cols });
+                return;
+            }
+            out.push(isArenaArray(o) ? expandV2Line(o, sch) : o);
+        });
+        return dumpLines(out);
+    }
+
+    const RunlogFormat = {
+        ARENA_TAG,
+        ARENA_DIR,
+        ARENA_COMMAND_KEYS,
+        BEHAVIOR_V2_ARENA_COLS,
+        isGzip,
+        isRunlogName,
+        stripGz,
+        inflateIfGzip,
+        readRunlogText,
+        readRunlogPrefixText,
+        isArenaArray,
+        expandV2Line,
+        compactV1Line,
+        detectFormat,
+        createNormalizer,
+        convertV1ToV2Text,
+        convertV2ToV1Text
+    };
+
+    if (typeof module !== 'undefined' && module.exports) module.exports = RunlogFormat;
+    global.RunlogFormat = RunlogFormat;
+})(typeof window !== 'undefined' ? window : globalThis);
diff --git a/docs/development/arena-studio-release-notes.md b/docs/development/arena-studio-release-notes.md
index 659e1dc..99ddab7 100644
--- a/docs/development/arena-studio-release-notes.md
+++ b/docs/development/arena-studio-release-notes.md
@@ -4,6 +4,15 @@ The Studio's footer used to carry the full changelog inline; it now shows one li
 history lives here. Newest first. (Per-session engineering detail stays in
 `arena-studio-handover.md` and the design docs — this file is the user-facing what-changed list.)
 
+## v0.73 (2026-09-06) · Replay opens gzipped and `behavior_v2` run logs
+
+- **Replay reads the new log files.** The Alt replay picker lists and opens `.jsonl.gz`
+  files (from the repo or a local file) and understands the compact `behavior_v2`
+  arena echoes, so runs recorded by a v0.72 Studio replay exactly like older ones.
+  The shared decoder (`js/runlog-format.js`) is the same code the analysis dashboard
+  now uses, which also opens `.jsonl.gz` and `behavior_v2` from the repo, a local
+  server, a URL or a dropped file and shows the committed size in its catalog.
+
 ## v0.72 (2026-09-06) · Run logs commit gzipped; compact `behavior_v2` log format; the bridge confirms the log level
 
 - **Run logs now commit as `.jsonl.gz`.** The Studio gzips the exported log in the
diff --git a/docs/development/runlog-behavior-v2-plan.md b/docs/development/runlog-behavior-v2-plan.md
index 95362e5..0832569 100644
--- a/docs/development/runlog-behavior-v2-plan.md
+++ b/docs/development/runlog-behavior-v2-plan.md
@@ -1,12 +1,11 @@
-# Run-log format `behavior_v2` + large-file commit path — PLAN (PRs 1–2 shipped; PR 3 readers pending)
+# Run-log format `behavior_v2` + large-file commit path — PLAN (PRs 1–3 implemented 2026-09-06)
 
 Owner: Michael. Drafted 2026-09-06 from the analysis of rig03-sr run `rydc2tql`
-(40 s trials, 51.4 MB, failed to auto-commit). Status: **PR 1 (bridge) and PR 2
-(Studio) implemented 2026-09-06** — see the implementation notes at the end; PR 3
-(dashboard/readers) not started. Implementation lands as three PRs (bridge, Studio,
-dashboard) in that order. **Merge PR 2 together with (or after) PR 3:** once PR 2 is
-live, new course runs commit as `.jsonl.gz`, which the dashboard and replay viewer
-cannot open until PR 3 lands.
+(40 s trials, 51.4 MB, failed to auto-commit). Status: **all three PRs implemented
+2026-09-06** (bridge #183 → Studio → readers, stacked) — see the implementation notes
+at the end. None bench-tested yet. **Merge order:** PR 3 (readers) must be live before
+or together with PR 2 (Studio): once PR 2 is live, new course runs commit as
+`.jsonl.gz`, which only PR 3's readers open.
 
 ## Problem
 
@@ -256,3 +255,33 @@ Studio (PR 2) and reader (PR 3) work must build on:
 - **Bench check when hardware is back:** recorded 20 s run → `.jsonl.gz` committed with the
   size shown; banner names `behavior_v2`; then run against a deliberately old bridge
   checkout and confirm the "bridge too old" warning + `log_format: behavior_v1`.
+
+## PR 3 implementation notes (readers, 2026-09-06)
+
+- **`js/runlog-format.js`** (classic dual-export; vendored byte-identical at
+  `dashboard/data-browser/vendor/runlog-format.js`, enforced by `tests/test-runlog-format.js`):
+  `isGzip`, `isRunlogName` (`.jsonl|.ndjson|.json` with optional `.gz`), `stripGz`,
+  `inflateIfGzip`, `readRunlogText(string|bytes|ArrayBuffer|Blob)`, `readRunlogPrefixText`
+  (truncation-tolerant gunzip for the catalog's 64 KB metadata reads), `isArenaArray`,
+  `expandV2Line` (exact v1 object; timeout ⇒ status/echo/ok all null), `compactV1Line`,
+  `detectFormat`, `createNormalizer()` (per-file state machine every reader feeds each
+  parsed line through), `convertV1ToV2Text` / `convertV2ToV1Text` (JS mirror of the bridge
+  converter — tests + parity).
+- **Dashboard:** `analysis-core.js parseJsonl` normalizes every line (v2 echoes reach
+  `p3LedEpochs`, stall forensics etc. as v1 objects); `run.logFormat` + `run.rawBytes`;
+  `parseFilename` strips `.gz`. `github-repo.js fetchRaw` reads BYTES and inflates on the
+  magic (prefix mode inflates a truncated gz). `app.js` loaders (repo / URL / local server /
+  dropped file) go through `readRunlogText`; catalog filters accept `.jsonl.gz`; new size
+  column (compressed, with inflated size + format in the hover). Cache-busting `?v=` bumped.
+- **Replay:** `js/runlog-replay.js parseRunLog` normalizes records (needs
+  `js/runlog-format.js` loaded first — `arena_studio.html` does; a stale cache degrades to
+  "v2 echoes skipped" with a console warning, frames + runner events still replay);
+  `js/arena-studio-alt.js` replay picker lists `.jsonl.gz` and inflates the picked file.
+  `arena_replay_viewer.html` receives data over its protocol module — unchanged.
+  `js/studio-runlog-adapter.js` does not read files — unchanged.
+- **Tests:** `tests/test-runlog-format.js` (new, in `pixi run test`); `tests/test-runlog-replay.js`
+  v2 case asserting identical samples/arenaFrames/events vs the equivalent v1;
+  `dashboard/data-browser/tests/test-analysis.js` re-reads the P3 fixture as v2 + gz and
+  asserts identical frames, arena_command objects, preference indices, LED epochs and page
+  CSV rows, plus metadata from a gz prefix; `dashboard/data-browser/tests/corpus-v2-parity.js`
+  runs that comparison over a whole clone (result in PR 3's description).
diff --git a/js/arena-studio-alt.js b/js/arena-studio-alt.js
index b2aecf1..6634cdb 100644
--- a/js/arena-studio-alt.js
+++ b/js/arena-studio-alt.js
@@ -453,7 +453,7 @@
                                 (entry) =>
                                     entry &&
                                     entry.type === 'file' &&
-                                    /\.(jsonl|ndjson)$/i.test(entry.name)
+                                    /\.(jsonl|ndjson)(\.gz)?$/i.test(entry.name)
                             )
                             .sort((a, b) => b.name.localeCompare(a.name));
                         Studio.showPicker(
@@ -925,7 +925,7 @@
         replayPane.innerHTML =
             '<div class="alt-replay-grid">' +
             '<div class="alt-replay-file"><button type="button" data-pick="yaml">YAML</button><button type="button" class="alt-replay-repo" data-repo-pick="yaml" title="Choose a protocol directly from the configured course repo">Repo</button><span data-name="yaml">choose protocol…</span><input type="file" accept=".yaml,.yml" hidden></div>' +
-            '<div class="alt-replay-file"><button type="button" data-pick="log">JSONL</button><button type="button" class="alt-replay-repo" data-repo-pick="log" title="Choose a runlog directly from the configured course repo">Repo</button><span data-name="log">choose run log…</span><input type="file" accept=".jsonl,.ndjson,.json,.txt" hidden></div>' +
+            '<div class="alt-replay-file"><button type="button" data-pick="log">JSONL</button><button type="button" class="alt-replay-repo" data-repo-pick="log" title="Choose a runlog directly from the configured course repo">Repo</button><span data-name="log">choose run log…</span><input type="file" accept=".jsonl,.gz,.ndjson,.json,.txt" hidden></div>' +
             '<div class="alt-replay-file"><button type="button" data-pick="patterns">PATs</button><span data-name="patterns">optional pattern files…</span><input type="file" accept=".pat" multiple hidden></div>' +
             '</div>' +
             '<div class="alt-replay-options">' +
@@ -2252,10 +2252,12 @@
             // Popup creation must stay inside the user gesture. It waits for the
             // validated ready handshake while the two local files are parsed.
             if (replay.ui.viewerCheck && replay.ui.viewerCheck.checked) openViewer(true);
-            const [yamlText, logText] = await Promise.all([
-                replay.yamlFile.text(),
-                replay.logFile.text()
-            ]);
+            // The run log may be a gzipped `.jsonl.gz` (Studio v0.72+): inflate on the
+            // gzip magic via the shared format module; plain text passes through.
+            const readLog = window.RunlogFormat
+                ? window.RunlogFormat.readRunlogText(replay.logFile)
+                : replay.logFile.text();
+            const [yamlText, logText] = await Promise.all([replay.yamlFile.text(), readLog]);
             if (token !== replay.loadToken || !Studio.replayActive) return;
             const yamlHash = await sha256(yamlText);
             if (token !== replay.loadToken || !Studio.replayActive) return;
diff --git a/js/runlog-format.js b/js/runlog-format.js
new file mode 100644
index 0000000..ff3845e
--- /dev/null
+++ b/js/runlog-format.js
@@ -0,0 +1,481 @@
+/**
+ * runlog-format.js — ONE place that knows how a run-log FILE is encoded, shared by
+ * every reader: the analysis dashboard (dashboard/data-browser, via an exact
+ * vendored copy), the replay parser (js/runlog-replay.js) and the Alt Studio
+ * replay picker (js/arena-studio-alt.js). Plan: docs/development/runlog-behavior-v2-plan.md.
+ *
+ * Two orthogonal encodings, both lossless:
+ *   1. gzip — since Studio v0.72 run logs are committed as `<name>.jsonl.gz`.
+ *      Detect by the magic bytes (1f 8b), never by name alone: `inflateIfGzip`,
+ *      `readRunlogText` (any of string / bytes / ArrayBuffer / Blob|File → text),
+ *      `readRunlogPrefixText` (a truncated prefix of a .gz still inflates to the
+ *      run_metadata line near the top — the catalog reads 64 KB prefixes).
+ *   2. line format — `behavior_v1` (pre-2026-09) vs `behavior_v2` (bridge ≥ 3.0):
+ *      identical frame arrays [ms,fc,idx,ft,x,y,hd]; v2 writes each browser
+ *      `arena_command` echo as the compact array
+ *        ["a", t_off, dt, hex, status, rx_off(, error)]
+ *      with ms offsets from the v2 frame_schema line's `t0`. `expandV2Line`
+ *      rebuilds the EXACT v1 object (key order type,event,t,dt,len,head,status,
+ *      echo,ok,error,dir,rx_ms) so every existing consumer keeps working; readers
+ *      call `createNormalizer()` and pass each parsed line through `normalize()`.
+ *      Timeout rule (verified on the course corpus, bridge.py mirrors it): when
+ *      `status` is null then `echo` and `ok` are null too — NOT false.
+ *      A v2 file may still carry a verbatim v1 `arena_command` object (an echo the
+ *      bridge could not compact, e.g. a bulk command with a truncated ` …` head)
+ *      and a converted legacy file may carry `"cols": null` in its schema.
+ *
+ * `compactV1Line` / `convertV1ToV2Text` / `convertV2ToV1Text` are the JS mirror of
+ * the bridge's converter — used by the tests and the corpus parity script so the
+ * readers can be exercised on v2 data generated from every existing v1 log.
+ *
+ * LOADING: classic <script src> (window-global `RunlogFormat` + CommonJS), no ES
+ * `export` — same rule as arena-session.js (see CLAUDE.md). Load it BEFORE
+ * js/runlog-replay.js. The dashboard's copy at dashboard/data-browser/vendor/ must
+ * stay byte-identical (tests/test-runlog-format.js enforces it).
+ */
+(function (global) {
+    'use strict';
+
+    const GZIP_MAGIC_0 = 0x1f;
+    const GZIP_MAGIC_1 = 0x8b;
+    const ARENA_TAG = 'a';
+    const ARENA_DIR = 'browser→bridge';
+    const BEHAVIOR_V2_ARENA_COLS = ['t_off', 'dt', 'hex', 'status', 'rx_off'];
+    const ARENA_COMMAND_KEYS = [
+        'type',
+        'event',
+        't',
+        'dt',
+        'len',
+        'head',
+        'status',
+        'echo',
+        'ok',
+        'error',
+        'dir',
+        'rx_ms'
+    ];
+    const RUNLOG_NAME_RE = /\.(jsonl|ndjson|json)(\.gz)?$/i;
+
+    // ── bytes / gzip ────────────────────────────────────────────────────────────
+    function toBytes(input) {
+        if (input instanceof Uint8Array) return input;
+        if (typeof ArrayBuffer !== 'undefined' && input instanceof ArrayBuffer)
+            return new Uint8Array(input);
+        if (input && ArrayBuffer.isView && ArrayBuffer.isView(input))
+            return new Uint8Array(input.buffer, input.byteOffset, input.byteLength);
+        if (typeof input === 'string') return new TextEncoder().encode(input);
+        throw new Error(
+            'RunlogFormat: cannot read bytes from ' + Object.prototype.toString.call(input)
+        );
+    }
+
+    function isGzip(bytes) {
+        let u8;
+        try {
+            u8 = toBytes(bytes);
+        } catch (_) {
+            return false;
+        }
+        return u8.length >= 2 && u8[0] === GZIP_MAGIC_0 && u8[1] === GZIP_MAGIC_1;
+    }
+
+    function isRunlogName(name) {
+        return RUNLOG_NAME_RE.test(String(name || ''));
+    }
+
+    /** `run.jsonl.gz` → `run.jsonl` (filename parsers key on the .jsonl stem). */
+    function stripGz(name) {
+        return String(name || '').replace(/\.gz$/i, '');
+    }
+
+    function concatBytes(chunks) {
+        let n = 0;
+        for (const c of chunks) n += c.length;
+        const out = new Uint8Array(n);
+        let at = 0;
+        for (const c of chunks) {
+            out.set(c, at);
+            at += c.length;
+        }
+        return out;
+    }
+
+    /**
+     * gunzip. `tolerateTruncation` returns what could be inflated from a cut-off
+     * stream (a file prefix) instead of throwing at the missing trailer.
+     */
+    async function inflate(bytes, tolerateTruncation) {
+        const u8 = toBytes(bytes);
+        if (typeof DecompressionStream !== 'undefined') {
+            const stream = new Blob([u8]).stream().pipeThrough(new DecompressionStream('gzip'));
+            const reader = stream.getReader();
+            const chunks = [];
+            try {
+                for (;;) {
+                    const part = await reader.read();
+                    if (part.done) break;
+                    chunks.push(part.value);
+                }
+            } catch (err) {
+                if (!tolerateTruncation) throw err;
+            }
+            return concatBytes(chunks);
+        }
+        if (typeof require === 'function') {
+            const zlib = require('zlib');
+            const buf = zlib.gunzipSync(
+                Buffer.from(u8.buffer, u8.byteOffset, u8.byteLength),
+                tolerateTruncation ? { finishFlush: zlib.constants.Z_SYNC_FLUSH } : undefined
+            );
+            return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+        }
+        throw new Error('RunlogFormat: no gzip support (DecompressionStream missing)');
+    }
+
+    /** Bytes in → bytes out, inflated when they start with the gzip magic. */
+    async function inflateIfGzip(bytes) {
+        const u8 = toBytes(bytes);
+        return isGzip(u8) ? inflate(u8, false) : u8;
+    }
+
+    function decodeText(u8) {
+        return new TextDecoder('utf-8').decode(u8);
+    }
+
+    /**
+     * The one entry point for loaders: string (returned as-is), Uint8Array /
+     * ArrayBuffer / typed array, or a Blob|File (anything with arrayBuffer()) →
+     * the log TEXT, inflated when gzipped.
+     */
+    async function readRunlogText(input) {
+        if (typeof input === 'string') return input;
+        if (input && typeof input.arrayBuffer === 'function' && !(input instanceof Uint8Array)) {
+            input = await input.arrayBuffer();
+        }
+        return decodeText(await inflateIfGzip(toBytes(input)));
+    }
+
+    /**
+     * A possibly TRUNCATED prefix of a file (the catalog's 64 KB metadata read) →
+     * as much text as can be recovered; gzip prefixes inflate partially.
+     */
+    async function readRunlogPrefixText(input) {
+        if (typeof input === 'string') return input;
+        const u8 = toBytes(input);
+        if (!isGzip(u8)) return decodeText(u8);
+        try {
+            return decodeText(await inflate(u8, true));
+        } catch (_) {
+            return '';
+        }
+    }
+
+    // ── behavior_v2 line format ─────────────────────────────────────────────────
+    function isInt(v) {
+        return Number.isInteger(v);
+    }
+
+    function isArenaArray(value) {
+        return (
+            Array.isArray(value) &&
+            (value.length === 6 || value.length === 7) &&
+            value[0] === ARENA_TAG
+        );
+    }
+
+    function isSchemaRecord(rec) {
+        return (
+            !!rec && !Array.isArray(rec) && typeof rec === 'object' && rec.type === 'frame_schema'
+        );
+    }
+
+    function hexBytes(hex) {
+        if (typeof hex !== 'string' || hex.length % 2 || !/^[0-9a-f]*$/.test(hex)) return null;
+        const parts = [];
+        for (let i = 0; i < hex.length; i += 2) parts.push(hex.slice(i, i + 2));
+        return parts;
+    }
+
+    /**
+     * ["a", t_off, dt, hex, status, rx_off(, error)] → the exact v1 arena_command
+     * object. `schema` is the v2 frame_schema record (uses its `t0`) or a number.
+     * Throws on a malformed array.
+     */
+    function expandV2Line(arr, schema) {
+        if (!isArenaArray(arr)) throw new Error('RunlogFormat: not a compact arena array');
+        const t0 = typeof schema === 'number' ? schema : schema && schema.t0;
+        const tOff = arr[1];
+        const dt = arr[2];
+        const hex = arr[3];
+        const status = arr[4];
+        const rxOff = arr[5];
+        const error = arr.length === 7 ? arr[6] : null;
+        if (!isInt(t0) || !isInt(tOff) || !isInt(rxOff))
+            throw new Error('RunlogFormat: t0/t_off/rx_off must be integers');
+        if (typeof dt !== 'number') throw new Error('RunlogFormat: dt must be a number');
+        const parts = hexBytes(hex);
+        if (!parts) throw new Error('RunlogFormat: malformed hex ' + JSON.stringify(hex));
+        if (status !== null && !isInt(status))
+            throw new Error('RunlogFormat: status must be int or null');
+        if (status !== null && parts.length < 2)
+            throw new Error('RunlogFormat: status present but no command byte');
+        if (error !== null && typeof error !== 'string')
+            throw new Error('RunlogFormat: error must be a string');
+        return {
+            type: 'log',
+            event: 'arena_command',
+            t: t0 + tOff,
+            dt: dt,
+            len: parts.length,
+            head: parts.join(' '),
+            status: status,
+            echo: status === null ? null : parseInt(parts[1], 16),
+            ok: status === null ? null : status === 0,
+            error: error,
+            dir: ARENA_DIR,
+            rx_ms: t0 + rxOff
+        };
+    }
+
+    /**
+     * v1 arena_command object → compact array, or null when the object does not fit
+     * the fixed shape (then it stays verbatim). Mirrors bridge.py's invariants.
+     */
+    function compactV1Line(obj, t0) {
+        if (!obj || Array.isArray(obj) || typeof obj !== 'object') return null;
+        if (obj.type !== 'log' || obj.event !== 'arena_command') return null;
+        const keys = Object.keys(obj);
+        if (keys.length !== ARENA_COMMAND_KEYS.length) return null;
+        for (const k of ARENA_COMMAND_KEYS) if (!(k in obj)) return null;
+        if (obj.dir !== ARENA_DIR) return null;
+        if (!isInt(t0) || !isInt(obj.t) || !isInt(obj.rx_ms)) return null;
+        if (typeof obj.dt !== 'number') return null;
+        if (typeof obj.head !== 'string' || !obj.head) return null;
+        const parts = obj.head.split(' ');
+        if (!parts.every((p) => /^[0-9a-f]{2}$/.test(p))) return null;
+        if (obj.len !== parts.length) return null;
+        if (obj.status === null) {
+            if (obj.echo !== null || obj.ok !== null) return null;
+        } else {
+            if (!isInt(obj.status)) return null;
+            if (parts.length < 2 || obj.echo !== parseInt(parts[1], 16)) return null;
+            if (typeof obj.ok !== 'boolean' || obj.ok !== (obj.status === 0)) return null;
+        }
+        if (obj.error !== null && typeof obj.error !== 'string') return null;
+        const arr = [ARENA_TAG, obj.t - t0, obj.dt, parts.join(''), obj.status, obj.rx_ms - t0];
+        if (obj.error !== null) arr.push(obj.error);
+        return arr;
+    }
+
+    /**
+     * 'behavior_v2' | 'behavior_v1' | 'full' | 'legacy' | 'unknown' from either the
+     * log text (first `maxLines` lines) or an array of parsed records. The schema
+     * line decides; without one, "a" arrays mean v2, fictrac_frame objects with the
+     * 25-column array mean `full`, other content is a pre-#140 log.
+     */
+    function detectFormat(input, maxLines) {
+        let records = input;
+        if (typeof input === 'string') {
+            records = [];
+            const lines = input.split(/\r?\n/);
+            const n = Math.min(lines.length, maxLines || 200);
+            for (let i = 0; i < n; i++) {
+                const ln = lines[i].trim();
+                if (!ln) continue;
+                try {
+                    records.push(JSON.parse(ln));
+                } catch (_) {
+                    /* torn line */
+                }
+            }
+        }
+        if (!Array.isArray(records) || !records.length) return 'unknown';
+        let sawFull = false;
+        let sawAny = false;
+        for (const o of records) {
+            sawAny = true;
+            if (isSchemaRecord(o)) return String(o.level || 'behavior_v1');
+            if (isArenaArray(o)) return 'behavior_v2';
+            if (
+                o &&
+                typeof o === 'object' &&
+                o.type === 'fictrac_frame' &&
+                Array.isArray(o.fictrac)
+            )
+                sawFull = true;
+        }
+        if (!sawAny) return 'unknown';
+        return sawFull ? 'full' : 'legacy';
+    }
+
+    /**
+     * Per-file state machine for readers: feed every parsed line through
+     * `normalize(rec)`; it remembers the frame_schema (v1 or v2), expands compact
+     * arena arrays to v1 objects, and passes everything else through untouched.
+     * `format` reports what the file turned out to be once enough lines went by.
+     */
+    function createNormalizer() {
+        const state = {
+            schema: null,
+            level: null,
+            orphanArena: 0,
+            sawFull: false,
+            sawAny: false
+        };
+        return {
+            get schema() {
+                return state.schema;
+            },
+            get level() {
+                return state.level;
+            },
+            get orphanArena() {
+                return state.orphanArena;
+            },
+            get format() {
+                if (state.level) return state.level;
+                if (!state.sawAny) return 'unknown';
+                return state.sawFull ? 'full' : 'legacy';
+            },
+            normalize(rec) {
+                state.sawAny = true;
+                if (isSchemaRecord(rec)) {
+                    state.schema = rec;
+                    state.level = String(rec.level || 'behavior_v1');
+                    return rec;
+                }
+                if (isArenaArray(rec)) {
+                    if (!state.schema || !isInt(state.schema.t0)) {
+                        // No t0 → the timestamps could not be trusted; leave the array
+                        // (readers ignore it as a frame row) and count it.
+                        state.orphanArena++;
+                        if (!state.level) state.level = 'behavior_v2';
+                        return rec;
+                    }
+                    if (!state.level) state.level = 'behavior_v2';
+                    return expandV2Line(rec, state.schema);
+                }
+                if (
+                    rec &&
+                    typeof rec === 'object' &&
+                    !Array.isArray(rec) &&
+                    rec.type === 'fictrac_frame' &&
+                    Array.isArray(rec.fictrac)
+                )
+                    state.sawFull = true;
+                return rec;
+            }
+        };
+    }
+
+    // ── whole-text converters (JS mirror of bridge.py --convert; tests + parity) ──
+    function parseLines(text) {
+        const out = [];
+        for (const line of String(text).split(/\r?\n/)) {
+            const ln = line.trim();
+            if (!ln) continue;
+            out.push(JSON.parse(ln));
+        }
+        return out;
+    }
+
+    function dumpLines(records) {
+        return records.map((r) => JSON.stringify(r)).join('\n') + (records.length ? '\n' : '');
+    }
+
+    function isSession(o) {
+        return o && typeof o === 'object' && !Array.isArray(o) && o.type === 'session';
+    }
+
+    /** behavior_v1 / legacy / full text → behavior_v2 text (lossless). */
+    function convertV1ToV2Text(text) {
+        const records = parseLines(text);
+        const schemaIdx = records.findIndex(isSchemaRecord);
+        let cols = null;
+        if (schemaIdx >= 0) {
+            const sch = records[schemaIdx];
+            if (sch.level === 'behavior_v2') throw new Error('already behavior_v2');
+            cols = sch.cols;
+        }
+        let t0 = null;
+        for (const o of records) {
+            if (isSession(o) && isInt(o.ms)) {
+                t0 = o.ms;
+                break;
+            }
+        }
+        if (t0 === null) {
+            const a = records.find(
+                (o) =>
+                    o && typeof o === 'object' && !Array.isArray(o) && o.event === 'arena_command'
+            );
+            t0 = a && isInt(a.t) ? a.t : 0;
+        }
+        const schema = {
+            type: 'frame_schema',
+            level: 'behavior_v2',
+            cols: cols,
+            arena_cols: BEHAVIOR_V2_ARENA_COLS.slice(),
+            t0: t0
+        };
+        const insertAt =
+            schemaIdx >= 0 ? schemaIdx : records.length && isSession(records[0]) ? 1 : 0;
+        const out = [];
+        records.forEach((o, i) => {
+            if (i === schemaIdx) {
+                out.push(schema);
+                return;
+            }
+            if (schemaIdx < 0 && i === insertAt) out.push(schema);
+            if (o && typeof o === 'object' && !Array.isArray(o) && o.event === 'arena_command') {
+                const arr = compactV1Line(o, t0);
+                out.push(arr || o);
+            } else out.push(o);
+        });
+        if (schemaIdx < 0 && insertAt >= records.length) out.push(schema);
+        return dumpLines(out);
+    }
+
+    /** behavior_v2 text → behavior_v1 text (the exact inverse). */
+    function convertV2ToV1Text(text) {
+        const records = parseLines(text);
+        const schemaIdx = records.findIndex(isSchemaRecord);
+        if (schemaIdx < 0 || records[schemaIdx].level !== 'behavior_v2')
+            throw new Error('not a behavior_v2 log');
+        const sch = records[schemaIdx];
+        const out = [];
+        records.forEach((o, i) => {
+            if (i === schemaIdx) {
+                if (sch.cols !== null && sch.cols !== undefined)
+                    out.push({ type: 'frame_schema', level: 'behavior_v1', cols: sch.cols });
+                return;
+            }
+            out.push(isArenaArray(o) ? expandV2Line(o, sch) : o);
+        });
+        return dumpLines(out);
+    }
+
+    const RunlogFormat = {
+        ARENA_TAG,
+        ARENA_DIR,
+        ARENA_COMMAND_KEYS,
+        BEHAVIOR_V2_ARENA_COLS,
+        isGzip,
+        isRunlogName,
+        stripGz,
+        inflateIfGzip,
+        readRunlogText,
+        readRunlogPrefixText,
+        isArenaArray,
+        expandV2Line,
+        compactV1Line,
+        detectFormat,
+        createNormalizer,
+        convertV1ToV2Text,
+        convertV2ToV1Text
+    };
+
+    if (typeof module !== 'undefined' && module.exports) module.exports = RunlogFormat;
+    global.RunlogFormat = RunlogFormat;
+})(typeof window !== 'undefined' ? window : globalThis);
diff --git a/js/runlog-replay.js b/js/runlog-replay.js
index 7f2d2b5..198ed3c 100644
--- a/js/runlog-replay.js
+++ b/js/runlog-replay.js
@@ -26,7 +26,15 @@
  * in the browser for the scope replay / dashboard.
  */
 (function (global) {
-    'use strict';
+    // Run-log FILE format helper (gzip + behavior_v2 compact arena echoes). Loaded
+    // before this file as a classic script (js/runlog-format.js); under a stale
+    // cache it may be missing — then v2 arena arrays are skipped (frames + runner
+    // events still replay) and a console warning says why.
+    const Fmt =
+        (typeof global !== 'undefined' && global.RunlogFormat) ||
+        (typeof require === 'function' ? require('./runlog-format.js') : null);
+    let warnedNoFmt = false;
+    ('use strict');
 
     // Keep in sync with fictrac-bridge/bridge.py FT_TS_NS_PER_MS.
     const FT_TS_NS_PER_MS = 1e6;
@@ -290,9 +298,22 @@
         let frameCols = null;
         let frameLevel = null;
         let fallbackMs = 0;
+        const normalizer = Fmt ? Fmt.createNormalizer() : null;
 
-        for (const o of records) {
-            // behavior_v1 positional row: [ms, fc, idx, ft, x, y, hd] (ft already ms)
+        for (let o of records) {
+            // behavior_v2: ["a", t_off, dt, hex, status, rx_off] → the v1 arena_command
+            // object (the frame_schema line with t0 precedes them in the file).
+            if (normalizer) o = normalizer.normalize(o);
+            else if (Array.isArray(o) && o[0] === 'a') {
+                if (!warnedNoFmt && typeof console !== 'undefined') {
+                    warnedNoFmt = true;
+                    console.warn(
+                        'runlog-replay: RunlogFormat not loaded — behavior_v2 arena echoes skipped'
+                    );
+                }
+                continue;
+            }
+            // behavior_v1/v2 positional row: [ms, fc, idx, ft, x, y, hd] (ft already ms)
             if (Array.isArray(o)) {
                 sawBehaviorV1 = true;
                 const col = (name, fallback) => {
diff --git a/pixi.toml b/pixi.toml
index 7e3557b..631beca 100644
--- a/pixi.toml
+++ b/pixi.toml
@@ -16,7 +16,7 @@ serve = "python -m http.server 8000 --bind 127.0.0.1"
 # The full test suite. yaml is vendored (js/vendor/yaml), so no package install.
 # The v3 suite pulls in ESM modules that `import 'yaml'`; --import maps that bare
 # specifier to the vendored copy (tests/vendor-yaml.register.mjs).
-test = "node tests/validate-arena-calculations.js && node tests/test-protocol-roundtrip.js && node --import ./tests/vendor-yaml.register.mjs tests/test-protocol-roundtrip-v3.js && node --import ./tests/vendor-yaml.register.mjs tests/test-runtime-controls.js && node tests/test-plugin-registry.js && node tests/test-arena-wire-g6.js && node tests/test-arena-link.js && node tests/test-arena-runner-g6.js && node tests/test-arena-session.js && node tests/test-fictrac-bridge-client.js && node tests/test-run-log.js && node tests/test-bin-classifier.js && node tests/test-pattern-set.js && node tests/test-pat-preview.js && node tests/test-studio-meta.js && node tests/test-studio-url-state.js && node tests/test-studio-runlog-adapter.js && node tests/test-studio-github.js && node tests/test-studio-canmutate.js && node tests/test-studio-protocols-index.js && node tests/test-g6-tall-rigs.js && node tests/test-arena-studio-alt.js && node tests/test-three-viewer-led-glow.js && node tests/test-three-viewer-preview-omissions.js && node tests/test-arena-replay-viewer-protocol.js && node tests/test-kinematics.js && node tests/test-runlog-replay.js && node tests/test-metadata-yaml.js && python tests/test-bridge-behavior.py"
+test = "node tests/validate-arena-calculations.js && node tests/test-protocol-roundtrip.js && node --import ./tests/vendor-yaml.register.mjs tests/test-protocol-roundtrip-v3.js && node --import ./tests/vendor-yaml.register.mjs tests/test-runtime-controls.js && node tests/test-plugin-registry.js && node tests/test-arena-wire-g6.js && node tests/test-arena-link.js && node tests/test-arena-runner-g6.js && node tests/test-arena-session.js && node tests/test-fictrac-bridge-client.js && node tests/test-run-log.js && node tests/test-bin-classifier.js && node tests/test-pattern-set.js && node tests/test-pat-preview.js && node tests/test-studio-meta.js && node tests/test-studio-url-state.js && node tests/test-studio-runlog-adapter.js && node tests/test-studio-github.js && node tests/test-studio-canmutate.js && node tests/test-studio-protocols-index.js && node tests/test-g6-tall-rigs.js && node tests/test-arena-studio-alt.js && node tests/test-three-viewer-led-glow.js && node tests/test-three-viewer-preview-omissions.js && node tests/test-arena-replay-viewer-protocol.js && node tests/test-kinematics.js && node tests/test-runlog-replay.js && node tests/test-runlog-format.js && node tests/test-metadata-yaml.js && python tests/test-bridge-behavior.py"
 format = "prettier --write \"**/*.js\""
 format-check = "prettier --check \"**/*.js\""
 
diff --git a/tests/test-runlog-format.js b/tests/test-runlog-format.js
new file mode 100644
index 0000000..7f1b9a5
--- /dev/null
+++ b/tests/test-runlog-format.js
@@ -0,0 +1,466 @@
+#!/usr/bin/env node
+/**
+ * Tests for js/runlog-format.js — the shared run-log FILE decoder every reader uses
+ * (dashboard, replay parser, Alt Studio replay): gzip detection + inflation
+ * (whole file and truncated prefix), behavior_v2 compact arena echo → exact v1
+ * object (incl. the timeout rule: status/echo/ok ALL null), the per-file
+ * normalizer, format detection, and the JS v1⇄v2 text converters used by the
+ * dashboard parity checks. Also enforces that the dashboard's vendored copy is
+ * byte-identical to js/runlog-format.js. Run: node tests/test-runlog-format.js
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const zlib = require('zlib');
+const F = require('../js/runlog-format.js');
+
+let total = 0;
+let failures = 0;
+function check(name, got, expected) {
+    total++;
+    const ok = JSON.stringify(got) === JSON.stringify(expected);
+    console.log(
+        `  ${ok ? 'PASS' : 'FAIL'}  ${name}${ok ? '' : ` — got ${JSON.stringify(got)}, expected ${JSON.stringify(expected)}`}`
+    );
+    if (!ok) failures++;
+}
+function checkBool(name, ok, info) {
+    total++;
+    console.log(`  ${ok ? 'PASS' : 'FAIL'}  ${name}${ok ? '' : ' — ' + (info || '')}`);
+    if (!ok) failures++;
+}
+function checkThrows(name, fn, re) {
+    total++;
+    try {
+        fn();
+        console.log(`  FAIL  ${name} — did not throw`);
+        failures++;
+    } catch (e) {
+        const ok = !re || re.test(e.message);
+        console.log(`  ${ok ? 'PASS' : 'FAIL'}  ${name} (threw ${e.message})`);
+        if (!ok) failures++;
+    }
+}
+
+// Real v1 line shapes (rig03-sr run rydc2tql, values trimmed) + the bridge's
+// Python-produced compact arrays for the same lines (tests/test-bridge-behavior.py).
+const T0 = 1788636439304;
+const A_OK = {
+    type: 'log',
+    event: 'arena_command',
+    t: 1788636442353,
+    dt: 7,
+    len: 4,
+    head: '03 70 2e 00',
+    status: 0,
+    echo: 112,
+    ok: true,
+    error: null,
+    dir: 'browser→bridge',
+    rx_ms: 1788636442360
+};
+const A_REJECT = {
+    ...A_OK,
+    t: 1788636442400,
+    dt: 4,
+    head: '03 70 31 00',
+    status: 1,
+    ok: false,
+    rx_ms: 1788636442405
+};
+const A_TIMEOUT = {
+    ...A_OK,
+    t: 1788636442467,
+    dt: 505,
+    head: '03 70 a6 00',
+    status: null,
+    echo: null,
+    ok: null,
+    error: 'response timeout after 500 ms (cmd 0x70)',
+    rx_ms: 1788636442972
+};
+const A_OK_ARR = ['a', 3049, 7, '03702e00', 0, 3056];
+const A_TIMEOUT_ARR = [
+    'a',
+    3163,
+    505,
+    '0370a600',
+    null,
+    3668,
+    'response timeout after 500 ms (cmd 0x70)'
+];
+const SCHEMA_V2 = {
+    type: 'frame_schema',
+    level: 'behavior_v2',
+    cols: ['ms', 'fc', 'idx', 'ft', 'x', 'y', 'hd'],
+    arena_cols: ['t_off', 'dt', 'hex', 'status', 'rx_off'],
+    t0: T0
+};
+const FRAME = [5, 9052, 39, 0.0, 1.42578, -3.19222, 1.21378];
+
+async function main() {
+    console.log('=== vendored copy is byte-identical ===');
+    const src = fs.readFileSync(path.join(__dirname, '..', 'js', 'runlog-format.js'), 'utf8');
+    const vendored = fs.readFileSync(
+        path.join(__dirname, '..', 'dashboard', 'data-browser', 'vendor', 'runlog-format.js'),
+        'utf8'
+    );
+    checkBool(
+        'dashboard/data-browser/vendor/runlog-format.js === js/runlog-format.js',
+        src === vendored,
+        'copy js/runlog-format.js over the vendored file'
+    );
+
+    console.log('=== isGzip / names ===');
+    const gz = zlib.gzipSync(Buffer.from('{"a":1}\n'));
+    check('gzip magic detected', F.isGzip(new Uint8Array(gz)), true);
+    check('Buffer accepted', F.isGzip(gz), true);
+    check('plain text not gzip', F.isGzip(new TextEncoder().encode('{"a":1}')), false);
+    check('empty not gzip', F.isGzip(new Uint8Array(0)), false);
+    check('garbage input not gzip', F.isGzip(null), false);
+    check('isRunlogName .jsonl', F.isRunlogName('run.jsonl'), true);
+    check('isRunlogName .jsonl.gz', F.isRunlogName('runlogs/rig1/run.jsonl.gz'), true);
+    check(
+        'isRunlogName .ndjson / .json',
+        [F.isRunlogName('x.ndjson'), F.isRunlogName('x.json')],
+        [true, true]
+    );
+    check(
+        'isRunlogName rejects .yaml / .gz alone',
+        [F.isRunlogName('p.yaml'), F.isRunlogName('x.gz')],
+        [false, false]
+    );
+    check('stripGz', F.stripGz('a__b__c__d.jsonl.gz'), 'a__b__c__d.jsonl');
+    check('stripGz no-op', F.stripGz('a.jsonl'), 'a.jsonl');
+
+    console.log('=== inflateIfGzip / readRunlogText ===');
+    const text = [JSON.stringify(SCHEMA_V2), JSON.stringify(FRAME), 'héllo ☃'].join('\n') + '\n';
+    const gzBytes = new Uint8Array(zlib.gzipSync(Buffer.from(text, 'utf8')));
+    check('inflateIfGzip inflates', new TextDecoder().decode(await F.inflateIfGzip(gzBytes)), text);
+    const plain = new TextEncoder().encode(text);
+    check(
+        'inflateIfGzip passes plain bytes through (same object)',
+        (await F.inflateIfGzip(plain)) === plain,
+        true
+    );
+    check('readRunlogText(string) as-is', await F.readRunlogText(text), text);
+    check('readRunlogText(gz Uint8Array)', await F.readRunlogText(gzBytes), text);
+    check(
+        'readRunlogText(gz ArrayBuffer)',
+        await F.readRunlogText(
+            gzBytes.buffer.slice(gzBytes.byteOffset, gzBytes.byteOffset + gzBytes.byteLength)
+        ),
+        text
+    );
+    check('readRunlogText(plain bytes)', await F.readRunlogText(plain), text);
+    check(
+        'readRunlogText(Blob of gz) — the File path',
+        await F.readRunlogText(new Blob([gzBytes])),
+        text
+    );
+    check('readRunlogText(Blob of text)', await F.readRunlogText(new Blob([text])), text);
+
+    console.log('=== readRunlogPrefixText: truncated gzip prefix still yields the head ===');
+    const big = [
+        JSON.stringify({ type: 'session', event: 'logging_started', file: 'x', ms: T0 }),
+        JSON.stringify(SCHEMA_V2),
+        JSON.stringify({
+            type: 'log',
+            event: 'run_metadata',
+            run_id: 'abc',
+            protocol_filename: 'p3.yaml',
+            dir: 'browser→bridge',
+            rx_ms: T0 + 1
+        })
+    ];
+    for (let i = 0; i < 20000; i++)
+        big.push(
+            JSON.stringify([
+                i * 8,
+                9000 + i,
+                i % 200,
+                i * 8.27,
+                Math.sin(i) * 3,
+                Math.cos(i) * 3,
+                (i % 628) / 100
+            ])
+        );
+    const bigText = big.join('\n') + '\n';
+    const bigGz = new Uint8Array(zlib.gzipSync(Buffer.from(bigText)));
+    checkBool(
+        'fixture gz is bigger than the 64 KB prefix',
+        bigGz.length > 65536,
+        String(bigGz.length)
+    );
+    const prefix = await F.readRunlogPrefixText(bigGz.subarray(0, 65536));
+    checkBool(
+        'truncated gz prefix inflates to a non-empty head',
+        prefix.length > 1000,
+        String(prefix.length)
+    );
+    checkBool(
+        '… containing the run_metadata line',
+        /"event":"run_metadata","run_id":"abc"/.test(prefix),
+        prefix.slice(0, 300)
+    );
+    checkBool(
+        '… starting with the session line',
+        prefix.startsWith('{"type":"session"'),
+        prefix.slice(0, 40)
+    );
+    check(
+        'plain prefix passes through',
+        await F.readRunlogPrefixText(new TextEncoder().encode('abc')),
+        'abc'
+    );
+    check('string prefix passes through', await F.readRunlogPrefixText('abc'), 'abc');
+
+    console.log('=== expandV2Line: exact v1 object ===');
+    check('ok line expands to the exact v1 object', F.expandV2Line(A_OK_ARR, SCHEMA_V2), A_OK);
+    check(
+        'key order = the v1 order',
+        Object.keys(F.expandV2Line(A_OK_ARR, SCHEMA_V2)),
+        F.ARENA_COMMAND_KEYS
+    );
+    check(
+        'timeout: status/echo/ok ALL null + error restored',
+        F.expandV2Line(A_TIMEOUT_ARR, SCHEMA_V2),
+        A_TIMEOUT
+    );
+    check('t0 as a number works too', F.expandV2Line(A_OK_ARR, T0).t, A_OK.t);
+    check(
+        'reject (status 1) → ok false, echo = cmd byte',
+        F.expandV2Line(['a', 3096, 4, '03703100', 1, 3101], T0),
+        A_REJECT
+    );
+    check(
+        'other command byte → echo 0xa0',
+        F.expandV2Line(['a', 1, 9, '03a00100', 0, 2], T0).echo,
+        160
+    );
+    check('isArenaArray: compact', F.isArenaArray(A_OK_ARR), true);
+    check('isArenaArray: frame row is NOT', F.isArenaArray(FRAME), false);
+    check('isArenaArray: wrong length', F.isArenaArray(['a', 1, 2]), false);
+    checkThrows('malformed hex throws', () => F.expandV2Line(['a', 1, 2, '037', 0, 3], T0), /hex/);
+    checkThrows(
+        'float offset throws',
+        () => F.expandV2Line(['a', 1.5, 2, '03700000', 0, 3], T0),
+        /integers/
+    );
+    checkThrows(
+        'missing t0 throws',
+        () => F.expandV2Line(A_OK_ARR, { type: 'frame_schema', level: 'behavior_v2' }),
+        /integers/
+    );
+    checkThrows(
+        'non-string error throws',
+        () => F.expandV2Line(['a', 1, 2, '03700000', null, 3, 5], T0),
+        /error/
+    );
+    checkThrows(
+        'status without command byte throws',
+        () => F.expandV2Line(['a', 1, 2, '03', 0, 3], T0),
+        /command byte/
+    );
+
+    console.log('=== compactV1Line: mirror of the bridge encoder ===');
+    check('ok line → Python-identical array', F.compactV1Line(A_OK, T0), A_OK_ARR);
+    check('timeout → 7 elements, Python-identical', F.compactV1Line(A_TIMEOUT, T0), A_TIMEOUT_ARR);
+    for (const [name, o] of [
+        ['ok', A_OK],
+        ['reject', A_REJECT],
+        ['timeout', A_TIMEOUT]
+    ]) {
+        check(`round trip ${name}`, F.expandV2Line(F.compactV1Line(o, T0), T0), o);
+    }
+    check('unknown extra key → null (verbatim)', F.compactV1Line({ ...A_OK, extra: 1 }, T0), null);
+    check('echo mismatch → null', F.compactV1Line({ ...A_OK, echo: 113 }, T0), null);
+    check('ok inconsistent → null', F.compactV1Line({ ...A_OK, ok: false }, T0), null);
+    check(
+        'truncated head (…) → null',
+        F.compactV1Line({ ...A_OK, head: '03 8d 00 01 02 03 04 05 …', len: 12 }, T0),
+        null
+    );
+    check('float t → null', F.compactV1Line({ ...A_OK, t: A_OK.t + 0.5 }, T0), null);
+    check(
+        'not an arena_command → null',
+        F.compactV1Line({ type: 'log', event: 'runner' }, T0),
+        null
+    );
+
+    console.log('=== createNormalizer ===');
+    {
+        const n = F.createNormalizer();
+        check('fresh: format unknown', n.format, 'unknown');
+        const s = { type: 'session', event: 'logging_started', ms: T0 };
+        check('session passes through', n.normalize(s), s);
+        check('after a non-schema line: legacy', n.format, 'legacy');
+        check(
+            'schema passes through + remembered',
+            [n.normalize(SCHEMA_V2), n.level],
+            [SCHEMA_V2, 'behavior_v2']
+        );
+        check('frame row untouched', n.normalize(FRAME), FRAME);
+        check('compact arena → v1 object', n.normalize(A_OK_ARR), A_OK);
+        check(
+            'verbatim v1 arena object in a v2 file passes through',
+            n.normalize(A_REJECT),
+            A_REJECT
+        );
+        check(
+            'runner object passes through',
+            n.normalize({ type: 'log', event: 'runner', phase: 'x' }),
+            { type: 'log', event: 'runner', phase: 'x' }
+        );
+        check('format = schema level', n.format, 'behavior_v2');
+        check('no orphans', n.orphanArena, 0);
+    }
+    {
+        const n = F.createNormalizer();
+        const v1s = { type: 'frame_schema', level: 'behavior_v1', cols: SCHEMA_V2.cols };
+        n.normalize(v1s);
+        check('v1 schema → level behavior_v1', n.format, 'behavior_v1');
+    }
+    {
+        const n = F.createNormalizer();
+        const r = n.normalize(A_OK_ARR); // no schema yet → cannot place in time
+        check('arena array before any schema is left as-is', r, A_OK_ARR);
+        check(
+            '… counted as orphan, format still v2',
+            [n.orphanArena, n.format],
+            [1, 'behavior_v2']
+        );
+    }
+    {
+        const n = F.createNormalizer();
+        n.normalize({
+            type: 'fictrac_frame',
+            seq: 1,
+            index: 2,
+            t: 3,
+            fictrac: new Array(25).fill(0)
+        });
+        check('full-level file detected', n.format, 'full');
+    }
+
+    console.log('=== detectFormat ===');
+    check(
+        'v2 text',
+        F.detectFormat(JSON.stringify(SCHEMA_V2) + '\n' + JSON.stringify(FRAME)),
+        'behavior_v2'
+    );
+    check(
+        'v1 text',
+        F.detectFormat('{"type":"frame_schema","level":"behavior_v1","cols":[]}\n'),
+        'behavior_v1'
+    );
+    check(
+        'v2 by arena array (no schema)',
+        F.detectFormat([{ type: 'session' }, A_OK_ARR]),
+        'behavior_v2'
+    );
+    check(
+        'full by fictrac array',
+        F.detectFormat([{ type: 'fictrac_frame', fictrac: new Array(25).fill(0) }]),
+        'full'
+    );
+    check(
+        'legacy',
+        F.detectFormat([{ type: 'session' }, { type: 'fictrac_frame', seq: 1 }]),
+        'legacy'
+    );
+    check('empty → unknown', F.detectFormat(''), 'unknown');
+    check(
+        'torn lines tolerated',
+        F.detectFormat('{"type":"frame_schema","level":"behavior_v2","cols":null,"t0":1}\n{"trunc'),
+        'behavior_v2'
+    );
+
+    console.log('=== convertV1ToV2Text / convertV2ToV1Text ===');
+    const v1Text =
+        [
+            JSON.stringify({ type: 'session', event: 'logging_started', file: 'x', ms: T0 }),
+            JSON.stringify({ type: 'frame_schema', level: 'behavior_v1', cols: SCHEMA_V2.cols }),
+            JSON.stringify({
+                type: 'log',
+                event: 'run_metadata',
+                run_id: 'r',
+                dir: 'browser→bridge',
+                rx_ms: T0 + 1
+            }),
+            JSON.stringify(FRAME),
+            JSON.stringify(A_OK),
+            JSON.stringify(A_TIMEOUT),
+            JSON.stringify({ ...A_OK, extra: 1 }),
+            JSON.stringify({ type: 'session', event: 'logging_stopped', ms: T0 + 500 })
+        ].join('\n') + '\n';
+    const v2Text = F.convertV1ToV2Text(v1Text);
+    const v2Lines = v2Text
+        .trim()
+        .split('\n')
+        .map((l) => JSON.parse(l));
+    check('same line count', v2Lines.length, 8);
+    check('schema replaced in place with t0 = session ms', v2Lines[1], SCHEMA_V2);
+    check(
+        'arena lines compacted (2), unknown-key one verbatim',
+        v2Lines.filter(F.isArenaArray).length,
+        2
+    );
+    check('verbatim line kept', v2Lines[6], { ...A_OK, extra: 1 });
+    check('frame row unchanged', v2Lines[3], FRAME);
+    check('detectFormat(v2Text)', F.detectFormat(v2Text), 'behavior_v2');
+    check('v2 → v1 restores the original text exactly', F.convertV2ToV1Text(v2Text), v1Text);
+    checkThrows('v1→v2 of a v2 text throws', () => F.convertV1ToV2Text(v2Text), /already/);
+    checkThrows(
+        'v2→v1 of a v1 text throws',
+        () => F.convertV2ToV1Text(v1Text),
+        /not a behavior_v2/
+    );
+    // legacy file (no schema): schema with cols null inserted after the session line, dropped on the way back
+    const legacyText =
+        [
+            JSON.stringify({ type: 'session', event: 'logging_started', file: 'x', ms: T0 }),
+            JSON.stringify({
+                type: 'fictrac_frame',
+                seq: 1,
+                index: 2,
+                t: T0 + 5,
+                fictrac: new Array(25).fill(0)
+            }),
+            JSON.stringify(A_OK)
+        ].join('\n') + '\n';
+    const legacyV2 = F.convertV1ToV2Text(legacyText)
+        .trim()
+        .split('\n')
+        .map((l) => JSON.parse(l));
+    check(
+        'legacy: schema inserted at line 2 with cols null',
+        [legacyV2[1].type, legacyV2[1].cols, legacyV2[1].t0],
+        ['frame_schema', null, T0]
+    );
+    check('legacy: arena compacted', F.isArenaArray(legacyV2[3]), true);
+    check(
+        'legacy round trip exact',
+        F.convertV2ToV1Text(F.convertV1ToV2Text(legacyText)),
+        legacyText
+    );
+    // and through gzip + the normalizer, as a reader would see it
+    const readBack = await F.readRunlogText(new Uint8Array(zlib.gzipSync(Buffer.from(v2Text))));
+    const n = F.createNormalizer();
+    const seen = readBack
+        .trim()
+        .split('\n')
+        .map((l) => n.normalize(JSON.parse(l)));
+    check('gz → text → normalizer yields the v1 objects', [seen[4], seen[5]], [A_OK, A_TIMEOUT]);
+    check('… and the v1 schema is the v2 one (readers key on cols)', seen[1].cols, SCHEMA_V2.cols);
+
+    console.log('\n=== Summary ===');
+    console.log(`${total - failures} / ${total} checks passed`);
+    process.exit(failures ? 1 : 0);
+}
+
+main().catch((e) => {
+    console.error('test crashed:', e);
+    process.exit(1);
+});
diff --git a/tests/test-runlog-replay.js b/tests/test-runlog-replay.js
index 26cfb83..8d2a9e0 100644
--- a/tests/test-runlog-replay.js
+++ b/tests/test-runlog-replay.js
@@ -355,6 +355,104 @@ check(
     null
 );
 
+// ── parseRunLog: behavior_v2 log (compact arena echoes) ─────────────────────
+console.log('=== parseRunLog: behavior_v2 log ===');
+{
+    const T0 = 100000;
+    const v2Log = [
+        JSON.stringify({ type: 'session', event: 'logging_started', file: 'x.jsonl', ms: T0 }),
+        JSON.stringify({
+            type: 'frame_schema',
+            level: 'behavior_v2',
+            cols: ['ms', 'fc', 'idx', 'ft', 'x', 'y', 'hd'],
+            arena_cols: ['t_off', 'dt', 'hex', 'status', 'rx_off'],
+            t0: T0
+        }),
+        JSON.stringify({
+            type: 'log',
+            event: 'run_metadata',
+            run_id: 'run-v2',
+            protocol_filename: 'closed_loop.yaml',
+            log_format: 'behavior_v2',
+            rx_ms: T0 + 1,
+            dir: 'browser→bridge'
+        }),
+        JSON.stringify([0, 100, 5, 0.0, 0.0, 0.0, 0.0]),
+        JSON.stringify(['a', 60, 1, '03700201', 0, 61]), // SET_FRAME_POSITION(258) ok
+        JSON.stringify([8, 101, 5, 8.272, 0.01, 0.0, 0.02]),
+        JSON.stringify(['a', 70, 3, '0370ff00', 1, 73]), // rejected (status 1) → not a frame
+        JSON.stringify([
+            'a',
+            80,
+            505,
+            '03700300',
+            null,
+            585,
+            'response timeout after 500 ms (cmd 0x70)'
+        ]),
+        JSON.stringify({
+            type: 'log',
+            event: 'runner',
+            phase: 'led-activation',
+            condition: 'closed_loop_led',
+            index: 50,
+            on: true,
+            ledPercent: 20,
+            rx_ms: T0 + 40
+        })
+    ].join('\n');
+    const pv2 = R.parseRunLog(v2Log);
+    check('format detected behavior_v2', pv2.format, 'behavior_v2');
+    check('v2 metadata run id', pv2.metadata.run_id, 'run-v2');
+    check('v2 frame rows parsed like v1', pv2.samples.length, 2);
+    approx('v2 ft passthrough', pv2.samples[1].ft, 8.272, 1e-9);
+    check('only the OK compact echo becomes a frame (reject + timeout dropped)', pv2.arenaFrames, [
+        { ms: 60, index: 258, source: 'arena_command' }
+    ]);
+    check('runner event rebased to the session clock', pv2.events[0].ms, 40);
+    // Identical result to the equivalent v1 log.
+    const v1Equivalent = R.parseRunLog(
+        v2Log
+            .split('\n')
+            .map((ln) => {
+                const o = JSON.parse(ln);
+                if (Array.isArray(o) && o[0] === 'a') {
+                    const parts = o[3].match(/../g);
+                    return JSON.stringify({
+                        type: 'log',
+                        event: 'arena_command',
+                        t: T0 + o[1],
+                        dt: o[2],
+                        len: parts.length,
+                        head: parts.join(' '),
+                        status: o[4],
+                        echo: o[4] === null ? null : parseInt(parts[1], 16),
+                        ok: o[4] === null ? null : o[4] === 0,
+                        error: o.length === 7 ? o[6] : null,
+                        dir: 'browser→bridge',
+                        rx_ms: T0 + o[5]
+                    });
+                }
+                if (o.type === 'frame_schema')
+                    return JSON.stringify({
+                        type: 'frame_schema',
+                        level: 'behavior_v1',
+                        cols: o.cols
+                    });
+                return ln;
+            })
+            .join('\n')
+    );
+    check('v2 arenaFrames == v1 arenaFrames', pv2.arenaFrames, v1Equivalent.arenaFrames);
+    check('v2 samples == v1 samples', pv2.samples, v1Equivalent.samples);
+    check('v2 events == v1 events', pv2.events, v1Equivalent.events);
+    check(
+        'v2 bounds == v1 bounds',
+        [pv2.startMs, pv2.endMs],
+        [v1Equivalent.startMs, v1Equivalent.endMs]
+    );
+}
+
 // Canonical runlog.json uses t_offset_s rather than bridge rx_ms.
 const canonical = R.parseRunLog(
     JSON.stringify(

From 9479340e784526c3512d83e2bc9852a9ab96359f Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Mon, 7 Sep 2026 19:09:00 -0400
Subject: [PATCH 2/2] fix(readers): run-log name filter must not match
 runlogs/<folder>/index.json

isRunlogName accepted bare .json, and #188 applies it to directory listings
(data-repo browse, URL index) and the corpus parity script. Since #187 every
runlogs/<folder>/ carries an index.json catalog, so the dashboard would list
each folder's index as a run and the corpus gate failed on all 12 of them
(174/174 logs themselves pass). Narrow the shared filter to .jsonl|.ndjson
(+ .gz); the drop handler keeps accepting a user-dropped .json to match the
file input's accept list. Vendored copy synced; test updated.

Corpus gates on this branch (course clone @ 37d003e, 174 logs):
  scripts/runlog-v2-corpus.py             174/174 ok
  dashboard/data-browser/tests/corpus-v2-parity.js  174/174 ok (was 174 ok + 12 index.json FAIL)

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 dashboard/data-browser/app.js                  |  6 ++++--
 dashboard/data-browser/vendor/runlog-format.js |  7 ++++++-
 docs/development/runlog-behavior-v2-plan.md    |  2 +-
 js/runlog-format.js                            |  7 ++++++-
 tests/test-runlog-format.js                    | 11 ++++++++---
 5 files changed, 25 insertions(+), 8 deletions(-)

diff --git a/dashboard/data-browser/app.js b/dashboard/data-browser/app.js
index 97823d6..01f5c65 100644
--- a/dashboard/data-browser/app.js
+++ b/dashboard/data-browser/app.js
@@ -1998,8 +1998,10 @@ els.scopeAutoY.addEventListener('click', () => {
 document.body.addEventListener('dragover', (event) => event.preventDefault());
 document.body.addEventListener('drop', async (event) => {
     event.preventDefault();
-    const files = [...((event.dataTransfer && event.dataTransfer.files) || [])].filter((file) =>
-        F.isRunlogName(file.name)
+    // Same acceptance as the file input (`accept=".jsonl,.ndjson,.json,…"`): a
+    // dropped `.json` is a user's choice; directory listings use F.isRunlogName alone.
+    const files = [...((event.dataTransfer && event.dataTransfer.files) || [])].filter(
+        (file) => F.isRunlogName(file.name) || /\.json$/i.test(file.name)
     );
     if (!files.length) return;
     try {
diff --git a/dashboard/data-browser/vendor/runlog-format.js b/dashboard/data-browser/vendor/runlog-format.js
index ff3845e..3d8b3ef 100644
--- a/dashboard/data-browser/vendor/runlog-format.js
+++ b/dashboard/data-browser/vendor/runlog-format.js
@@ -55,7 +55,12 @@
         'dir',
         'rx_ms'
     ];
-    const RUNLOG_NAME_RE = /\.(jsonl|ndjson|json)(\.gz)?$/i;
+    // Run-log FILE names as they appear in directory listings (data repo, local
+    // folder, URL index). Deliberately NOT bare `.json`: every runlogs/<folder>/
+    // carries an `index.json` catalog (build-runlog-index.py) that must never be
+    // parsed as a run. User-picked files may still be `.json` (see the dashboard's
+    // file input `accept=`); that path checks the name itself.
+    const RUNLOG_NAME_RE = /\.(jsonl|ndjson)(\.gz)?$/i;
 
     // ── bytes / gzip ────────────────────────────────────────────────────────────
     function toBytes(input) {
diff --git a/docs/development/runlog-behavior-v2-plan.md b/docs/development/runlog-behavior-v2-plan.md
index 0832569..0be9200 100644
--- a/docs/development/runlog-behavior-v2-plan.md
+++ b/docs/development/runlog-behavior-v2-plan.md
@@ -260,7 +260,7 @@ Studio (PR 2) and reader (PR 3) work must build on:
 
 - **`js/runlog-format.js`** (classic dual-export; vendored byte-identical at
   `dashboard/data-browser/vendor/runlog-format.js`, enforced by `tests/test-runlog-format.js`):
-  `isGzip`, `isRunlogName` (`.jsonl|.ndjson|.json` with optional `.gz`), `stripGz`,
+  `isGzip`, `isRunlogName` (`.jsonl|.ndjson` with optional `.gz` — never bare `.json`, so `runlogs/<folder>/index.json` is not a run), `stripGz`,
   `inflateIfGzip`, `readRunlogText(string|bytes|ArrayBuffer|Blob)`, `readRunlogPrefixText`
   (truncation-tolerant gunzip for the catalog's 64 KB metadata reads), `isArenaArray`,
   `expandV2Line` (exact v1 object; timeout ⇒ status/echo/ok all null), `compactV1Line`,
diff --git a/js/runlog-format.js b/js/runlog-format.js
index ff3845e..3d8b3ef 100644
--- a/js/runlog-format.js
+++ b/js/runlog-format.js
@@ -55,7 +55,12 @@
         'dir',
         'rx_ms'
     ];
-    const RUNLOG_NAME_RE = /\.(jsonl|ndjson|json)(\.gz)?$/i;
+    // Run-log FILE names as they appear in directory listings (data repo, local
+    // folder, URL index). Deliberately NOT bare `.json`: every runlogs/<folder>/
+    // carries an `index.json` catalog (build-runlog-index.py) that must never be
+    // parsed as a run. User-picked files may still be `.json` (see the dashboard's
+    // file input `accept=`); that path checks the name itself.
+    const RUNLOG_NAME_RE = /\.(jsonl|ndjson)(\.gz)?$/i;
 
     // ── bytes / gzip ────────────────────────────────────────────────────────────
     function toBytes(input) {
diff --git a/tests/test-runlog-format.js b/tests/test-runlog-format.js
index 7f1b9a5..8743d68 100644
--- a/tests/test-runlog-format.js
+++ b/tests/test-runlog-format.js
@@ -121,10 +121,15 @@ async function main() {
     check('garbage input not gzip', F.isGzip(null), false);
     check('isRunlogName .jsonl', F.isRunlogName('run.jsonl'), true);
     check('isRunlogName .jsonl.gz', F.isRunlogName('runlogs/rig1/run.jsonl.gz'), true);
+    check('isRunlogName .ndjson', F.isRunlogName('x.ndjson'), true);
     check(
-        'isRunlogName .ndjson / .json',
-        [F.isRunlogName('x.ndjson'), F.isRunlogName('x.json')],
-        [true, true]
+        'isRunlogName rejects bare .json — runlogs/<folder>/index.json is a catalog, not a run',
+        [
+            F.isRunlogName('x.json'),
+            F.isRunlogName('runlogs/rig1/index.json'),
+            F.isRunlogName('index.json.gz')
+        ],
+        [false, false, false]
     );
     check(
         'isRunlogName rejects .yaml / .gz alone',