From 7fe7d8c4c4afd98b222ab6262e4e264b889999ad Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 6 Sep 2026 17:57:18 -0400
Subject: [PATCH] =?UTF-8?q?feat(studio):=20gzip=20run-log=20commits=20(.js?=
 =?UTF-8?q?onl.gz),=20behavior=5Fv2=20default,=20bridge=20log-level=20ack?=
 =?UTF-8?q?=20(PR=202=20of=20runlog-behavior-v2-plan)=20=E2=80=94=20Studio?=
 =?UTF-8?q?=20v0.72?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Studio side of docs/development/runlog-behavior-v2-plan.md (Part 1 §5 + Part 2).
Stacks on PR #183 (bridge). Readers (dashboard / replay viewer) are PR 3 — until
it lands, .jsonl.gz files need gunzip or `bridge.py --convert`.

- js/fictrac-bridge-client.js: LOG_LEVELS [behavior_v2, behavior_v1, full]
  (v2 default); handles hello_ack (bridgeInfo, bridgeSupportsLevel) and
  log_control_ack (ackedLogLevel, cleared on every setLogging and on close);
  new 'loglevel' event + an err log line when the bridge cannot write the
  requested level; waitForLogLevelAck(ms) → acked level or null (old bridge).
- js/studio-github.js: gzipBytes (CompressionStream) + isGzip; Git Database
  builders (reqCreateBlob/reqGetCommit/reqCreateTree/reqCreateCommit/
  reqUpdateRef, allowlisted, fast-forward only); directCommitLarge (7-call
  blob→tree→commit→ref sequence, per-step errors); commitFile routes by size
  (LARGE_FILE_BYTES = 30 MiB) and reports via + bytes.
- arena_studio.html v0.72: File ▾ → Run logging offers behavior_v2 (default) /
  behavior_v1 (legacy) / full; Console mirror follows the bridge's ack (⚠ on
  mismatch); run start awaits the ack ≤ 800 ms, names the level in the banner
  + transcript and warns "bridge too old for behavior_v2 — logging behavior_v1"
  (or "did not confirm" for a pre-3.0 bridge); run_metadata gains log_format;
  commitRunLog gzips the export → runlogs/<bench>/<name>.jsonl.gz via
  GH.commitFile (raw .jsonl fallback without CompressionStream) and shows
  raw → gz size + the path used.
- Tests: test-fictrac-bridge-client.js 42 → 71 checks (levels, hello_ack,
  log_control_ack, mismatch, waiters, close reset); test-studio-github.js
  118 → 160 (gzip round trip via zlib, git-db builders + token containment,
  directCommitLarge sequence + failure step, commitFile routing, Studio wiring
  assertions on the HTML).
- Docs: release notes v0.72, cshl-pipeline-test-plan size-limits, CLAUDE.md
  Studio rule, plan doc status + PR 2 notes (merge with/after PR 3).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 CLAUDE.md                                     |  11 +
 arena_studio.html                             | 111 +++++--
 .../development/arena-studio-release-notes.md |  23 ++
 docs/development/cshl-pipeline-test-plan.md   |  14 +-
 docs/development/runlog-behavior-v2-plan.md   |  38 ++-
 js/fictrac-bridge-client.js                   | 172 +++++++++-
 js/studio-github.js                           | 185 ++++++++++-
 tests/test-fictrac-bridge-client.js           | 160 ++++++++-
 tests/test-studio-github.js                   | 307 ++++++++++++++++++
 9 files changed, 973 insertions(+), 48 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index f00ce17..2614fb4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -292,6 +292,17 @@ fix flows to every page automatically; two hand-written HTML pages never will.
   recurring mistake. The changelog lives ONLY in
   `docs/development/arena-studio-release-notes.md` — add an entry there for user-visible
   changes.
+- **Run logs are `.jsonl.gz` (v0.72+, `docs/development/runlog-behavior-v2-plan.md`).**
+  `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
+  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
+  never acks, so treat "no ack" as behavior_v1. Never write `log_format` into
+  `run_metadata` from anything but the acked/inferred level.
 - Bump the footer version/timestamp on every edit; never Prettier the HTML.
 
 ## Pattern Designer (`pattern_editor.html`)
diff --git a/arena_studio.html b/arena_studio.html
index dc56446..a5928ab 100644
--- a/arena_studio.html
+++ b/arena_studio.html
@@ -2134,8 +2134,9 @@
         <label class="gh-check"><input type="checkbox" id="ghDirect" title="Save commits straight to the target repo's default branch — no branch, no PR. Course-repo mode: safe there because bench-id namespacing means no two rigs write the same file"> Commit directly to default branch</label>
         <label class="gh-check"><input type="checkbox" id="ghArchivePatterns" title="Advanced: after each completed run, snapshot the SD card's patterns to pattern-sets/&lt;hash&gt;/patterns.zip in the repo (content-hash deduped) — redundancy for on-card edits. OFF by default: the SD bulk-download is still under investigation (it can disconnect the arena on large cards)."> Archive SD patterns to repo after each run <span class="dim">(advanced)</span></label>
         <div class="gh-row"><label for="fmLogLevel">Run logging</label>
-          <select id="fmLogLevel" title="FicTrac frame logging verbosity for recorded runs (and ad-hoc Console logging). behavior_v1 = the compact [ms,fc,idx,ft,x,y,hd] row the live scope + analysis dashboard use (default); full = the whole 25-column FicTrac record (debug/archival, ~4× larger). Asserted at run start — overrides the Console log toggle for deterministic experiment logging.">
-            <option value="behavior_v1">behavior_v1 (compact — default)</option>
+          <select id="fmLogLevel" title="Run-log format for recorded runs (and ad-hoc Console logging). behavior_v2 = compact arena-command echoes + the [ms,fc,idx,ft,x,y,hd] frame row the live scope + analysis dashboard use (default; ~0.4× the size of v1, lossless); behavior_v1 = the pre-2026-09 format (readable by every tool); full = the whole 25-column FicTrac record (debug/archival, ~4× larger). Asserted at run start — overrides the Console log toggle; the bridge acknowledges the level it will actually write and the run banner warns if it is too old for the chosen one.">
+            <option value="behavior_v2">behavior_v2 (compact — default)</option>
+            <option value="behavior_v1">behavior_v1 (legacy)</option>
             <option value="full">full 25-column (debug)</option>
           </select></div>
         <div class="gh-dest" id="ghDest">→ writes a local .yaml file (sign in to GitHub to open a PR instead)</div>
@@ -2249,7 +2250,7 @@ <h3>Sequence · test any single condition ▶ <span id="docSummary" class="doc-s
             <button class="pill log-only" id="btnLogClear">Clear</button>
             <button class="pill log-only" id="btnLogCopy" title="Copy log to clipboard">Copy</button>
             <button class="pill log-only" id="btnLogSave" title="Download the recorded run log (.json + .txt)" disabled>⬇ Save</button>
-            <button class="pill log-only" id="btnLogPush" title="Push this run's log to the course repo (runlogs/&lt;bench-id&gt;/) — use after an auto-commit was skipped (aborted/disconnected) or failed. Needs the bridge still connected; it re-serves the last run until the next one." disabled>⇪ Push log</button>
+            <button class="pill log-only" id="btnLogPush" title="Push this run's log to the course repo (runlogs/&lt;bench-id&gt;/, gzipped .jsonl.gz) — use after an auto-commit was skipped (aborted/disconnected) or failed. Needs the bridge still connected; it re-serves the last run until the next one." disabled>⇪ Push log</button>
           </span>
           <!-- Scope controls live ON the header row in scope mode (maximizes the
                canvas); hidden in log mode. The .acts group is hidden in scope mode. -->
@@ -2917,7 +2918,7 @@ <h2 id="modalTitle">Import error</h2>
 </div>
 
 <footer id="footer">
-  <span class="foot-left">Arena Studio v0.71 | 2026-09-04 16:39 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.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>
   <!-- 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)">
@@ -3287,7 +3288,7 @@ <h2 id="modalTitle">Import error</h2>
     // ---- course-repo run-log auto-commit (CSHL pipeline) -----------------------
     // On COMPLETED recorded runs only: export the bridge's JSONL — the canonical
     // run artifact (run_metadata line + every runner/arena/FicTrac event) — and
-    // direct-commit it as ONE file under runlogs/<bench-id>/. Aborted or
+    // direct-commit it gzipped as ONE `.jsonl.gz` under runlogs/<bench-id>/. Aborted or
     // disconnected runs never auto-commit (deliberate: a partial run is bench
     // debris until someone decides otherwise). Filename STAMP is colon-free —
     // a raw ISO ':' breaks git checkout on Windows clones.
@@ -3391,26 +3392,45 @@ <h2 id="modalTitle">Import error</h2>
         const stamp = new Date().toISOString().slice(0, 19).replace(/:/g, '-');
         const proto = GH.slug(String(log.meta.protocol_filename || 'protocol').replace(/\.ya?ml$/i, ''));
         const who = GH.slug(log.meta.experimenter || 'unknown');
-        const path =
+        const basePath =
             'runlogs/' + cs.benchId + '/' +
             proto + '__' + who + '__' + stamp + '__' + (log.meta.run_id || 'run') + '.jsonl';
-        rawLine((opts.manual ? 'pushing' : 'committing') + ' run log → ' + cs.repo.full + ' · ' + path + ' (' + exported.content.length + ' chars)…', 'info');
-        showUploadModal('Uploading run log…', { busy: true, msg: 'committing to ' + cs.repo.full + '\n' + path });
+        // The archival format is `.jsonl.gz` (behavior_v2 plan, Part 2): gzip in the
+        // browser (lossless, 6–8× smaller) so 40 s and hour-long runs clear the
+        // Contents API's ~35 MiB ceiling; GH.commitFile routes anything still
+        // over 30 MiB through the Git Database API. Readers inflate on the gzip
+        // magic. A browser without CompressionStream falls back to raw .jsonl.
+        const fmtMB = (n) => (n >= 1e6 ? (n / 1e6).toFixed(1) + ' MB' : Math.round(n / 1e3) + ' KB');
+        const rawBytes = new TextEncoder().encode(exported.content).length;
+        let path = basePath + '.gz';
+        let payload = null;
         try {
-            const res = await GH.directCommit(fetch, {
+            payload = { contentBytes: await GH.gzipBytes(exported.content) };
+        } catch (e) {
+            rawLine('gzip unavailable (' + (e && e.message ? e.message : e) + ') — committing uncompressed .jsonl', 'warn');
+            path = basePath;
+            payload = { contentText: exported.content };
+        }
+        const sizeNote = payload.contentBytes
+            ? fmtMB(rawBytes) + ' → ' + fmtMB(payload.contentBytes.length) + ' gzip'
+            : fmtMB(rawBytes);
+        rawLine((opts.manual ? 'pushing' : 'committing') + ' run log → ' + cs.repo.full + ' · ' + path + ' (' + sizeNote + ')…', 'info');
+        showUploadModal('Uploading run log…', { busy: true, msg: 'committing to ' + cs.repo.full + '\n' + path + '\n' + sizeNote });
+        try {
+            const res = await GH.commitFile(fetch, Object.assign({
                 owner: cs.repo.owner,
                 repo: cs.repo.name,
                 token: token,
                 path: path,
-                message: 'runlog: ' + proto + ' on ' + cs.benchId + ' (run ' + (log.meta.run_id || '?') + ')',
-                contentText: exported.content
-            });
+                message: 'runlog: ' + proto + ' on ' + cs.benchId + ' (run ' + (log.meta.run_id || '?') + ')'
+            }, payload));
             if (!res.ok) throw new Error(res.error || 'HTTP ' + res.status);
-            rawLine('✓ run log committed: ' + path, 'info');
-            showUploadModal('✓ Run log committed', { ok: true, msg: cs.repo.full + '\n' + path });
+            const via = res.via === 'git-db' ? ' · via Git Database API (large file)' : '';
+            rawLine('✓ run log committed: ' + path + ' (' + fmtMB(res.bytes) + via + ')', 'info');
+            showUploadModal('✓ Run log committed', { ok: true, msg: cs.repo.full + '\n' + path + '\n' + fmtMB(res.bytes) + via });
             setTimeout(hideUploadModal, 1800); // auto-dismiss on success
             const saved = $('rlSaved');
-            if (saved && !/committed to course repo/.test(saved.textContent)) saved.textContent += ' · ✓ committed to course repo';
+            if (saved && !/committed to course repo/.test(saved.textContent)) saved.textContent += ' · ✓ committed to course repo (' + fmtMB(res.bytes) + ')';
             // Redundancy: stash the actual on-card patterns (deduped by content
             // hash). Best-effort — a failure here never fails the run-log commit.
             try {
@@ -4706,22 +4726,28 @@ <h2 id="modalTitle">Import error</h2>
     })();
 
     // ---- Run logging level (runtime setting; File ▾ → Run logging) ------------
-    // Frame-logging verbosity for recorded runs AND ad-hoc Console logging. A
-    // SESSION setting (localStorage), NOT per-protocol: `behavior_v1` (compact,
-    // default) or `full` (the 25-column record). The runner asserts it at run start
-    // (deterministic — overrides the Console log toggle); the Console keeps the
-    // manual on/off for non-protocol sessions and shows this level read-only.
+    // Run-log format for recorded runs AND ad-hoc Console logging. A SESSION
+    // setting (localStorage), NOT per-protocol: `behavior_v2` (compact arena
+    // echoes, default since v0.72), `behavior_v1` (the pre-2026-09 format — an
+    // explicitly stored choice is honored for one release, then dropped) or `full`
+    // (the 25-column record). The runner asserts it at run start (deterministic —
+    // overrides the Console log toggle); the bridge ACKS the level it will actually
+    // write (a pre-3.0 bridge never acks and silently writes behavior_v1), and the
+    // Console shows the acked level read-only.
+    const LOG_LEVELS = ['behavior_v2', 'behavior_v1', 'full'];
     function sessionLogLevel() {
-        return localStorage.getItem('studio_log_level') === 'full' ? 'full' : 'behavior_v1';
+        const v = localStorage.getItem('studio_log_level');
+        return LOG_LEVELS.includes(v) ? v : 'behavior_v2';
     }
     Studio.sessionLogLevel = sessionLogLevel;
     function applyLogLevel(level) {
-        const lvl = level === 'full' ? 'full' : 'behavior_v1';
+        const lvl = LOG_LEVELS.includes(level) ? level : 'behavior_v2';
         localStorage.setItem('studio_log_level', lvl);
         const b = Studio.session && Studio.session.bridge;
         if (b && b.setLogLevel) b.setLogLevel(lvl); // so ad-hoc Console logging uses it too
         const sel = $('fmLogLevel'); if (sel && sel.value !== lvl) sel.value = lvl;
-        const disp = $('cFtLogLevel'); if (disp) disp.textContent = lvl;
+        const disp = $('cFtLogLevel');
+        if (disp) { disp.textContent = lvl; disp.title = 'Requested log format (read-only here — change it in File ▾ → Run logging); the bridge confirms it when logging starts'; }
     }
     Studio.applyLogLevel = applyLogLevel;
     (function initLogLevel() {
@@ -4798,6 +4824,19 @@ <h2 id="modalTitle">Import error</h2>
         if (Studio.session.bridge) {
             Studio.session.bridge.on('log', (m, kind) => rawLine('bridge: ' + m, kind === 'err' ? 'err' : 'info'));
             Studio.session.bridge.on('status', (text, kind) => rawLine('bridge: ' + text, kind === 'err' ? 'err' : 'info'));
+            // Level ack (bridge ≥ 3.0): the Console mirror shows what the bridge
+            // will ACTUALLY write, flagged when it is too old for the chosen level.
+            Studio.session.bridge.on('loglevel', (info) => {
+                const disp = $('cFtLogLevel');
+                if (!disp || !info) return;
+                if (info.ok) {
+                    disp.textContent = info.level || info.requested;
+                    disp.title = 'Log format confirmed by the bridge' + (info.levels ? ' (it offers: ' + info.levels.join(', ') + ')' : '') + ' — change it in File ▾ → Run logging';
+                } else {
+                    disp.textContent = (info.level || '?') + ' ⚠';
+                    disp.title = 'Bridge too old for ' + info.requested + ' — it logs ' + (info.level || 'behavior_v1') + '. Restart `pixi run bridge` from the current checkout.';
+                }
+            });
         }
         Studio.session.on('disconnect', (info) => {
             if (info && info.involuntary && Studio.activeRunLog && !Studio.activeRunLog.summary) {
@@ -7771,7 +7810,7 @@ <h2 id="modalTitle">Import error</h2>
         // NOT per-protocol. Assert it here so a recorded run logs deterministically
         // at the chosen level — this OVERRIDES any ad-hoc Console log toggle state.
         if (bridge.setLogLevel)
-            bridge.setLogLevel(Studio.sessionLogLevel ? Studio.sessionLogLevel() : 'behavior_v1');
+            bridge.setLogLevel(Studio.sessionLogLevel ? Studio.sessionLogLevel() : 'behavior_v2');
         bridge.setLogging(true); // universal default-on: no experiment untracked
         if ($('cFtLog')) $('cFtLog').checked = true; // keep the console toggle honest
         const ftUrl = ((($('cFtUrl') || {}).value) || 'ws://localhost:8765').trim();
@@ -7781,18 +7820,31 @@ <h2 id="modalTitle">Import error</h2>
                 await new Promise((r) => setTimeout(r, 25));
             }
         }
+        // Log-level negotiation (behavior_v2 plan, Part 1 §5): a ≥3.0 bridge acks
+        // the level it will ACTUALLY write; a pre-3.0 bridge never acks and silently
+        // writes behavior_v1 (or full, if it was launched with --log-frames). Name
+        // the outcome in the banner + transcript so a stale bridge is visible at run
+        // start, not at analysis time. `logLevel` is what goes into run_metadata.
+        const wantLevel = bridge.logLevel || 'behavior_v2';
+        const ackLevel = bridge.connected && bridge.waitForLogLevelAck ? await bridge.waitForLogLevelAck(800) : null;
+        const logLevel = ackLevel || (wantLevel === 'behavior_v2' ? 'behavior_v1' : wantLevel);
+        Studio._runLogFormat = bridge.connected ? logLevel : null;
+        const levelNote = !bridge.connected ? ''
+            : ackLevel === wantLevel ? ' (' + ackLevel + ')'
+            : ackLevel ? ' ⚠ bridge too old for ' + wantLevel + ' — logging ' + ackLevel + ' (restart `pixi run bridge` from the current checkout)'
+            : ' ⚠ bridge did not confirm the log level (old bridge?) — assuming ' + logLevel + '; restart `pixi run bridge` from the current checkout';
         const ftMsg = bridge.connected
-            ? 'bridge connected (' + ftUrl + ') · run logging to JSONL' + (ftNames.length ? ' · fictrac closed-loop armed' : '')
+            ? 'bridge connected (' + ftUrl + ') · run logging to JSONL' + levelNote + (ftNames.length ? ' · fictrac closed-loop armed' : '')
             : 'bridge NOT connected (' + ftUrl + ') — ' +
               (ftNames.length ? 'closed-loop + ' : '') +
               'JSONL run logging INACTIVE. Start it (`pixi run bridge`) and re-run.';
-        Studio.rawLog((bridge.connected ? '' : '⚠ ') + ftMsg, bridge.connected ? 'info' : 'err');
+        Studio.rawLog((bridge.connected ? '' : '⚠ ') + ftMsg, !bridge.connected ? 'err' : (ackLevel === wantLevel ? 'info' : 'warn'));
         // Also into the RECORDED transcript — a saved runlog.txt must be
         // self-documenting about whether the bridge was live (bench finding:
         // the pre-fix log showed fictracApply firing into nothing, silently).
         if (Studio.activeRunLog) {
             Studio.activeRunLog.event('log', {
-                level: bridge.connected ? 'INFO' : 'WARN',
+                level: !bridge.connected || ackLevel !== wantLevel ? 'WARN' : 'INFO',
                 message: ftMsg
             });
         }
@@ -7800,8 +7852,11 @@ <h2 id="modalTitle">Import error</h2>
         // bridge log (setLogging(true) above rotated a fresh file server-side;
         // messages ride the same socket FIFO, so this lands right after the
         // logging_started marker). The committed artifact is self-describing.
+        // `log_format` names the line format of THIS file (the bridge's acked
+        // level, or the inferred one for a non-acking old bridge) so readers that
+        // skip the frame_schema line still know what they hold.
         if (isExperiment && bridge.connected && Studio.activeRunLog) {
-            bridge.log(Object.assign({ event: 'run_metadata', rig_id: Studio.rigId || null },
+            bridge.log(Object.assign({ event: 'run_metadata', rig_id: Studio.rigId || null, log_format: logLevel },
                 Studio.activeRunLog.meta));
         }
     }
diff --git a/docs/development/arena-studio-release-notes.md b/docs/development/arena-studio-release-notes.md
index 45db836..659e1dc 100644
--- a/docs/development/arena-studio-release-notes.md
+++ b/docs/development/arena-studio-release-notes.md
@@ -4,6 +4,29 @@ 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.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
+  browser before committing it to the course repo (lossless, 6–8× smaller), so 40 s
+  and hour-long runs no longer hit GitHub's ~35 MiB per-file ceiling (the rig03-sr
+  40 s run that failed to auto-commit was 51 MB raw → about 6 MB gzipped). Anything
+  still over 30 MiB after compression goes through GitHub's Git Database API
+  instead of the Contents API. The run summary and the upload dialog show the
+  committed size and, when used, the large-file path. **Readers must inflate:**
+  the analysis dashboard and the replay viewer learn to open `.jsonl.gz` in the
+  next release; until then open new logs with `gunzip` or the bridge's
+  `--convert`. Old `.jsonl` files are untouched.
+- **New default log format `behavior_v2`** (File ▾ → Run logging). Same frame
+  rows as before; the per-command arena echoes (three quarters of a log's bytes)
+  are written compactly by the bridge. `behavior_v1` stays selectable for one
+  release; `full` is unchanged. Needs bridge 3.0 — benches `git pull` and restart
+  `pixi run bridge`.
+- **The bridge now confirms the log level it writes.** The run-start banner names
+  the confirmed level and warns "bridge too old for behavior_v2 — logging
+  behavior_v1" when the running bridge cannot write the chosen format (an old
+  bridge used to fall back silently). The Console's read-only level mirror shows
+  the confirmed level. `run_metadata` gains `log_format`.
+
 ## v0.71 (2026-09-04) · Closed-loop apply is reset at run start and abort
 
 - **No more error floods at the start of a run.** If FicTrac closed-loop "apply"
diff --git a/docs/development/cshl-pipeline-test-plan.md b/docs/development/cshl-pipeline-test-plan.md
index 2d7715d..73db791 100644
--- a/docs/development/cshl-pipeline-test-plan.md
+++ b/docs/development/cshl-pipeline-test-plan.md
@@ -355,7 +355,16 @@ sensitive hops; I measured both against the real services:
 | Hop | Verified up to | Binding limit |
 |---|---|---|
 | Bridge → browser (WebSocket `log_export`) | **50 MB round-trips fine** | not the bottleneck |
-| Browser → GitHub (`directCommit` PUT) | **35 MiB OK; 40 MiB rejected** | **~35 MiB per file** |
+| Browser → GitHub (`directCommit` PUT, Contents API) | **35 MiB OK; 40 MiB rejected** | **~35 MiB per file — RAW** |
+| Browser → GitHub (`directCommitLarge`, Git Database API) | used automatically above 30 MiB gzipped | GitHub's 100 MiB hard limit |
+
+**Since Studio v0.72 (2026-09-06) run logs commit as `.jsonl.gz`** — gzipped in the
+browser (`GH.gzipBytes`, lossless, 6–8× smaller on v1 logs, ~3× on the denser
+`behavior_v2` format) — and `GH.commitFile` routes anything still over 30 MiB
+through the Git Database API (blob → tree → commit → ref). Measured on the
+course corpus: 1282 MB of v1 logs → 656 MB as v2 → 211 MB as v2.gz; the 51 MB
+40 s rig03-sr run → 6 MB. Readers must inflate (gzip magic `1f 8b`). The table
+below describes the RAW Contents-API limit the gzip path was added to clear.
 
 **The binding constraint is GitHub's Contents API: ~35 MiB per committed
 file.** Measured: 5 / 10 / 25 / 30 / 35 MiB all commit (201) and pull back
@@ -377,6 +386,9 @@ FicTrac frame, ~65 bytes/line):
 - `bridge.py --log-frames` (full 25-field record per frame) is **~3–4× larger**
   and could blow the ceiling on a long run — **leave it off for the course**
   (it's off by default). It's a debugging switch, not a course setting.
+- With v0.72's gzip + `behavior_v2` an hour-long run lands around 4 MB, so the
+  ceiling is no longer the constraint in practice; the Git Database fallback is
+  the safety net for `full`-level or multi-hour logs.
 
 **Failure is graceful, never data loss.** If a run log ever exceeds the ceiling,
 `directCommit` gets the 422 and the Studio shows *"Run log commit failed … saved
diff --git a/docs/development/runlog-behavior-v2-plan.md b/docs/development/runlog-behavior-v2-plan.md
index 8d79b1d..95362e5 100644
--- a/docs/development/runlog-behavior-v2-plan.md
+++ b/docs/development/runlog-behavior-v2-plan.md
@@ -1,10 +1,12 @@
-# Run-log format `behavior_v2` + large-file commit path — PLAN (PR 1 bridge shipped; PRs 2–3 pending)
+# Run-log format `behavior_v2` + large-file commit path — PLAN (PRs 1–2 shipped; PR 3 readers pending)
 
 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) implemented
-2026-09-06** — see "PR 1 implementation notes" at the end; PR 2 (Studio) and PR 3
+(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.
+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.
 
 ## Problem
 
@@ -226,3 +228,31 @@ Studio (PR 2) and reader (PR 3) work must build on:
 - **Corpus result (164 logs, 1.28 GB, origin/main of cshl-2026-course):** all pass;
   totals in PR 1's description (1281.6 MB v1 → 655.6 MB v2 → 211.3 MB v2.gz at gzip
   level 6). The 51 MB `rydc2tql` run → 20.4 MB v2 → 6.2 MB v2.gz.
+
+## PR 2 implementation notes (Studio, 2026-09-06)
+
+- **`js/fictrac-bridge-client.js`:** `LOG_LEVELS = ['behavior_v2','behavior_v1','full']`
+  (default v2); handles `hello_ack` (→ `bridgeInfo`, `bridgeSupportsLevel(level)`) and
+  `log_control_ack` (→ `ackedLogLevel`, cleared by every `setLogging()` and on close);
+  new `'loglevel'` event `{source, requested, level, ok, levels, enabled, file}` plus an
+  `'err'` log line on mismatch; `waitForLogLevelAck(ms)` resolves the acked level or
+  null (old bridge / not connected / timeout).
+- **`js/studio-github.js`:** `gzipBytes(input)` (CompressionStream; rejects where
+  unavailable), `isGzip(bytes)`, Git Database builders (`reqCreateBlob`, `reqGetCommit`,
+  `reqCreateTree` — allowlisted path, `reqCreateCommit`, `reqUpdateRef` fast-forward
+  only), `directCommitLarge` (7-call sequence, per-step error reporting),
+  `commitFile` (routes by size; `LARGE_FILE_BYTES` = 30 MiB; `thresholdBytes` test hook;
+  result carries `via` + `bytes`).
+- **`arena_studio.html` v0.72:** `#fmLogLevel` v2/v1/full (v2 default; a stored v1 is
+  honored); Console `#cFtLogLevel` follows the `'loglevel'` event (⚠ + tooltip on
+  mismatch); run start awaits the ack ≤ 800 ms and names the level in the banner +
+  transcript (`WARN` level when it disagrees or is unconfirmed); `run_metadata` gets
+  `log_format` = acked level, or the inferred one for a non-acking bridge (`behavior_v1`
+  when v2 was requested, else the request itself); `commitRunLog` gzips → `<name>.jsonl.gz`
+  via `GH.commitFile`, falls back to raw `.jsonl` without CompressionStream, and reports
+  raw → gz size + the path used in the log line, the modal and the run-summary line.
+- **Not done here (PR 3):** readers. Until PR 3, `.jsonl.gz` files from a v0.72 Studio are
+  opened with `gunzip` / `bridge.py --convert`.
+- **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`.
diff --git a/js/fictrac-bridge-client.js b/js/fictrac-bridge-client.js
index 7fa8beb..858d77c 100644
--- a/js/fictrac-bridge-client.js
+++ b/js/fictrac-bridge-client.js
@@ -14,9 +14,16 @@
  *                  "x":<rad>,"y":<rad>,"hd":<rad>}   (behavior_v1 fields — the live
  *                    oscilloscope's raw state; index/seq/t kept for back-compat)
  *                 {"type":"log_export_result","name":..,"content":..}  (or {"error":..})
+ *                 {"type":"hello_ack","bridge":..,"levels":[..],"level":..,"logging":..}
+ *                    (bridge ≥ 3.0 only — an OLD bridge never answers hello)
+ *                 {"type":"log_control_ack","enabled":..,"level":..,"requested":..,"file":..}
+ *                    (`level` = the level the bridge will ACTUALLY write; an unknown
+ *                     requested level is ignored by the bridge, so this is how a
+ *                     stale bridge becomes visible instead of silently logging v1)
  *   us → bridge:  {"type":"hello","client":...,"v":1}
  *                 {"type":"config","fictrac_port":..,"gain":..,"offset":..,"frames":..}
- *                 {"type":"log_control","enabled":<bool>,"level":"behavior_v1"|"full"}
+ *                 {"type":"log_control","enabled":<bool>,
+ *                                       "level":"behavior_v2"|"behavior_v1"|"full"}
  *                     (opens/closes the log file; level picks the frame-row format)
  *                 {"type":"log", ...}                        (an event to append)
  *                 {"type":"log_export"}                      (close + stream back the log)
@@ -43,11 +50,31 @@
  *   'blocked' (reason:string)              — a frame could not be applied (canApply false)
  *   'apply'   (on:bool)                     — closed-loop apply was enabled/disabled
  *   'log'     (msg:string, kind:string)    — human-readable trace line
+ *   'loglevel' (info:object)               — the bridge acknowledged a log level:
+ *                                            {requested, level, ok, levels, enabled,
+ *                                             file, source:'log_control'|'hello'}.
+ *                                            ok=false ⇒ the bridge cannot write the
+ *                                            requested level (too old) and `level`
+ *                                            is what it logs instead.
  */
 (function (global) {
     'use strict';
 
-    const EVENTS = ['status', 'stats', 'frame', 'sample', 'applied', 'blocked', 'apply', 'log'];
+    const EVENTS = [
+        'status',
+        'stats',
+        'frame',
+        'sample',
+        'applied',
+        'blocked',
+        'apply',
+        'log',
+        'loglevel'
+    ];
+    // Log levels this client knows how to request, most-preferred first. The
+    // bridge advertises ITS list in hello_ack; a level missing there is one the
+    // running bridge is too old for. Mirrors bridge.py LOG_LEVELS.
+    const LOG_LEVELS = ['behavior_v2', 'behavior_v1', 'full'];
 
     class FicTracBridgeClient {
         /**
@@ -86,16 +113,21 @@
             this._lastBlockedMs = 0;
 
             // Bridge config (mirrors the console inputs). Sent on connect + on change.
-            // logLevel is the frame-logging level requested when logging starts
-            // ('behavior_v1' default | 'full'); the browser ASSERTS it so the runner
-            // logs behavior_v1 regardless of how the bridge process was launched.
+            // logLevel is the log format requested when logging starts
+            // ('behavior_v2' default | 'behavior_v1' | 'full'); the browser ASSERTS
+            // it so the runner logs deterministically regardless of how the bridge
+            // process was launched. The bridge answers with the level it will
+            // actually write (log_control_ack) — see ackedLogLevel.
             this._config = {
                 fictrac_port: 60000,
                 gain: 1.8,
                 offset: 0,
                 frames: null,
-                logLevel: 'behavior_v1'
+                logLevel: LOG_LEVELS[0]
             };
+            this._bridgeInfo = null; // from hello_ack: {version, levels, level} (null = old bridge / not yet)
+            this._ackedLevel = null; // from log_control_ack while logging is enabled
+            this._ackWaiters = []; // waitForLogLevelAck() resolvers
         }
 
         // ---- events ----------------------------------------------------------
@@ -193,11 +225,16 @@
                 }
                 if (msg && msg.type === 'frame') this.handleFrame(msg.index, msg);
                 else if (msg && msg.type === 'log_export_result') this._handleExportResult(msg);
+                else if (msg && msg.type === 'hello_ack') this._handleHelloAck(msg);
+                else if (msg && msg.type === 'log_control_ack') this._handleLogControlAck(msg);
             };
             ws.onerror = () => this._emit('status', 'error', 'err');
             ws.onclose = () => {
                 this._stopRateTimer();
                 this._ws = null;
+                this._bridgeInfo = null;
+                this._ackedLevel = null;
+                this._settleAckWaiters(null);
                 this._settleExport('reject', new Error('bridge disconnected during log export'));
                 this._emit('status', 'disconnected', 'dim');
                 this._emit('stats', this.stats);
@@ -265,18 +302,129 @@
         }
 
         /**
-         * Select the frame-logging level for the NEXT log the bridge opens:
-         * 'behavior_v1' (compact, the runner default) or 'full' (25-column). Takes
-         * effect at the next setLogging(true) / reconnect (the bridge applies it
-         * when it opens a fresh file). Unknown values are ignored.
+         * Select the log level for the NEXT log the bridge opens: 'behavior_v2'
+         * (compact arena echoes, the default), 'behavior_v1' (the pre-2026-09
+         * format) or 'full' (25-column FicTrac record). Takes effect at the next
+         * setLogging(true) / reconnect (the bridge applies it when it opens a fresh
+         * file). Unknown values are ignored.
          */
         setLogLevel(level) {
-            if (level === 'behavior_v1' || level === 'full') this._config.logLevel = level;
+            if (LOG_LEVELS.includes(level)) this._config.logLevel = level;
+        }
+        /** The level this client will request (not necessarily what the bridge writes). */
+        get logLevel() {
+            return this._config.logLevel;
+        }
+        /**
+         * The level the bridge acknowledged for the CURRENT log file (log_control_ack
+         * with enabled=true), or null: not yet acked, logging off, or an old bridge
+         * that never acks (then it writes behavior_v1 / whatever --log-frames said).
+         */
+        get ackedLogLevel() {
+            return this._ackedLevel;
+        }
+        /** hello_ack facts {version, levels, level} — null until a ≥3.0 bridge answers. */
+        get bridgeInfo() {
+            return this._bridgeInfo;
+        }
+        /**
+         * Can the connected bridge write `level`? true/false from hello_ack; null when
+         * unknown (no hello_ack yet — including every pre-3.0 bridge).
+         */
+        bridgeSupportsLevel(level) {
+            const lv = level || this._config.logLevel;
+            if (!this._bridgeInfo || !Array.isArray(this._bridgeInfo.levels)) return null;
+            return this._bridgeInfo.levels.includes(lv);
+        }
+        /**
+         * Resolve with the acked level once the bridge answers the pending
+         * log_control (or immediately if it already has); null after `timeoutMs`
+         * (default 1000) — i.e. an old bridge, or not connected.
+         */
+        waitForLogLevelAck(timeoutMs) {
+            if (this._ackedLevel) return Promise.resolve(this._ackedLevel);
+            if (!this.connected || !this._logging) return Promise.resolve(null);
+            return new Promise((resolve) => {
+                const w = { resolve, timer: null };
+                w.timer = setTimeout(() => {
+                    this._ackWaiters = this._ackWaiters.filter((x) => x !== w);
+                    resolve(null);
+                }, timeoutMs || 1000);
+                this._ackWaiters.push(w);
+            });
+        }
+        _settleAckWaiters(level) {
+            const ws = this._ackWaiters;
+            this._ackWaiters = [];
+            for (const w of ws) {
+                if (w.timer && typeof clearTimeout !== 'undefined') clearTimeout(w.timer);
+                w.resolve(level);
+            }
+        }
+        _handleHelloAck(msg) {
+            this._bridgeInfo = {
+                version: msg.bridge || null,
+                levels: Array.isArray(msg.levels) ? msg.levels.slice() : [],
+                level: msg.level || null
+            };
+            const requested = this._config.logLevel;
+            const ok = this._bridgeInfo.levels.includes(requested);
+            if (!ok) {
+                this._emit(
+                    'log',
+                    'bridge ' +
+                        (msg.bridge || '?') +
+                        ' cannot write ' +
+                        requested +
+                        ' (it offers ' +
+                        this._bridgeInfo.levels.join(', ') +
+                        ') — restart `pixi run bridge` from the current checkout',
+                    'err'
+                );
+            }
+            this._emit('loglevel', {
+                source: 'hello',
+                requested: requested,
+                level: ok ? requested : this._bridgeInfo.level,
+                ok: ok,
+                levels: this._bridgeInfo.levels,
+                enabled: !!msg.logging,
+                file: null
+            });
+        }
+        _handleLogControlAck(msg) {
+            const requested = msg.requested != null ? msg.requested : this._config.logLevel;
+            const level = msg.level || null;
+            const enabled = !!msg.enabled;
+            this._ackedLevel = enabled ? level : null;
+            const ok = !enabled || level === requested;
+            if (!ok) {
+                this._emit(
+                    'log',
+                    'bridge too old for ' +
+                        requested +
+                        ' — logging ' +
+                        level +
+                        ' instead (restart `pixi run bridge` from the current checkout)',
+                    'err'
+                );
+            }
+            this._emit('loglevel', {
+                source: 'log_control',
+                requested: requested,
+                level: level,
+                ok: ok,
+                levels: this._bridgeInfo ? this._bridgeInfo.levels : null,
+                enabled: enabled,
+                file: msg.file || null
+            });
+            if (enabled) this._settleAckWaiters(level);
         }
 
         /** Turn the bridge's session log file on/off (sends log_control + the level). */
         setLogging(on) {
             this._logging = !!on;
+            this._ackedLevel = null; // pending until the bridge acks this request
             const msg = { type: 'log_control', enabled: this._logging };
             if (this._logging) msg.level = this._config.logLevel;
             this._send(msg);
@@ -438,6 +586,8 @@
     }
 
     // Dual-export: CommonJS (Node tests) + window global (classic <script src>).
+    FicTracBridgeClient.LOG_LEVELS = LOG_LEVELS.slice();
+
     if (typeof module !== 'undefined' && module.exports) {
         module.exports = FicTracBridgeClient;
     }
diff --git a/js/studio-github.js b/js/studio-github.js
index 73aacc7..6165c59 100644
--- a/js/studio-github.js
+++ b/js/studio-github.js
@@ -23,7 +23,10 @@
  * same file.
  *
  * Security: the token lives ONLY in the Authorization header — never in a URL,
- * never in the body. Writable paths are allowlisted (WRITABLE_PREFIXES:
+ * never in the body. Run logs commit as gzip (`gzipBytes`, `.jsonl.gz`) and
+ * `commitFile` routes >30 MiB payloads through the Git Database API
+ * (`directCommitLarge`) — the Contents API rejects ~35 MiB+ files (HTTP 422).
+ * Writable paths are allowlisted (WRITABLE_PREFIXES:
  * protocols/, runlogs/, configs/metadata/, patterns/, pattern-sets/ — mirrors
  * the URL-state path-traversal guard); reads additionally allow the data
  * repo's root-level controlled-vocabulary YAMLs (READABLE_EXACT: roster,
@@ -39,6 +42,10 @@
 
     const API = 'https://api.github.com';
     const API_VERSION = '2022-11-28';
+    // The Contents API rejects files over ~35 MiB (measured: 35 OK, 40 → 422).
+    // commitFile() routes anything above this through the Git Database API
+    // (blob → tree → commit → ref; hard limit 100 MiB per file).
+    const LARGE_FILE_BYTES = 30 * 1024 * 1024;
     // patterns/ = the shared pattern library (Pattern Designer "Save to Repo");
     // pattern-sets/<hash>/patterns.zip = the opt-in post-run SD snapshot.
     const WRITABLE_PREFIXES = [
@@ -83,6 +90,33 @@
         return btoa(bin);
     }
 
+    /**
+     * gzip bytes (or a UTF-8 string) with the platform CompressionStream —
+     * Chrome ≥ 80, Node ≥ 18. Run logs are committed as `.jsonl.gz` (6–8×
+     * smaller; lossless). Rejects when the platform has no CompressionStream so
+     * the caller can fall back to the uncompressed path.
+     * @param {Uint8Array|ArrayBuffer|string} input
+     * @returns {Promise<Uint8Array>}
+     */
+    async function gzipBytes(input) {
+        if (typeof CompressionStream === 'undefined') {
+            throw new Error('CompressionStream unavailable — cannot gzip in this browser');
+        }
+        const u8 =
+            typeof input === 'string'
+                ? new TextEncoder().encode(input)
+                : input instanceof Uint8Array
+                  ? input
+                  : new Uint8Array(input);
+        const stream = new Blob([u8]).stream().pipeThrough(new CompressionStream('gzip'));
+        return new Uint8Array(await new Response(stream).arrayBuffer());
+    }
+    /** gzip magic (1f 8b) — how readers tell a `.gz` payload regardless of name. */
+    function isGzip(bytes) {
+        const u8 = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes || 0);
+        return u8.length >= 2 && u8[0] === 0x1f && u8[1] === 0x8b;
+    }
+
     function _isSanePath(path) {
         if (typeof path !== 'string' || !path) return false;
         if (path.includes('..') || path.startsWith('/') || path.includes('\\')) return false;
@@ -224,6 +258,54 @@
             body: body
         };
     }
+    // ── Git Database API (the >30 MiB path; see directCommitLarge) ────────────
+    function _gitUrl(o, r, tail) {
+        return API + '/repos/' + enc(o) + '/' + enc(r) + '/git/' + tail;
+    }
+    function reqCreateBlob(o, r, bytes, token) {
+        return {
+            method: 'POST',
+            url: _gitUrl(o, r, 'blobs'),
+            headers: headers(token),
+            body: { content: b64Bytes(bytes), encoding: 'base64' }
+        };
+    }
+    function reqGetCommit(o, r, sha, token) {
+        return {
+            method: 'GET',
+            url: _gitUrl(o, r, 'commits/' + enc(sha)),
+            headers: headers(token)
+        };
+    }
+    function reqCreateTree(o, r, baseTreeSha, path, blobSha, token) {
+        if (!isAllowedPath(path)) throw new Error('Refusing to write disallowed path: ' + path);
+        return {
+            method: 'POST',
+            url: _gitUrl(o, r, 'trees'),
+            headers: headers(token),
+            body: {
+                base_tree: baseTreeSha,
+                tree: [{ path: path, mode: '100644', type: 'blob', sha: blobSha }]
+            }
+        };
+    }
+    function reqCreateCommit(o, r, a, token) {
+        return {
+            method: 'POST',
+            url: _gitUrl(o, r, 'commits'),
+            headers: headers(token),
+            body: { message: a.message, tree: a.treeSha, parents: [a.parentSha] }
+        };
+    }
+    function reqUpdateRef(o, r, branch, sha, token) {
+        return {
+            method: 'PATCH',
+            url: _gitUrl(o, r, 'refs/heads/' + branch.split('/').map(enc).join('/')),
+            headers: headers(token),
+            body: { sha: sha, force: false }
+        };
+    }
+
     function reqCreatePull(o, r, a, token) {
         return {
             method: 'POST',
@@ -321,14 +403,106 @@
         return { ok: true, status: put.status, branch: branch, updated: !!sha, data: put.data };
     }
 
+    /**
+     * Large-file direct commit via the Git Database API — for payloads the
+     * Contents API refuses (>~35 MiB): GET /repos (default_branch) → GET
+     * git/ref/heads/<branch> (head commit) → GET git/commits/<sha> (root tree)
+     * → POST git/blobs → POST git/trees (base_tree + ONE entry) → POST
+     * git/commits → PATCH git/refs/heads/<branch> (fast-forward only). Same
+     * token, same WRITABLE_PREFIXES allowlist. Overwrites an existing path
+     * (no sha dance — the tree entry simply replaces it).
+     * @param {Function} fetchImpl injected fetch
+     * @param {object} a {owner, repo, token, path, message, contentBytes}
+     * @returns {{ok:boolean, status:number, branch?:string, sha?:string,
+     *            via:'git-db', step?:string, error?:string}}
+     */
+    async function directCommitLarge(fetchImpl, a) {
+        const fail = (step, res) => ({
+            ok: false,
+            via: 'git-db',
+            step: step,
+            status: res.status,
+            error: _apiError(res)
+        });
+        const repo = await run(fetchImpl, reqGetRepo(a.owner, a.repo, a.token));
+        if (!repo.ok || !repo.data || !repo.data.default_branch) return fail('repo', repo);
+        const branch = repo.data.default_branch;
+        const ref = await run(fetchImpl, reqGetRef(a.owner, a.repo, branch, a.token));
+        if (!ref.ok || !ref.data || !ref.data.object || !ref.data.object.sha)
+            return fail('ref', ref);
+        const headSha = ref.data.object.sha;
+        const head = await run(fetchImpl, reqGetCommit(a.owner, a.repo, headSha, a.token));
+        if (!head.ok || !head.data || !head.data.tree || !head.data.tree.sha)
+            return fail('commit-get', head);
+        const blob = await run(fetchImpl, reqCreateBlob(a.owner, a.repo, a.contentBytes, a.token));
+        if (!blob.ok || !blob.data || !blob.data.sha) return fail('blob', blob);
+        const tree = await run(
+            fetchImpl,
+            reqCreateTree(a.owner, a.repo, head.data.tree.sha, a.path, blob.data.sha, a.token)
+        );
+        if (!tree.ok || !tree.data || !tree.data.sha) return fail('tree', tree);
+        const commit = await run(
+            fetchImpl,
+            reqCreateCommit(
+                a.owner,
+                a.repo,
+                { message: a.message, treeSha: tree.data.sha, parentSha: headSha },
+                a.token
+            )
+        );
+        if (!commit.ok || !commit.data || !commit.data.sha) return fail('commit', commit);
+        const upd = await run(
+            fetchImpl,
+            reqUpdateRef(a.owner, a.repo, branch, commit.data.sha, a.token)
+        );
+        if (!upd.ok) return fail('ref-update', upd);
+        return {
+            ok: true,
+            via: 'git-db',
+            status: upd.status,
+            branch: branch,
+            sha: commit.data.sha
+        };
+    }
+
+    /**
+     * Commit ONE file to the default branch, picking the path by size: the
+     * Contents API (directCommit) up to LARGE_FILE_BYTES, the Git Database API
+     * (directCommitLarge) above it. The result carries `via` and `bytes` so the
+     * caller can say which path landed the file.
+     * @param {object} a {owner, repo, token, path, message, contentText?|contentBytes?,
+     *                    thresholdBytes?  (test hook; default LARGE_FILE_BYTES)}
+     */
+    async function commitFile(fetchImpl, a) {
+        const bytes =
+            a.contentBytes != null
+                ? a.contentBytes instanceof Uint8Array
+                    ? a.contentBytes
+                    : new Uint8Array(a.contentBytes)
+                : new TextEncoder().encode(a.contentText == null ? '' : String(a.contentText));
+        const threshold = Number.isFinite(a.thresholdBytes) ? a.thresholdBytes : LARGE_FILE_BYTES;
+        let res;
+        if (bytes.length > threshold) {
+            res = await directCommitLarge(fetchImpl, Object.assign({}, a, { contentBytes: bytes }));
+        } else {
+            res = await directCommit(fetchImpl, a);
+            res.via = 'contents';
+        }
+        res.bytes = bytes.length;
+        return res;
+    }
+
     const StudioGitHub = {
         API,
         API_VERSION,
+        LARGE_FILE_BYTES,
         WRITABLE_PREFIXES,
         READABLE_EXACT,
         b64,
         b64Bytes,
         bytesEqual,
+        gzipBytes,
+        isGzip,
         isAllowedPath,
         isAllowedReadPath,
         slug,
@@ -340,10 +514,17 @@
         reqGetContents,
         reqGetContentsRaw,
         reqPutContents,
+        reqCreateBlob,
+        reqGetCommit,
+        reqCreateTree,
+        reqCreateCommit,
+        reqUpdateRef,
         reqCreatePull,
         run,
         runBytes,
-        directCommit
+        directCommit,
+        directCommitLarge,
+        commitFile
     };
 
     if (typeof module !== 'undefined' && module.exports) {
diff --git a/tests/test-fictrac-bridge-client.js b/tests/test-fictrac-bridge-client.js
index b873216..b5bb263 100644
--- a/tests/test-fictrac-bridge-client.js
+++ b/tests/test-fictrac-bridge-client.js
@@ -262,15 +262,24 @@ async function main() {
         client.disconnect();
     }
 
-    console.log('\n=== log level (behavior_v1 default / full override) ===');
+    console.log('\n=== log level (behavior_v2 default / v1 + full selectable) ===');
     {
         const client = new FicTracBridgeClient({ WebSocketImpl: FakeWS });
+        check('LOG_LEVELS exposed, v2 first', FicTracBridgeClient.LOG_LEVELS, [
+            'behavior_v2',
+            'behavior_v1',
+            'full'
+        ]);
         client.connect('ws://localhost:8765');
         const ws = FakeWS.last;
         ws.open();
         const lastEnable = () => ws.sent.filter((m) => m.type === 'log_control' && m.enabled).pop();
         client.setLogging(true);
-        check('setLogging asserts default level behavior_v1', lastEnable().level, 'behavior_v1');
+        check('setLogging asserts default level behavior_v2', lastEnable().level, 'behavior_v2');
+        check('logLevel getter = requested level', client.logLevel, 'behavior_v2');
+        client.setLogLevel('behavior_v1');
+        client.setLogging(true);
+        check('setLogLevel(behavior_v1) still selectable', lastEnable().level, 'behavior_v1');
         client.setLogLevel('full');
         client.setLogging(true);
         check('setLogLevel(full) → level full', lastEnable().level, 'full');
@@ -286,6 +295,153 @@ async function main() {
         );
     }
 
+    console.log('\n=== hello_ack / log_control_ack: the bridge names the level it writes ===');
+    {
+        const client = new FicTracBridgeClient({ WebSocketImpl: FakeWS });
+        const events = [];
+        const logs = [];
+        client.on('loglevel', (i) => events.push(i));
+        client.on('log', (m, kind) => logs.push([kind, m]));
+        client.connect('ws://localhost:8765');
+        const ws = FakeWS.last;
+        ws.open();
+        check('no hello_ack yet → bridgeInfo null', client.bridgeInfo, null);
+        check(
+            'no hello_ack yet → bridgeSupportsLevel unknown (null)',
+            client.bridgeSupportsLevel('behavior_v2'),
+            null
+        );
+        check('nothing acked yet', client.ackedLogLevel, null);
+        // A pre-3.0 bridge never acks: waitForLogLevelAck resolves null after the timeout.
+        client.setLogging(true);
+        check('old bridge: wait times out → null', await client.waitForLogLevelAck(15), null);
+        // A 3.0 bridge answers hello with its levels.
+        ws.message({
+            type: 'hello_ack',
+            bridge: '3.0 · behavior_v2',
+            levels: ['behavior_v2', 'behavior_v1', 'full'],
+            level: 'behavior_v2',
+            logging: false
+        });
+        check('hello_ack recorded', client.bridgeInfo, {
+            version: '3.0 · behavior_v2',
+            levels: ['behavior_v2', 'behavior_v1', 'full'],
+            level: 'behavior_v2'
+        });
+        check('bridgeSupportsLevel(v2) true', client.bridgeSupportsLevel('behavior_v2'), true);
+        check('bridgeSupportsLevel(bogus) false', client.bridgeSupportsLevel('behavior_v9'), false);
+        check(
+            'hello loglevel event ok',
+            [events[0].source, events[0].ok, events[0].level],
+            ['hello', true, 'behavior_v2']
+        );
+        checkBool(
+            'no warning when supported',
+            logs.filter((l) => l[0] === 'err').length === 0,
+            JSON.stringify(logs)
+        );
+        // Enable logging; the ack names the same level → ok, waiters resolve.
+        client.setLogging(true);
+        const pending = client.waitForLogLevelAck(5000);
+        ws.message({
+            type: 'log_control_ack',
+            enabled: true,
+            level: 'behavior_v2',
+            requested: 'behavior_v2',
+            file: 'arena-log-1.jsonl'
+        });
+        check('ack → ackedLogLevel', client.ackedLogLevel, 'behavior_v2');
+        check('waitForLogLevelAck resolves with the acked level', await pending, 'behavior_v2');
+        check(
+            'already acked → immediate resolve',
+            await client.waitForLogLevelAck(5000),
+            'behavior_v2'
+        );
+        const e = events[events.length - 1];
+        check(
+            'log_control loglevel event',
+            [e.source, e.ok, e.level, e.requested, e.file, e.enabled],
+            ['log_control', true, 'behavior_v2', 'behavior_v2', 'arena-log-1.jsonl', true]
+        );
+        // Disable → acked level cleared, ack with enabled:false is ok regardless of level.
+        client.setLogging(false);
+        check('setLogging(false) clears acked level (pending)', client.ackedLogLevel, null);
+        ws.message({
+            type: 'log_control_ack',
+            enabled: false,
+            level: 'behavior_v2',
+            requested: null,
+            file: 'arena-log-1.jsonl'
+        });
+        check('disabled ack keeps ackedLogLevel null', client.ackedLogLevel, null);
+        check('disabled ack is ok', events[events.length - 1].ok, true);
+        // MISMATCH: the bridge cannot write what we asked → warning + ok:false.
+        client.setLogging(true);
+        ws.message({
+            type: 'log_control_ack',
+            enabled: true,
+            level: 'behavior_v1',
+            requested: 'behavior_v2',
+            file: 'arena-log-2.jsonl'
+        });
+        const m = events[events.length - 1];
+        check(
+            'mismatch → ok false, level = what the bridge writes',
+            [m.ok, m.level, m.requested],
+            [false, 'behavior_v1', 'behavior_v2']
+        );
+        check(
+            "mismatch → ackedLogLevel is the bridge's level",
+            client.ackedLogLevel,
+            'behavior_v1'
+        );
+        checkBool(
+            'mismatch → err log line names both levels',
+            logs.some(
+                (l) =>
+                    l[0] === 'err' &&
+                    /too old for behavior_v2/.test(l[1]) &&
+                    /logging behavior_v1/.test(l[1])
+            ),
+            JSON.stringify(logs.slice(-1))
+        );
+        // hello_ack from a bridge that lacks the requested level warns up front.
+        const before = logs.length;
+        ws.message({
+            type: 'hello_ack',
+            bridge: '2.9',
+            levels: ['behavior_v1', 'full'],
+            level: 'behavior_v1',
+            logging: true
+        });
+        check(
+            'hello without our level → loglevel ok:false with fallback level',
+            [events[events.length - 1].ok, events[events.length - 1].level],
+            [false, 'behavior_v1']
+        );
+        checkBool(
+            'hello without our level → err log line',
+            logs.length === before + 1 &&
+                logs[before][0] === 'err' &&
+                /cannot write behavior_v2/.test(logs[before][1]),
+            JSON.stringify(logs.slice(before))
+        );
+        // Disconnect resets negotiation state (a fresh setLogging clears the
+        // previous ack, so the waiter is really pending when the socket closes).
+        client.setLogging(true);
+        check('fresh setLogging → acked level pending again', client.ackedLogLevel, null);
+        const w = client.waitForLogLevelAck(5000);
+        ws.close();
+        check('close → pending waiter resolves null', await w, null);
+        check('close → bridgeInfo reset', client.bridgeInfo, null);
+        check('close → ackedLogLevel reset', client.ackedLogLevel, null);
+        check(
+            'not connected → wait resolves null immediately',
+            await client.waitForLogLevelAck(5000),
+            null
+        );
+    }
+
     console.log('\n=== Summary ===');
     console.log(`${totalChecks - failures} / ${totalChecks} checks passed`);
     process.exit(failures === 0 ? 0 : 1);
diff --git a/tests/test-studio-github.js b/tests/test-studio-github.js
index dae3d4e..c5f7aa7 100644
--- a/tests/test-studio-github.js
+++ b/tests/test-studio-github.js
@@ -555,6 +555,313 @@ console.log('=== run (injected fetch) ===');
     check('non-404 GET blocks', [dc.ok, dc.step], [false, 'get']);
     checkBool('no PUT after GET failure', !api.calls.some((c) => c.method === 'PUT'), 'clean');
 
+    // ── gzipBytes / isGzip (run logs commit as .jsonl.gz) ───────────────────
+    console.log('=== gzipBytes / isGzip ===');
+    {
+        const zlib = require('zlib');
+        const text =
+            '{"type":"session"}\n' + '[5,9052,39,0.0,1.42578,-3.19222,1.21378]\n'.repeat(200);
+        const gz = await G.gzipBytes(text);
+        checkBool('returns Uint8Array', gz instanceof Uint8Array, typeof gz);
+        check('gzip magic', G.isGzip(gz), true);
+        check(
+            'inflates to the original text',
+            zlib.gunzipSync(Buffer.from(gz)).toString('utf8'),
+            text
+        );
+        checkBool(
+            'smaller than the input',
+            gz.length < text.length / 4,
+            gz.length + ' vs ' + text.length
+        );
+        const gz2 = await G.gzipBytes(new TextEncoder().encode('héllo ☃'));
+        check(
+            'Uint8Array input, UTF-8 preserved',
+            zlib.gunzipSync(Buffer.from(gz2)).toString('utf8'),
+            'héllo ☃'
+        );
+        check('isGzip on plain text false', G.isGzip(new TextEncoder().encode('{"a":1}')), false);
+        check('isGzip on empty false', G.isGzip(new Uint8Array(0)), false);
+    }
+
+    // ── Git Database API request builders ───────────────────────────────────
+    console.log('=== git-db request builders ===');
+    {
+        const blob = G.reqCreateBlob(O, R, new Uint8Array([0x1f, 0x8b, 0x00, 0xff]), TOKEN);
+        check(
+            'blob POST url',
+            [blob.method, blob.url],
+            ['POST', 'https://api.github.com/repos/reiserlab/webDisplayTools/git/blobs']
+        );
+        check('blob body base64 + encoding', blob.body, {
+            content: 'H4sA/w==',
+            encoding: 'base64'
+        });
+        check('blob auth header', blob.headers.Authorization, 'Bearer ' + TOKEN);
+        const gc = G.reqGetCommit(O, R, 'abc123', TOKEN);
+        check(
+            'get commit',
+            [gc.method, gc.url],
+            ['GET', 'https://api.github.com/repos/reiserlab/webDisplayTools/git/commits/abc123']
+        );
+        const tree = G.reqCreateTree(
+            O,
+            R,
+            'treeBase',
+            'runlogs/bench03/run.jsonl.gz',
+            'blobSha',
+            TOKEN
+        );
+        check(
+            'tree POST url',
+            tree.url,
+            'https://api.github.com/repos/reiserlab/webDisplayTools/git/trees'
+        );
+        check('tree body: base_tree + ONE blob entry', tree.body, {
+            base_tree: 'treeBase',
+            tree: [
+                {
+                    path: 'runlogs/bench03/run.jsonl.gz',
+                    mode: '100644',
+                    type: 'blob',
+                    sha: 'blobSha'
+                }
+            ]
+        });
+        let threw = null;
+        try {
+            G.reqCreateTree(O, R, 't', '.github/workflows/x.yml', 'b', TOKEN);
+        } catch (e) {
+            threw = e.message;
+        }
+        checkBool(
+            'tree refuses a path outside WRITABLE_PREFIXES',
+            /disallowed path/.test(threw || ''),
+            threw
+        );
+        const cm = G.reqCreateCommit(
+            O,
+            R,
+            { message: 'runlog: x', treeSha: 'T', parentSha: 'P' },
+            TOKEN
+        );
+        check('commit body', cm.body, { message: 'runlog: x', tree: 'T', parents: ['P'] });
+        const ref = G.reqUpdateRef(O, R, 'main', 'NEW', TOKEN);
+        check(
+            'ref PATCH (fast-forward only)',
+            [ref.method, ref.url, ref.body],
+            [
+                'PATCH',
+                'https://api.github.com/repos/reiserlab/webDisplayTools/git/refs/heads/main',
+                { sha: 'NEW', force: false }
+            ]
+        );
+        for (const r of [blob, gc, tree, cm, ref])
+            checkBool(
+                'token never in URL (' + r.method + ' ' + r.url.split('/git/')[1] + ')',
+                !r.url.includes(TOKEN),
+                r.url
+            );
+    }
+
+    // ── directCommitLarge + commitFile routing ──────────────────────────────
+    console.log('=== directCommitLarge / commitFile ===');
+    {
+        const mkApi = (opts) => {
+            opts = opts || {};
+            const calls = [];
+            const fetchImpl = async (url, init) => {
+                calls.push({
+                    method: init.method,
+                    url,
+                    body: init.body ? JSON.parse(init.body) : null
+                });
+                const j = (status, data) => ({ ok: status < 300, status, json: async () => data });
+                if (init.method === 'GET' && /\/repos\/[^/]+\/[^/]+$/.test(url))
+                    return j(200, { default_branch: 'main' });
+                if (init.method === 'GET' && /\/git\/ref\/heads\/main$/.test(url))
+                    return j(200, { object: { sha: 'HEAD1' } });
+                if (init.method === 'GET' && /\/git\/commits\/HEAD1$/.test(url))
+                    return j(200, { sha: 'HEAD1', tree: { sha: 'ROOT1' } });
+                if (init.method === 'POST' && /\/git\/blobs$/.test(url))
+                    return opts.blobFail
+                        ? j(422, { message: 'blob too big' })
+                        : j(201, { sha: 'BLOB1' });
+                if (init.method === 'POST' && /\/git\/trees$/.test(url))
+                    return j(201, { sha: 'TREE1' });
+                if (init.method === 'POST' && /\/git\/commits$/.test(url))
+                    return j(201, { sha: 'COMMIT1' });
+                if (init.method === 'PATCH' && /\/git\/refs\/heads\/main$/.test(url))
+                    return j(200, { object: { sha: 'COMMIT1' } });
+                // Contents API path (small files)
+                if (init.method === 'GET' && /\/contents\//.test(url))
+                    return j(404, { message: 'Not Found' });
+                if (init.method === 'PUT' && /\/contents\//.test(url))
+                    return j(201, { content: { path: 'x' } });
+                return j(500, { message: 'unexpected ' + init.method + ' ' + url });
+            };
+            return { calls, fetchImpl };
+        };
+        const bytes = new Uint8Array([0x1f, 0x8b, 1, 2, 3]);
+        let api = mkApi();
+        let res = await G.directCommitLarge(api.fetchImpl, {
+            owner: O,
+            repo: R,
+            token: TOKEN,
+            path: 'runlogs/bench03/big.jsonl.gz',
+            message: 'runlog: big',
+            contentBytes: bytes
+        });
+        check(
+            'large: ok via git-db with the new commit sha',
+            [res.ok, res.via, res.branch, res.sha],
+            [true, 'git-db', 'main', 'COMMIT1']
+        );
+        check(
+            'large: 7-call sequence repo→ref→commit→blob→tree→commit→ref',
+            api.calls.map((c) => c.method + ' ' + c.url.replace(/^.*\/repos\/[^/]+\/[^/]+/, '')),
+            [
+                'GET ',
+                'GET /git/ref/heads/main',
+                'GET /git/commits/HEAD1',
+                'POST /git/blobs',
+                'POST /git/trees',
+                'POST /git/commits',
+                'PATCH /git/refs/heads/main'
+            ]
+        );
+        check('large: tree built on the head root tree with the blob', api.calls[4].body, {
+            base_tree: 'ROOT1',
+            tree: [
+                { path: 'runlogs/bench03/big.jsonl.gz', mode: '100644', type: 'blob', sha: 'BLOB1' }
+            ]
+        });
+        check('large: commit parents = head', api.calls[5].body.parents, ['HEAD1']);
+        check('large: ref moved to the new commit, no force', api.calls[6].body, {
+            sha: 'COMMIT1',
+            force: false
+        });
+        checkBool(
+            'large: token only in headers',
+            api.calls.every((c) => !c.url.includes(TOKEN)),
+            'urls clean'
+        );
+        api = mkApi({ blobFail: true });
+        res = await G.directCommitLarge(api.fetchImpl, {
+            owner: O,
+            repo: R,
+            token: TOKEN,
+            path: 'runlogs/b/x.jsonl.gz',
+            message: 'm',
+            contentBytes: bytes
+        });
+        check(
+            'large: blob failure reported with step + status + message',
+            [res.ok, res.step, res.status, res.error],
+            [false, 'blob', 422, 'blob too big']
+        );
+        check('large: stops after the failing call', api.calls.length, 4);
+
+        // commitFile routes by size: small → Contents API, big → git-db.
+        api = mkApi();
+        res = await G.commitFile(api.fetchImpl, {
+            owner: O,
+            repo: R,
+            token: TOKEN,
+            path: 'runlogs/b/small.jsonl.gz',
+            message: 'm',
+            contentBytes: bytes
+        });
+        check(
+            'commitFile small → contents path',
+            [res.ok, res.via, res.bytes],
+            [true, 'contents', 5]
+        );
+        check(
+            'commitFile small → GET contents + PUT',
+            api.calls.slice(1).map((c) => c.method),
+            ['GET', 'PUT']
+        );
+        api = mkApi();
+        res = await G.commitFile(api.fetchImpl, {
+            owner: O,
+            repo: R,
+            token: TOKEN,
+            path: 'runlogs/b/big.jsonl.gz',
+            message: 'm',
+            contentBytes: bytes,
+            thresholdBytes: 4
+        });
+        check(
+            'commitFile over threshold → git-db path',
+            [res.ok, res.via, res.bytes],
+            [true, 'git-db', 5]
+        );
+        check(
+            'commitFile over threshold → blob posted',
+            api.calls.some((c) => /\/git\/blobs$/.test(c.url)),
+            true
+        );
+        api = mkApi();
+        res = await G.commitFile(api.fetchImpl, {
+            owner: O,
+            repo: R,
+            token: TOKEN,
+            path: 'runlogs/b/t.jsonl',
+            message: 'm',
+            contentText: 'héllo'
+        });
+        check('commitFile contentText → byte length is UTF-8 length', res.bytes, 6);
+        check('LARGE_FILE_BYTES is 30 MiB', G.LARGE_FILE_BYTES, 30 * 1024 * 1024);
+    }
+
+    // ── the Studio's run-log commit path uses gzip + commitFile ─────────────
+    console.log('=== arena_studio.html run-log commit wiring ===');
+    {
+        const start = studioHtml.indexOf('async function commitRunLog(');
+        const end = studioHtml.indexOf('Studio._maybeCommitRunLog = maybeCommitRunLog;', start);
+        const body = studioHtml.slice(start, end);
+        checkBool(
+            'commitRunLog gzips the export',
+            /GH\.gzipBytes\(exported\.content\)/.test(body),
+            'gzipBytes call'
+        );
+        checkBool(
+            'commitRunLog commits <name>.jsonl.gz',
+            /basePath \+ '\.gz'/.test(body),
+            '.gz path'
+        );
+        checkBool(
+            'commitRunLog routes through GH.commitFile (size-based path choice)',
+            /GH\.commitFile\(fetch,/.test(body),
+            'commitFile call'
+        );
+        checkBool(
+            'commitRunLog no longer calls directCommit directly',
+            !/GH\.directCommit\(fetch/.test(body),
+            'directCommit absent'
+        );
+        checkBool(
+            'commitRunLog falls back to raw .jsonl when gzip is unavailable',
+            /contentText: exported\.content/.test(body),
+            'fallback'
+        );
+        checkBool(
+            'fmLogLevel offers behavior_v2 as the default option',
+            /<option value="behavior_v2">behavior_v2 \(compact — default\)<\/option>/.test(
+                studioHtml
+            ),
+            'option'
+        );
+        checkBool(
+            'run_metadata carries log_format',
+            /event: 'run_metadata', rig_id: Studio\.rigId \|\| null, log_format: logLevel/.test(
+                studioHtml
+            ),
+            'log_format'
+        );
+    }
+
     console.log('\n=== Summary ===');
     console.log(`${totalChecks - failures} / ${totalChecks} checks passed`);
     process.exit(failures ? 1 : 0);