From 3042607009467df1389563694c986d1911802258 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 11:22:44 -0400
Subject: [PATCH 01/67] =?UTF-8?q?feat(studio):=20SD-card=20stall=20visibil?=
 =?UTF-8?q?ity=20=E2=80=94=20per-trial=20stimulus=20quality,=20card=20iden?=
 =?UTF-8?q?tity=20(0xCD),=20ring-v2=20FRAME=20latency=20fields,=20telemetr?=
 =?UTF-8?q?y=20report=20=E2=80=94=20Studio=20v0.77?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The controller's SD card stalls 23–89 ms every ~24.5k reads of a large pattern (card-internal
read-count maintenance; 712/716 stalls on the 813 KB pattern, none on the 81 KB one; measured
displayed-frame gap = stall + ~2 ms). Acceptable freeze: 5 ms target / 10 ms worst case.

- js/arena-telemetry.js: FRAME extras from ring-v2 firmware (req_age_us u32, superseded, flags →
  sdRead/contiguous), STATE kinds 11 sd_layout / 12 sd_slow_ctx / 13 sd_reads, sd_slow phase byte;
  cf rows gain three optional trailing fields; STREAM_SCHEMA updated; drainer per-poll budget
  40 → 200 chunks (background-tab 1 Hz polling could not keep up with 26 B FRAMEs at 200–286 Hz).
- js/arena-wire-g6.js: 0xCB flags bit 5 sdFastPath (+ ' sdfast' label), GET_SD_INFO 0xCD
  encoder/decoder (CID manufacturer/product/serial/date, capacity, FAT type, cluster size, label).
- js/trial-quality.js (new, dual-export, tested): per-trial pass / fail / unknown from ring records
  in seq order — trial = successful sd_open; fail = sd_slow read or FRAME req_age over 10 ms;
  coverage gaps (seq gap, reboot, ring overrun, poller paused) → unknown, never pass; dedup by seq;
  display_gap events; reads/commands/index-change accounting.
- arena_studio.html v0.77: reads 0xCD at link-up → Studio.sdCard → run_metadata.sd_card; feeds the
  drainer's records to trial-quality; display_gap events + trial_quality event at run end after a
  final drain; banner naming flagged trials (flag only — exclusion is the experimenter's call);
  FRAME dump lines show age/superseded/contiguous.
- scripts/telemetry-report.py (new, tested): reads accounting per pattern, SD read cost by index
  step class, stall clusters with spacing in commands / index changes / seconds, request→presentation
  percentiles, per-trial verdict table; consumes Studio logs and sd_stall_test.py logs alike.
- scripts/wedge-scan.py: kinds 11–13 (sd_layout labelled contig/FRAGMENTED + spc).
- tests: arena-telemetry (v1 + v2 FRAME, kinds 11–13), arena-wire (bit 5, 0xCD fixture),
  trial-quality (21), telemetry-report (37); pixi test task wired. Release notes v0.77; CLAUDE.md rule.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 arena_studio.html                             |  67 ++-
 .../development/arena-studio-release-notes.md |  20 +
 js/arena-telemetry.js                         |  71 ++-
 js/arena-wire-g6.js                           | 108 +++-
 js/trial-quality.js                           | 304 +++++++++++
 pixi.toml                                     |   2 +-
 scripts/telemetry-report.py                   | 477 ++++++++++++++++++
 scripts/wedge-scan.py                         |   5 +
 tests/test-arena-telemetry.js                 |  90 +++-
 tests/test-arena-wire-g6.js                   |  73 +++
 tests/test-telemetry-report.py                | 178 +++++++
 tests/test-trial-quality.js                   | 178 +++++++
 12 files changed, 1555 insertions(+), 18 deletions(-)
 create mode 100644 js/trial-quality.js
 create mode 100644 scripts/telemetry-report.py
 create mode 100644 tests/test-telemetry-report.py
 create mode 100644 tests/test-trial-quality.js

diff --git a/arena_studio.html b/arena_studio.html
index 82511ea3..db1c7be1 100644
--- a/arena_studio.html
+++ b/arena_studio.html
@@ -2959,7 +2959,7 @@ <h2 id="modalTitle">Import error</h2>
 </div>
 
 <footer id="footer">
-  <span class="foot-left">Arena Studio v0.76 | 2026-09-12 23:18 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.77 | 2026-09-13 11:19 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)">
@@ -2992,6 +2992,7 @@ <h2 id="modalTitle">Import error</h2>
 <script src="js/studio-runlog-adapter.js"></script>
 <script src="js/studio-postmortem.js"></script>
 <script src="js/arena-telemetry.js"></script>
+<script src="js/trial-quality.js"></script>
 <script src="js/kinematics.js"></script> <!-- shared scope/dashboard kinematic derivations -->
 <script src="js/studio-github.js"></script>
 <script src="js/runlog-format.js?v=20260906-1829"></script>
@@ -3685,6 +3686,9 @@ <h2 id="modalTitle">Import error</h2>
     // firmware answers an unknown opcode with an error glyph on the arena, so we
     // never ask blind. Falls back to the 0xC2 format byte ("v1") on old builds.
     Studio.firmwareVersion = null; // decoded 0xCB record, or null
+    // SD card identity (GET_SD_INFO 0xCD, fw sd_fastpath): every stall measurement and card
+    // comparison must be attributable to a physical card → run_metadata.sd_card.
+    Studio.sdCard = null;
     Studio.refreshFirmwareVersion = async function () {
         if (!Studio.session || !Studio.session.connected) return null;
         const caps = Studio.capabilities || [];
@@ -3701,6 +3705,14 @@ <h2 id="modalTitle">Import error</h2>
                 Studio.firmware = v.label;
                 if ($('pvFw')) { $('pvFw').textContent = v.label; $('pvFw').title = 'git ' + v.sha + (v.dirty ? ' (dirty tree)' : '') + ' · ' + v.branch + ' · built ' + v.date + ' · ' + v.arena + (v.debug ? ' · DEBUG_SERIAL' : ''); }
                 rawLine('‹ firmware build: ' + v.label, 'info');
+                Studio.sdCard = null;
+                if (v.sdFastPath && Wire.encodeGetSdInfo) {
+                    try {
+                        const si = Wire.decodeSdInfo(await Studio.session.send(Wire.encodeGetSdInfo(), { timeoutMs: 2000 }));
+                        Studio.sdCard = si;
+                        if (si) rawLine('‹ sd card: ' + si.label + (si.mounted ? ' · cid ' + si.cidHex : ''), si.mounted ? 'info' : 'warn');
+                    } catch (e) { rawLine('sd info: ' + (e && e.message ? e.message : e), 'warn'); }
+                }
                 return v;
             }
         } catch (e) {
@@ -8330,12 +8342,24 @@ <h2 id="modalTitle">Import error</h2>
             wire: Wire,
             maxBytes: 178, // firmware reply budget: 3 + payload < 200 ⇒ 196 − 18 B header
             onRecords: (block, rows) => {
+                // Per-trial stimulus quality (js/trial-quality.js): fed BEFORE the sink
+                // decides, in ring order; the module dedups re-delivered records by seq.
+                if (Studio.trialQuality) Studio.trialQuality.feed(block.records);
                 // Return the bridge's acceptance: false ⇒ the drainer withholds its ack
                 // and the controller keeps the records (bridge down / logging off).
                 const b = Studio.session.bridge;
                 return b && typeof b.logRows === 'function' ? b.logRows(rows) !== false : false;
             }
         });
+        if (!Studio.trialQuality && window.TrialQuality) {
+            Studio.trialQuality = window.TrialQuality.createTrialQuality({
+                onGap: (ev) => {
+                    const b = Studio.session.bridge;
+                    if (b && b.logging) b.log(ev);
+                    Studio.rawLog('display gap ' + ev.ms + ' ms (' + ev.kind + (ev.phase ? ', ' + ev.phase : '') + ') in trial ' + ev.trial + ' pattern ' + ev.pattern, 'warn');
+                }
+            });
+        }
         const poller = AT.createPoller({
             drainer,
             canPoll: () => {
@@ -8349,7 +8373,13 @@ <h2 id="modalTitle">Import error</h2>
                 if (Studio.session.outputInhibited) return { ok: false, reason: 'output inhibited' };
                 return { ok: true };
             },
-            onState: (s, r) => { if (s === 'paused' && r) Studio.rawLog('telemetry poller paused: ' + r, 'dim'); }
+            onState: (s, r) => {
+                if (s === 'paused' && r) {
+                    Studio.rawLog('telemetry poller paused: ' + r, 'dim');
+                    // Coverage gap: a trial classified while the drain was paused is 'unknown', never 'pass'.
+                    if (Studio.trialQuality && Studio.activeRunLog) Studio.trialQuality.noteCoverage('poller_paused', r);
+                }
+            }
         });
         Studio.telemetry = { drainer, poller, startedMs: Date.now(), lastReport: null };
         poller.start(100);
@@ -8399,7 +8429,7 @@ <h2 id="modalTitle">Import error</h2>
     }
     const tail = recs.slice(-30).map((r) =>
         r.kind === 'cmd' ? 'CMD 0x' + r.cmd.toString(16) + ' st' + r.status + ' @' + r.tUs :
-        r.kind === 'frame' ? 'FRAME idx' + r.idx + ' sd' + r.sdLoadUs + 'us spi' + r.spiUs + 'us @' + r.tUs :
+        r.kind === 'frame' ? 'FRAME idx' + r.idx + ' sd' + r.sdLoadUs + 'us spi' + r.spiUs + 'us' + (r.reqAgeUs != null ? ' age' + r.reqAgeUs + 'us sup' + r.superseded + (r.contiguous ? ' contig' : '') : '') + ' @' + r.tUs :
         r.kind === 'state' ? 'STATE ' + r.stateName + ' ' + (r.codeName || r.code) + ' ' + r.arg + ' @' + r.tUs : '?');
     const summary = { tag: tag || 'drain', records: recs.length, blocks: blocks.length, survivedReboot: d.stats.survivedReboot, bootCount: d.stats.bootCount, dropped: d.stats.dropped, gaps: d.stats.gaps, heapCollision: !!d.stats.heapCollision, tail };
     Studio.rawLog('telemetry dump (' + summary.tag + '): ' + recs.length + ' records' + (d.stats.survivedReboot ? ' — ring survived the reboot' : '') + (tail.length ? '\n  ' + tail.join('\n  ') : ''), recs.length ? 'warn' : 'dim');
@@ -8549,6 +8579,15 @@ <h2 id="modalTitle">Import error</h2>
             // Instrumentation is an experimental factor — say whether the 10 Hz
             // ring drain was interleaved with this run's commands.
             md.telemetry = Studio.telemetryAvailable ? 'ring-10hz' : 'off';
+            // Which physical SD card served this run (fw sd_fastpath, 0xCD) — the card's
+            // read-count housekeeping is the dominant display-freeze source (2026-09-13).
+            const sc = Studio.sdCard;
+            md.sd_card = sc && sc.mounted ? {
+                label: sc.label, manufacturer: sc.manufacturer, pnm: sc.pnm, prv: sc.prv, psn_hex: sc.psnHex,
+                mdt: sc.mdtYear + '-' + String(sc.mdtMonth).padStart(2, '0'), capacity_gb: sc.capacityGB,
+                card_type: sc.cardTypeName, fat: sc.fatTypeName, bytes_per_cluster: sc.bytesPerCluster, cid_hex: sc.cidHex
+            } : null;
+            md.gap_threshold_ms = Studio.trialQuality ? Studio.trialQuality.thresholdUs / 1000 : null;
             bridge.log(md);
         }
         // Controller telemetry streams (T4): declare the compact row schema once
@@ -8560,6 +8599,7 @@ <h2 id="modalTitle">Import error</h2>
     let summary = null;
     Studio._userStopRequested = false;
     Studio._linkDropped = false;
+    if (Studio.trialQuality) Studio.trialQuality.reset(); // per-trial stimulus-quality verdicts start fresh
     try {
         // NOTE: do NOT pass onProgress — the session broadcasts 'runstatus' which
         // Studio.onRunStatus (subscribed once) consumes, so the log/highlight stay
@@ -8591,6 +8631,27 @@ <h2 id="modalTitle">Import error</h2>
         if (summary && summary.fault) {
             Studio._lastPostmortem = await Studio.handleControllerFault(summary);
         }
+        // Stimulus quality (SD-card stalls, 2026-09-13): one last drain so the run's final ring
+        // records land in THIS log file, then the per-trial pass / flagged / unknown verdict →
+        // `trial_quality` event + a banner. Flag only — excluding or repeating a trial is the
+        // experimenter's decision (selection-bias caveat, Codex review).
+        if (Studio.trialQuality) {
+            try {
+                if (Studio.telemetry && Studio.telemetryAvailable && Studio.session.connected && !Studio._activePostmortem) {
+                    await Studio.telemetry.drainer.drainOnce();
+                }
+            } catch (_) { /* best effort */ }
+            const tq = Studio.trialQuality.finish();
+            Studio.lastTrialQuality = tq;
+            if (tq.trials.length) {
+                if (bridge.connected && bridge.logging) bridge.log(Object.assign({ event: 'trial_quality' }, tq));
+                const thr = tq.threshold_us / 1000;
+                const msg = 'stimulus quality: ' + (tq.counts.pass || 0) + ' pass · ' + (tq.counts.fail || 0) + ' flagged · ' + (tq.counts.unknown || 0) + ' unknown'
+                    + (tq.flagged_trials.length ? ' — display gap > ' + thr + ' ms in trial' + (tq.flagged_trials.length > 1 ? 's ' : ' ') + tq.flagged_trials.join(', ') + ' (worst ' + Math.round(tq.worst_gap_us / 100) / 10 + ' ms)' : '');
+                Studio.rawLog(msg, tq.counts.fail ? 'warn' : 'info');
+                if (tq.counts.fail && !Studio.soak) Studio.showBanner('⚠ ' + msg);
+            }
+        }
     } catch (e) {
         Studio.rawLog('run error: ' + (e && e.message ? e.message : e), 'err');
         if (Studio.activeRunLog && !Studio.activeRunLog.summary) {
diff --git a/docs/development/arena-studio-release-notes.md b/docs/development/arena-studio-release-notes.md
index 8e696055..cc064d5b 100644
--- a/docs/development/arena-studio-release-notes.md
+++ b/docs/development/arena-studio-release-notes.md
@@ -4,6 +4,26 @@ 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.77 (2026-09-13) · SD-card stall visibility: per-trial stimulus quality, card identity, request→display latency
+
+- **Display freezes are now flagged per trial.** The controller's SD card stalls for 30–90 ms every
+  ~24 k reads of a large pattern (card-internal housekeeping; the display holds the last frame and
+  the queued closed-loop commands are coalesced). With firmware that reports it (`sdfast` in the
+  firmware label), the Studio classifies every trial **pass / flagged / unknown** from the controller
+  telemetry ring: any SD read or request→display age over **10 ms** (Michael's worst-case acceptable
+  freeze; 5 ms is the target) flags the trial; incomplete telemetry coverage is `unknown`, never
+  `pass`. Each gap is a `display_gap` event in the run log, the per-trial table is a
+  `trial_quality` event at run end, and a banner names the flagged trials. Flag only — excluding or
+  repeating a trial stays the experimenter's decision.
+- **Which SD card ran the experiment** is recorded: the Studio reads the card's identity (maker,
+  product name, serial, manufacture date, capacity, FAT type, cluster size) at connect and writes
+  it into `run_metadata.sd_card`, so card comparisons are attributable.
+- **Request→display latency in the log.** Frame rows now carry how long the request waited before
+  the panels got it (`req_age_us`), how many loads were replaced before being shown, and whether the
+  pattern file is on the fast (contiguous) seek path. Readers treat the new columns as optional.
+- Telemetry drain keeps up in a background tab (per-poll budget raised 5×); new analysis script
+  `scripts/telemetry-report.py` (SD read cost by step, stall clusters, per-trial verdicts).
+
 ## v0.76 (2026-09-11) · Controller-fault detection, post-mortem probes, soak driver (fw #50)
 
 - **2026-09-12 review fixes (Codex gpt-6-astra, see `.codex-review/report-20260912-status.md`):**
diff --git a/js/arena-telemetry.js b/js/arena-telemetry.js
index ca4be7e4..9dc3bbe8 100644
--- a/js/arena-telemetry.js
+++ b/js/arena-telemetry.js
@@ -30,7 +30,9 @@
  * Log rows (behavior_v2 companion streams, proposal § 3.3; `rx` = host receive
  * epoch ms, `t_us` = raw controller micros(), `seq` = ring sequence):
  *   ["cc", rx, t_us, seq, cmd, status, "reqhex"]
- *   ["cf", rx, t_us, seq, idx, pattern, sd_load_us, spi_us]
+ *   ["cf", rx, t_us, seq, idx, pattern, sd_load_us, spi_us(, req_age_us, superseded, flags)]
+ *         — the three trailing fields exist only for ring-v2 firmware (0xCB flags bit 5,
+ *           26 B FRAME records); readers must treat them as optional.
  *   ["cs", rx, t_us, seq, kind, code, arg]
  *
  * Classic dual-export (window global + CommonJS), no bare ES `export`.
@@ -50,8 +52,13 @@
         7: 'sd_open',
         8: 'wdog_context',
         9: 'prev_isr_count',
-        10: 'timer_fail' // IntervalTimer::begin() failed: arg = requested refresh rate (Hz)
+        10: 'timer_fail', // IntervalTimer::begin() failed: arg = requested refresh rate (Hz)
+        11: 'sd_layout', // after sd_open: code bit0 contiguous file, bit1 exFAT; arg = sectors/cluster
+        12: 'sd_slow_ctx', // follows sd_slow: code = SdFat card errorCode(), arg = errorData() & 0xFFFF
+        13: 'sd_reads' // at STOP / next trial start: arg = readFrame calls while that pattern was open
     };
+    // sd_slow (kind 4) code byte, ring v2: bits 0-1 = slowest phase of the read, bit 7 = read error.
+    const SD_SLOW_PHASES = ['unknown', 'seek', 'body', 'tail'];
     const ISR_NAMES = [
         'none',
         'refresh_timer',
@@ -147,6 +154,16 @@
                 rec.pattern = u16(m, p + 2);
                 rec.sdLoadUs = u32(m, p + 4); // u32: the 129 ms SD tail must fit (u16 caps at 65 ms)
                 rec.spiUs = u16(m, p + 8);
+                if (plen >= 16) {
+                    // Ring v2 (fw sd_fastpath): dispatch→SPI latency of the request that
+                    // produced this frame (u32 — a 30–90 ms card stall must be representable),
+                    // loads replaced before any transfer, source flags.
+                    rec.reqAgeUs = u32(m, p + 10);
+                    rec.superseded = m[p + 14];
+                    rec.flags = m[p + 15];
+                    rec.sdRead = !!(rec.flags & 0x01);
+                    rec.contiguous = !!(rec.flags & 0x02);
+                }
             } else if (type === REC.STATE && plen >= 4) {
                 rec.kind = 'state';
                 rec.stateKind = m[p];
@@ -168,6 +185,21 @@
                     rec.isrName = ISR_NAMES[rec.code] || 'isr_' + rec.code;
                     rec.countApprox = rec.arg * 4096;
                 }
+                if (rec.stateKind === 4) {
+                    rec.readUs = rec.arg * 100;
+                    rec.phase = SD_SLOW_PHASES[rec.code & 0x03]; // 'unknown' on ring-v1 firmware (code 0)
+                    rec.readError = !!(rec.code & 0x80);
+                }
+                if (rec.stateKind === 11) {
+                    rec.contiguous = !!(rec.code & 0x01);
+                    rec.exfat = !!(rec.code & 0x02);
+                    rec.sectorsPerCluster = rec.arg;
+                }
+                if (rec.stateKind === 12) {
+                    rec.cardErrorCode = rec.code;
+                    rec.irqstatLo = rec.arg;
+                }
+                if (rec.stateKind === 13) rec.reads = rec.arg;
             } else {
                 rec.kind = 'unknown';
                 rec.raw = hex(m.subarray(p, p + plen));
@@ -184,9 +216,11 @@
         const rows = [];
         for (const r of block.records) {
             if (r.kind === 'cmd') rows.push(['cc', rx, r.tUs, r.seq, r.cmd, r.status, r.req]);
-            else if (r.kind === 'frame')
-                rows.push(['cf', rx, r.tUs, r.seq, r.idx, r.pattern, r.sdLoadUs, r.spiUs]);
-            else if (r.kind === 'state')
+            else if (r.kind === 'frame') {
+                const row = ['cf', rx, r.tUs, r.seq, r.idx, r.pattern, r.sdLoadUs, r.spiUs];
+                if (r.reqAgeUs != null) row.push(r.reqAgeUs, r.superseded, r.flags); // ring v2 only
+                rows.push(row);
+            } else if (r.kind === 'state')
                 rows.push(['cs', rx, r.tUs, r.seq, r.stateKind, r.code, r.arg]);
         }
         return rows;
@@ -199,8 +233,19 @@
             desc: 'controller-side command record'
         },
         cf: {
-            cols: ['rx', 't_us', 'seq', 'idx', 'pattern', 'sd_load_us', 'spi_us'],
-            desc: 'displayed frame change'
+            cols: [
+                'rx',
+                't_us',
+                'seq',
+                'idx',
+                'pattern',
+                'sd_load_us',
+                'spi_us',
+                'req_age_us',
+                'superseded',
+                'flags'
+            ],
+            desc: 'displayed frame change (req_age_us/superseded/flags only from ring-v2 firmware; optional)'
         },
         cs: {
             cols: ['rx', 't_us', 'seq', 'kind', 'code', 'arg'],
@@ -222,10 +267,13 @@
         const W = d.wire || (typeof global !== 'undefined' ? global.ArenaWireG6 : null);
         const timeoutMs = d.timeoutMs || 1500;
         const maxBytes = d.maxBytes || 180;
-        // 40 chunks × ~180 B ≈ 7 KB per poll: under Chrome's background-tab timer
-        // throttling a poll may run only once per second, and production during
-        // Mode-3 streaming at 286 Hz is ~5–6 KB/s — the budget must exceed that.
-        const maxChunks = d.maxChunks || 40;
+        // Per-poll budget = maxChunks × ~178 B. Under Chrome's background-tab timer
+        // throttling a poll may run only once per second, and Mode-3 production at
+        // 200–286 Hz with 26 B FRAME records is ~6.5–10 KB/s (Codex review,
+        // 2026-09-13): 40 chunks (7 KB) could not keep up and would silently lose
+        // the evidence that certifies a trial. 200 chunks ≈ 35 KB per poll; the loop
+        // stops at `more == 0`, so the cost is paid only while a backlog exists.
+        const maxChunks = d.maxChunks || 200;
         const now = d.now || (() => Date.now());
         const onRecords = d.onRecords || (() => {});
         const st = {
@@ -453,6 +501,7 @@
         HEADER_BYTES,
         REC,
         STATE_KINDS,
+        SD_SLOW_PHASES,
         ARENA_STATES,
         NO_ACK,
         STREAM_SCHEMA,
diff --git a/js/arena-wire-g6.js b/js/arena-wire-g6.js
index 54930e4e..4876288d 100644
--- a/js/arena-wire-g6.js
+++ b/js/arena-wire-g6.js
@@ -69,6 +69,7 @@ const ArenaWireG6 = (function () {
         GET_HEALTH: 0xca, // [01 CA] controller health counters + previous-boot breadcrumb (fw #50)
         GET_CRASHREPORT: 0xcc, // [01 CC] raw 128 B at OCRAM 0x2027FF80: PJRC arm_fault_info_struct + breadcrumbs (ring fw; gate on 0xCB flags bit 2)
         GET_FIRMWARE_VERSION: 0xcb, // [01 CB] build identity: git SHA, branch, date, arena rows×cols (gate on cap bit 7)
+        GET_SD_INFO: 0xcd, // SD card identity + volume geometry (fw sd_fastpath; gate on 0xCB flags bit 5)
         SET_TELEMETRY: 0xa8, // [04 A8 flags rate_lo rate_hi] telemetry ring: bit0 events on/off (fw feat/telemetry-ring)
         GET_TELEMETRY_BLOCK: 0xa9, // [08 A9 ack_seq u32 max_bytes u16 flags] ack-cursor drain of the ring (js/arena-telemetry.js decodes)
         SET_AO_VOLTAGE: 0xa0, // [03 A0 mv_lo mv_hi] set analog output (BNC J27) 0–5000 mV
@@ -956,6 +957,7 @@ const ArenaWireG6 = (function () {
             telemetry: !!(m[3] & 0x04), // ring buffer (0xA8/0xA9) present — the ONLY gate for SET_TELEMETRY
             crashReport: !!(m[3] & 0x08), // GET_CRASHREPORT 0xCC + GET_HEALTH ver 2 (fw fb11681+): the ONLY gate for 0xCC
             freeRunningTimer: !!(m[3] & 0x10), // fw eca07f6+: SET_FRAME_POSITION never disarms/re-arms the refresh timer
+            sdFastPath: !!(m[3] & 0x20), // fw 200fada+: O(1) seeks, same-index skip, 26 B FRAME (ring v2), GET_SD_INFO 0xCD — the ONLY gate for 0xCD
             sha: ascii(4, 8),
             date: ascii(12, 10),
             branch: ascii(22, 24)
@@ -970,7 +972,108 @@ const ArenaWireG6 = (function () {
             (v.date || '?') +
             (v.branch ? ' ' + v.branch : '') +
             (v.debug ? ' (debug)' : '') +
-            (v.freeRunningTimer ? ' freerun' : '');
+            (v.freeRunningTimer ? ' freerun' : '') +
+            (v.sdFastPath ? ' sdfast' : '');
+        return v;
+    }
+
+    // get-sd-info (0xCD) — the SD CARD's identity (CID/CSD, cached by SdFat at
+    // mount, so O(1)) plus volume geometry. Every stall measurement / card
+    // comparison must be attributable to a physical card. Gate on 0xCB flags
+    // bit 5 (`sdFastPath`); older firmware flashes an error glyph on unknown opcodes.
+    function encodeGetSdInfo() {
+        return frame(OPCODES.GET_SD_INFO); // 01 CD
+    }
+    // Payload (30 B): ver u8 · flags u8 (bit0 mounted, bit1 CID valid, bit2 CSD
+    // valid) · card_type u8 · fat_type u8 (12/16/32, 64 = exFAT) · sectors u32 ·
+    // bytes_per_cluster u32 · cid[16] raw · sd_status_maint u8 (0xFF = not read) ·
+    // reserved u8. Status 1 (no card) still carries the payload.
+    const SD_INFO_PAYLOAD_BYTES = 30;
+    // SD manufacturer IDs (CID byte 0) — the common ones; unknown → hex.
+    const SD_MANUFACTURERS = {
+        0x01: 'Panasonic',
+        0x02: 'Toshiba/Kioxia',
+        0x03: 'SanDisk',
+        0x09: 'ATP',
+        0x13: 'KingMax',
+        0x1b: 'Samsung',
+        0x1d: 'ADATA',
+        0x27: 'Phison',
+        0x28: 'Lexar',
+        0x31: 'Silicon Power',
+        0x41: 'Kingston',
+        0x5d: 'Swissbit',
+        0x6f: 'STMicro',
+        0x74: 'Transcend',
+        0x76: 'Patriot',
+        0x82: 'Sony/Gobe',
+        0x9c: 'Angelbird/Hoodman'
+    };
+    const SD_CARD_TYPES = ['none', 'SD1', 'SD2', 'SDHC/SDXC'];
+    function decodeSdInfo(resp) {
+        const r = asResponse(resp);
+        if (!r || r.payload.length < SD_INFO_PAYLOAD_BYTES) return null; // status 1 (no card) still decodes
+        const m = r.payload;
+        const u32le = (o) => (m[o] | (m[o + 1] << 8) | (m[o + 2] << 16) | (m[o + 3] << 24)) >>> 0;
+        const ascii = (from, len) =>
+            Array.from(m.subarray(from, from + len))
+                .map((b) => (b >= 0x20 && b < 0x7f ? String.fromCharCode(b) : ''))
+                .join('')
+                .trim();
+        const cid = m.subarray(12, 28);
+        const v = {
+            ver: m[0],
+            flags: m[1],
+            mounted: !!(m[1] & 0x01),
+            cidValid: !!(m[1] & 0x02),
+            csdValid: !!(m[1] & 0x04),
+            cardType: m[2],
+            cardTypeName: SD_CARD_TYPES[m[2]] || 'type_' + m[2],
+            fatType: m[3],
+            fatTypeName: m[3] === 64 ? 'exFAT' : m[3] ? 'FAT' + m[3] : 'unknown',
+            sectors: u32le(4),
+            capacityGB: Math.round((u32le(4) * 512) / 1e7) / 100, // decimal GB, 2 dp
+            bytesPerCluster: u32le(8),
+            sectorsPerCluster: u32le(8) >> 9,
+            cidHex: Array.from(cid)
+                .map((b) => b.toString(16).padStart(2, '0'))
+                .join(''),
+            mid: cid[0],
+            manufacturer:
+                SD_MANUFACTURERS[cid[0]] || 'mid_0x' + cid[0].toString(16).padStart(2, '0'),
+            oid: ascii(13, 2),
+            pnm: ascii(15, 5),
+            prv: (cid[8] >> 4) + '.' + (cid[8] & 0x0f),
+            psn: ((cid[9] << 24) | (cid[10] << 16) | (cid[11] << 8) | cid[12]) >>> 0,
+            mdtYear: 2000 + (((cid[13] & 0x0f) << 4) | (cid[14] >> 4)),
+            mdtMonth: cid[14] & 0x0f,
+            sdStatusMaint: m[28]
+        };
+        v.psnHex = v.psn.toString(16).padStart(8, '0');
+        v.label = !v.mounted
+            ? 'no card'
+            : v.manufacturer +
+              ' ' +
+              (v.pnm || '?') +
+              ' ' +
+              v.prv +
+              ' sn ' +
+              v.psnHex +
+              ' (' +
+              v.mdtYear +
+              '-' +
+              String(v.mdtMonth).padStart(2, '0') +
+              ') ' +
+              v.capacityGB +
+              ' GB ' +
+              v.cardTypeName +
+              ' ' +
+              v.fatTypeName +
+              ' ' +
+              (v.bytesPerCluster >= 1024
+                  ? v.bytesPerCluster / 1024 + ' KiB'
+                  : v.bytesPerCluster + ' B') +
+              ' clusters';
         return v;
     }
 
@@ -1192,6 +1295,7 @@ const ArenaWireG6 = (function () {
         encodeGetHealth,
         encodeGetFramePosition,
         encodeGetFirmwareVersion,
+        encodeGetSdInfo,
         encodeSetTelemetry,
         encodeGetTelemetryBlock,
         TELEMETRY_NO_ACK,
@@ -1226,6 +1330,8 @@ const ArenaWireG6 = (function () {
         decodeFramePosition,
         decodeFirmwareVersion,
         FIRMWARE_VERSION_PAYLOAD_BYTES,
+        decodeSdInfo,
+        SD_INFO_PAYLOAD_BYTES,
         HEALTH_PAYLOAD_BYTES,
         HEALTH_PAYLOAD_BYTES_FULL,
         HEALTH_PAYLOAD_BYTES_V2,
diff --git a/js/trial-quality.js b/js/trial-quality.js
new file mode 100644
index 00000000..8dd5d534
--- /dev/null
+++ b/js/trial-quality.js
@@ -0,0 +1,304 @@
+/**
+ * trial-quality.js — per-trial stimulus-quality classification from the
+ * controller telemetry ring (fw sd_fastpath / ring v2, 2026-09-13).
+ *
+ * The SD card inside the controller stalls for 23–89 ms every ~24.5k reads of a
+ * large pattern (card-internal read-count maintenance); during a stall the
+ * display freezes and the queued closed-loop commands are coalesced. Michael's
+ * acceptable display freeze is 5 ms (target) / 10 ms (worst case); anything
+ * ≥ 30 ms is a visible stimulus artifact. This module turns the drained ring
+ * records into a verdict per trial so the analysis can flag (never silently
+ * drop) the affected trials:
+ *
+ *   pass     complete telemetry coverage, no read or displayed-frame gap over the threshold
+ *   fail     at least one `sd_slow` read or FRAME `req_age_us` over the threshold
+ *   unknown  coverage incomplete (seq gap, controller reboot, drain paused / refused
+ *            by the bridge, drainer error) and no fail evidence — NEVER promoted to pass
+ *
+ * Attribution is by CONTROLLER order, not by arrival: records are fed in ring
+ * `seq` order; a trial starts at every successful `sd_open` (kind 7, code 0) and
+ * ends at the next one; `sd_reads` (kind 13) is emitted by the firmware for the
+ * pattern being left before the next `sd_open`, so it belongs to the trial that
+ * is current when it arrives. Records re-delivered by the drainer (a refused or
+ * re-armed block) are dropped by `seq` — counting is idempotent.
+ *
+ * Classic dual-export (window global + CommonJS), no bare ES `export`.
+ */
+(function (global) {
+    'use strict';
+
+    const DEFAULT_GAP_US = 10000; // worst-case acceptable freeze (Michael, 2026-09-13)
+    const DEFAULT_TARGET_US = 5000; // the target, reported but not a fail criterion
+
+    /**
+     * @param {object} [opts]
+     *   gapUs        fail threshold for sd_slow read time and FRAME req_age_us (default 10 000)
+     *   targetUs     reported "over target" count (default 5 000)
+     *   onGap(gap)   called once per over-threshold event with a run-log-ready object
+     *   onTrial(t)   called when a trial closes (the next sd_open or reset())
+     */
+    function createTrialQuality(opts) {
+        const o = opts || {};
+        const gapUs = o.gapUs || DEFAULT_GAP_US;
+        const targetUs = o.targetUs || DEFAULT_TARGET_US;
+        const onGap = o.onGap || (() => {});
+        const onTrial = o.onTrial || (() => {});
+
+        let trials = [];
+        let current = null; // the open trial (not yet closed by the next sd_open)
+        let lastSeq = null; // highest seq accepted (dedup + gap detection)
+        let pendingCoverage = []; // coverage issues noted while no trial is open
+        let duplicates = 0;
+        let fedRecords = 0;
+
+        function newTrial(rec) {
+            closeCurrent();
+            current = {
+                index: trials.length + 1, // 1-based, in controller order
+                pattern: rec.arg,
+                openSeq: rec.seq,
+                openTUs: rec.tUs,
+                lastTUs: rec.tUs,
+                cmds70: 0,
+                indexChanges: 0,
+                lastIdx: null,
+                frames: 0,
+                reads: null, // from sd_reads (kind 13) when the trial closes
+                stalls: [], // over-threshold sd_slow reads
+                slowReads: 0, // every sd_slow record (firmware threshold, 10 ms on v2 / 20 ms on v1)
+                ageGaps: [], // over-threshold FRAME req_age_us
+                overTarget: 0, // FRAME req_age_us over the target (5 ms) but under the threshold
+                maxReadUs: 0,
+                maxAgeUs: 0,
+                superseded: 0,
+                coverage: pendingCoverage.splice(0)
+            };
+            trials.push(current);
+        }
+
+        function closeCurrent() {
+            if (!current) return;
+            const t = current;
+            current = null;
+            t.status = statusOf(t);
+            onTrial(t);
+        }
+
+        function statusOf(t) {
+            if (t.stalls.length || t.ageGaps.length) return 'fail';
+            if (t.coverage.length) return 'unknown';
+            return 'pass';
+        }
+
+        function coverage(reason, detail) {
+            const entry = { reason, detail: detail || null };
+            if (current) current.coverage.push(entry);
+            else pendingCoverage.push(entry);
+        }
+
+        function gapEvent(kind, rec, us, extra) {
+            const ev = Object.assign(
+                {
+                    event: 'display_gap',
+                    trial: current ? current.index : null,
+                    pattern: current ? current.pattern : null,
+                    seq: rec.seq,
+                    t_us: rec.tUs,
+                    ms: Math.round(us / 100) / 10,
+                    kind
+                },
+                extra || {}
+            );
+            onGap(ev);
+            return ev;
+        }
+
+        /**
+         * Feed parsed records (js/arena-telemetry.js `parseBlock().records`) in the
+         * order the drainer delivered them (= ring seq order).
+         */
+        function feed(records) {
+            for (const r of records || []) {
+                if (typeof r.seq !== 'number') continue;
+                // Dedup: the drainer re-delivers a block the sink refused (ack withheld)
+                // and, after a rearm, records already stored. seq is monotonic within a
+                // ring incarnation; a boot record marks a possible restart (fresh ring).
+                const isBoot = r.kind === 'state' && r.stateKind === 1;
+                if (lastSeq != null && !isBoot && seqLE(r.seq, lastSeq)) {
+                    duplicates++;
+                    continue;
+                }
+                if (lastSeq != null && !isBoot && r.seq !== (lastSeq + 1) >>> 0) {
+                    coverage('seq_gap', { expected: (lastSeq + 1) >>> 0, got: r.seq });
+                }
+                lastSeq = r.seq;
+                fedRecords++;
+                if (current && typeof r.tUs === 'number') current.lastTUs = r.tUs;
+
+                if (r.kind === 'state') {
+                    switch (r.stateKind) {
+                        case 1: // boot: the controller reset — whatever trial was open lost its tail
+                            coverage('controller_reboot', { code: r.code });
+                            lastSeq = r.seq; // seq may restart (fresh ring) — accept the new numbering
+                            break;
+                        case 7: // sd_open
+                            if (r.code === 0) newTrial(r);
+                            break;
+                        case 4: {
+                            // sd_slow: readFrame over the FIRMWARE threshold (10 ms v2 / 20 ms v1)
+                            if (!current) break;
+                            const us = (r.readUs != null ? r.readUs : r.arg * 100) >>> 0;
+                            current.slowReads++;
+                            if (us > current.maxReadUs) current.maxReadUs = us;
+                            if (us > gapUs) {
+                                const ev = gapEvent('sd_slow', r, us, {
+                                    phase: r.phase || 'unknown',
+                                    read_error: !!r.readError
+                                });
+                                current.stalls.push({
+                                    seq: r.seq,
+                                    tUs: r.tUs,
+                                    us,
+                                    phase: ev.phase
+                                });
+                            }
+                            break;
+                        }
+                        case 13: // sd_reads for the pattern being left
+                            if (current) current.reads = r.reads != null ? r.reads : r.arg;
+                            break;
+                        case 5: // ring_overrun: records evicted before the host read them
+                            coverage('ring_overrun', { code: r.code, arg: r.arg });
+                            break;
+                        default:
+                            break;
+                    }
+                } else if (r.kind === 'frame') {
+                    if (!current) continue;
+                    current.frames++;
+                    if (current.lastIdx == null) current.lastIdx = r.idx; // the trial's initial frame: a 0x70 for it is not an index change
+                    if (typeof r.superseded === 'number') current.superseded += r.superseded;
+                    if (typeof r.reqAgeUs === 'number') {
+                        if (r.reqAgeUs > current.maxAgeUs) current.maxAgeUs = r.reqAgeUs;
+                        if (r.reqAgeUs > gapUs) {
+                            gapEvent('frame_age', r, r.reqAgeUs, { idx: r.idx });
+                            current.ageGaps.push({
+                                seq: r.seq,
+                                tUs: r.tUs,
+                                us: r.reqAgeUs,
+                                idx: r.idx
+                            });
+                        } else if (r.reqAgeUs > targetUs) current.overTarget++;
+                    }
+                } else if (r.kind === 'cmd') {
+                    if (!current || r.cmd !== 0x70 || r.status !== 0) continue;
+                    current.cmds70++;
+                    const idx = idxFromReq(r.req);
+                    if (idx != null && idx !== current.lastIdx) {
+                        current.indexChanges++;
+                        current.lastIdx = idx;
+                    }
+                }
+            }
+        }
+
+        /** Coverage note from outside the record stream (poller paused, bridge refused, drainer error). */
+        function noteCoverage(reason, detail) {
+            coverage(reason, detail);
+        }
+
+        /** Close the open trial (run end) and return the summary. */
+        function finish() {
+            closeCurrent();
+            return summary();
+        }
+
+        function summary() {
+            const rows = trials.map((t) => compact(t));
+            const counts = { pass: 0, fail: 0, unknown: 0, open: 0 };
+            for (const r of rows) counts[r.status] = (counts[r.status] || 0) + 1;
+            let worstUs = 0;
+            for (const t of trials) worstUs = Math.max(worstUs, t.maxReadUs, t.maxAgeUs);
+            return {
+                threshold_us: gapUs,
+                target_us: targetUs,
+                trials: rows,
+                counts,
+                worst_gap_us: worstUs,
+                flagged_trials: rows.filter((r) => r.status === 'fail').map((r) => r.trial),
+                unknown_trials: rows.filter((r) => r.status === 'unknown').map((r) => r.trial),
+                duplicates_dropped: duplicates,
+                records: fedRecords
+            };
+        }
+
+        function compact(t) {
+            return {
+                trial: t.index,
+                pattern: t.pattern,
+                status: t === current ? 'open' : t.status || statusOf(t),
+                duration_s: Math.round((((t.lastTUs - t.openTUs) >>> 0) / 1e6) * 10) / 10,
+                cmds70: t.cmds70,
+                index_changes: t.indexChanges,
+                reads: t.reads,
+                frames: t.frames,
+                slow_reads: t.slowReads,
+                stalls: t.stalls.length,
+                max_read_ms: Math.round(t.maxReadUs / 100) / 10,
+                age_gaps: t.ageGaps.length,
+                max_age_ms: Math.round(t.maxAgeUs / 100) / 10,
+                over_target: t.overTarget,
+                superseded: t.superseded,
+                coverage: t.coverage.map((c) => c.reason)
+            };
+        }
+
+        function reset() {
+            trials = [];
+            current = null;
+            lastSeq = null;
+            pendingCoverage = [];
+            duplicates = 0;
+            fedRecords = 0;
+        }
+
+        return {
+            feed,
+            noteCoverage,
+            finish,
+            summary,
+            reset,
+            get current() {
+                return current ? compact(current) : null;
+            },
+            get thresholdUs() {
+                return gapUs;
+            }
+        };
+    }
+
+    // seq a <= b with u32 wrap tolerance (half-range rule)
+    function seqLE(a, b) {
+        return (b - a) >>> 0 < 0x80000000;
+    }
+
+    // CMD record `req` = hex of the first ≤ 8 request bytes after [len, cmd]:
+    // for SET_FRAME_POSITION that is "03 70 lo hi" → index = lo | hi << 8.
+    function idxFromReq(req) {
+        if (typeof req !== 'string' || req.length < 8) return null;
+        const lo = parseInt(req.slice(4, 6), 16);
+        const hi = parseInt(req.slice(6, 8), 16);
+        if (Number.isNaN(lo) || Number.isNaN(hi)) return null;
+        return lo | (hi << 8);
+    }
+
+    const TrialQuality = {
+        DEFAULT_GAP_US,
+        DEFAULT_TARGET_US,
+        createTrialQuality,
+        idxFromReq
+    };
+
+    if (typeof module !== 'undefined' && module.exports) module.exports = TrialQuality;
+    if (typeof global !== 'undefined') global.TrialQuality = TrialQuality;
+})(typeof window !== 'undefined' ? window : this);
diff --git a/pixi.toml b/pixi.toml
index d7e80ec8..82dee624 100644
--- a/pixi.toml
+++ b/pixi.toml
@@ -21,7 +21,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-analog-in.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 && python tests/test-build-runlog-index.py && node tests/test-studio-postmortem.js && node tests/test-arena-telemetry.js && python tests/test-wedge-scan.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-analog-in.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 && python tests/test-build-runlog-index.py && node tests/test-studio-postmortem.js && node tests/test-arena-telemetry.js && python tests/test-wedge-scan.py && node tests/test-trial-quality.js && python tests/test-telemetry-report.py"
 format = "prettier --write \"**/*.js\""
 format-check = "prettier --check \"**/*.js\""
 
diff --git a/scripts/telemetry-report.py b/scripts/telemetry-report.py
new file mode 100644
index 00000000..ae3ef589
--- /dev/null
+++ b/scripts/telemetry-report.py
@@ -0,0 +1,477 @@
+#!/usr/bin/env python3
+"""telemetry-report.py — SD-read cost, card-stall clusters, request→presentation latency and
+per-trial stimulus quality from a behavior_v2 log that carries controller telemetry rows.
+
+Input: bridge behavior_v2 NDJSON (.jsonl / .jsonl.gz) written by fictrac-bridge/bridge.py (Arena
+Studio runs) or by the firmware repo's scripts/sd_stall_test.py (card comparisons) — both carry the
+controller ring as compact rows (js/arena-telemetry.js `toRows`):
+
+    ["cc", rx, t_us, seq, cmd, status, "reqhex"]                      controller CMD record
+    ["cf", rx, t_us, seq, idx, pattern, sd_load_us, spi_us
+           (, req_age_us, superseded, flags)]                          displayed frame change (v2 extras optional)
+    ["cs", rx, t_us, seq, kind, code, arg]                             STATE (4 sd_slow, 7 sd_open, 11 sd_layout,
+                                                                       12 sd_slow_ctx, 13 sd_reads, ...)
+    {"event":"run_metadata", "firmware": "...", "sd_card": {...}, ...}
+
+Rows are consumed in FILE order (= ring seq order as the drainer delivered them); never sort by `rx`.
+
+What it reports (per file):
+  1. reads accounting per pattern — accepted 0x70s, index-changing 0x70s, firmware-counted reads
+     (STATE sd_reads, kind 13), displayed frames, reads per command (measures the same-index skip);
+  2. SD read cost by index step class (+1 sequential / small forward / backward / jump / first-after-open)
+     — the seek-path signature (FAT walk vs contiguous);
+  3. card-stall clusters — every sd_slow over --gap-ms grouped when < 5 s apart; per cluster the trial,
+     pattern, durations, phases, and the spacing since the previous cluster in accepted commands,
+     index changes and seconds (the card's read-count maintenance shows up as a constant count);
+  4. request→presentation latency (ring v2 only): FRAME req_age_us percentiles, frames over the
+     5 ms target and the 10 ms threshold, superseded fraction, contiguous-path share;
+  5. per-trial table with a pass / fail / unknown verdict (same rules as js/trial-quality.js:
+     fail = any read or request age over --gap-ms; unknown = coverage gap; else pass).
+
+Usage:
+    python scripts/telemetry-report.py soak-logs/arena-log-20260913-014056-656.jsonl
+    python scripts/telemetry-report.py --json a.jsonl b.jsonl.gz > report.json
+    python scripts/telemetry-report.py --gap-ms 10 --target-ms 5 file.jsonl
+
+Standalone, stdlib only. Exit 0; 2 on bad arguments.
+"""
+
+from __future__ import annotations
+
+import argparse
+import gzip
+import json
+import os
+import statistics
+import sys
+from collections import Counter, defaultdict
+
+STATE_KINDS = {1: "boot", 2: "state_change", 3: "error_glyph", 4: "sd_slow", 5: "ring_overrun", 6: "telemetry",
+               7: "sd_open", 8: "wdog_context", 9: "prev_isr_count", 10: "timer_fail", 11: "sd_layout",
+               12: "sd_slow_ctx", 13: "sd_reads"}
+SD_SLOW_PHASES = ["unknown", "seek", "body", "tail"]
+CLUSTER_GAP_S = 5.0
+STEP_CLASSES = ("+1", "-1", "+2..9", "-2..-9", "jump>=10", "first-after-open", "other")
+
+
+def open_text(path: str):
+    if path.endswith(".gz"):
+        return gzip.open(path, "rt", encoding="utf-8", errors="replace")
+    return open(path, "r", encoding="utf-8", errors="replace")
+
+
+def pct(values, p):
+    if not values:
+        return None
+    s = sorted(values)
+    return s[min(len(s) - 1, int(p * len(s)))]
+
+
+def _round(v, nd=1):
+    return None if v is None else round(v, nd)
+
+
+def step_class(prev_idx, idx, frame_count):
+    if prev_idx is None:
+        return "other"
+    n = frame_count if frame_count and frame_count > 1 else None
+    d = idx - prev_idx
+    if n:
+        d %= n
+        if d > n // 2:
+            d -= n
+    if d == 1:
+        return "+1"
+    if d == -1:
+        return "-1"
+    if 1 < d < 10:
+        return "+2..9"
+    if -10 < d < -1:
+        return "-2..-9"
+    if abs(d) >= 10:
+        return "jump>=10"
+    return "other"
+
+
+def idx_from_req(req) -> int | None:
+    if not isinstance(req, str) or len(req) < 8:
+        return None
+    try:
+        return int(req[4:6], 16) | (int(req[6:8], 16) << 8)
+    except ValueError:
+        return None
+
+
+class Trial:
+    def __init__(self, index, pattern, rx, t_us):
+        self.index = index
+        self.pattern = pattern
+        self.rx0 = rx
+        self.rx_last = rx
+        self.t0_us = t_us
+        self.cmds70 = 0
+        self.index_changes = 0
+        self.last_idx = None
+        self.frames = 0
+        self.reads_fw = None
+        self.slow_reads = 0
+        self.stalls = []          # (ms, phase)
+        self.age_gaps = 0
+        self.over_target = 0
+        self.max_read_ms = 0.0
+        self.max_age_ms = 0.0
+        self.superseded = 0
+        self.coverage = []
+        self.layout = None
+
+    def status(self):
+        if self.stalls or self.age_gaps:
+            return "fail"
+        if self.coverage:
+            return "unknown"
+        return "pass"
+
+    def row(self):
+        return {
+            "trial": self.index, "pattern": self.pattern,
+            "duration_s": _round((self.rx_last - self.rx0) / 1000.0, 1) if self.rx0 is not None else None,
+            "cmds70": self.cmds70, "index_changes": self.index_changes, "reads_fw": self.reads_fw,
+            "frames": self.frames, "slow_reads": self.slow_reads, "stalls": len(self.stalls),
+            "max_read_ms": _round(self.max_read_ms), "age_gaps": self.age_gaps,
+            "max_age_ms": _round(self.max_age_ms), "over_target": self.over_target,
+            "superseded": self.superseded, "coverage": sorted(set(self.coverage)),
+            "layout": self.layout, "status": self.status(),
+        }
+
+
+def analyze_file(path: str, gap_ms: float = 10.0, target_ms: float = 5.0) -> dict:
+    gap_us = gap_ms * 1000.0
+    target_us = target_ms * 1000.0
+    meta = {"file": os.path.basename(path), "firmware": None, "sd_card": None, "log_format": None,
+            "telemetry": None, "protocol": None, "run_id": None}
+    trials: list[Trial] = []
+    cur: Trial | None = None
+    # per-pattern accumulators
+    step_sd = defaultdict(lambda: defaultdict(list))   # pattern -> class -> [sd_load_us]
+    frame_count = {}                                   # pattern -> max idx + 1 (proxy for frame count)
+    per_pattern = defaultdict(lambda: Counter())       # pattern -> counters
+    layout_by_pattern = {}
+    ages = []
+    superseded_frames = 0
+    superseded_total = 0
+    contiguous_frames = 0
+    v2_frames = 0
+    stalls = []   # dicts: rx, ms, phase, error, trial, pattern, cmds_global, idx_global, ctx
+    slow_all = 0
+    cmds_global = 0
+    idx_global = 0
+    last_seq = None
+    first_rx = None
+    last_rx = None
+    prev_cf_idx = {}   # pattern -> last displayed idx
+    pending_first = set()   # patterns whose next cf is the first after open
+    malformed = 0
+    lines = 0
+
+    with open_text(path) as f:
+        for raw in f:
+            raw = raw.strip()
+            if not raw:
+                continue
+            lines += 1
+            if raw[0] == "{":
+                try:
+                    obj = json.loads(raw)
+                except json.JSONDecodeError:
+                    malformed += 1
+                    continue
+                ev = obj.get("event")
+                if ev == "run_metadata":
+                    meta["firmware"] = obj.get("firmware")
+                    sd = obj.get("sd_card")
+                    meta["sd_card"] = sd.get("label") if isinstance(sd, dict) else sd
+                    meta["log_format"] = obj.get("log_format")
+                    meta["telemetry"] = obj.get("telemetry")
+                    meta["protocol"] = obj.get("protocol") or obj.get("protocol_name")
+                    meta["run_id"] = obj.get("run_id") or obj.get("id")
+                continue
+            if raw[0] != "[" or not raw.startswith('["c'):
+                continue
+            try:
+                arr = json.loads(raw)
+            except json.JSONDecodeError:
+                malformed += 1
+                continue
+            if not isinstance(arr, list) or len(arr) < 4:
+                malformed += 1
+                continue
+            tag, rx, t_us, seq = arr[0], arr[1], arr[2], arr[3]
+            if isinstance(rx, (int, float)):
+                first_rx = rx if first_rx is None else first_rx
+                last_rx = rx
+                if cur is not None:
+                    cur.rx_last = rx
+            # seq continuity (coverage)
+            if isinstance(seq, int):
+                is_boot = tag == "cs" and len(arr) >= 5 and arr[4] == 1
+                if last_seq is not None and not is_boot and seq != (last_seq + 1) & 0xFFFFFFFF:
+                    if cur is not None:
+                        cur.coverage.append("seq_gap")
+                last_seq = seq
+
+            if tag == "cs" and len(arr) >= 7:
+                kind, code, arg = arr[4], arr[5], arr[6]
+                if kind == 7 and code == 0:
+                    cur = Trial(len(trials) + 1, arg, rx, t_us)
+                    trials.append(cur)
+                    pending_first.add(arg)
+                    per_pattern[arg]["opens"] += 1
+                elif kind == 11:
+                    lay = {"contiguous": bool(code & 1), "exfat": bool(code & 2), "sectors_per_cluster": arg}
+                    if cur is not None:
+                        cur.layout = lay
+                        layout_by_pattern[cur.pattern] = lay
+                elif kind == 4:
+                    ms = arg / 10.0
+                    phase = SD_SLOW_PHASES[code & 3] if isinstance(code, int) else "unknown"
+                    err = bool(isinstance(code, int) and code & 0x80)
+                    slow_all += 1
+                    if cur is not None:
+                        cur.slow_reads += 1
+                        cur.max_read_ms = max(cur.max_read_ms, ms)
+                    if ms * 1000.0 > gap_us:
+                        st = {"rx": rx, "ms": ms, "phase": phase, "error": err,
+                              "trial": cur.index if cur else None, "pattern": cur.pattern if cur else None,
+                              "cmds_global": cmds_global, "idx_global": idx_global, "ctx": None}
+                        stalls.append(st)
+                        if cur is not None:
+                            cur.stalls.append((ms, phase))
+                elif kind == 12:
+                    if stalls and stalls[-1]["ctx"] is None:
+                        stalls[-1]["ctx"] = {"card_error_code": code, "irqstat_lo": arg}
+                elif kind == 13:
+                    if cur is not None:
+                        cur.reads_fw = arg
+                        per_pattern[cur.pattern]["reads_fw"] += arg
+                elif kind == 1:
+                    if cur is not None:
+                        cur.coverage.append("controller_reboot")
+                elif kind == 5:
+                    if cur is not None:
+                        cur.coverage.append("ring_overrun")
+            elif tag == "cc" and len(arr) >= 7:
+                cmd, status, req = arr[4], arr[5], arr[6]
+                if cmd == 0x70 and status == 0:
+                    cmds_global += 1
+                    idx = idx_from_req(req)
+                    if cur is not None:
+                        cur.cmds70 += 1
+                        per_pattern[cur.pattern]["cmds70"] += 1
+                        if idx is not None and idx != cur.last_idx:
+                            cur.index_changes += 1
+                            per_pattern[cur.pattern]["index_changes"] += 1
+                            idx_global += 1
+                            cur.last_idx = idx
+            elif tag == "cf" and len(arr) >= 8:
+                idx, pattern, sd_us, spi_us = arr[4], arr[5], arr[6], arr[7]
+                if not isinstance(sd_us, (int, float)):
+                    malformed += 1
+                    continue
+                per_pattern[pattern]["frames"] += 1
+                frame_count[pattern] = max(frame_count.get(pattern, 0), idx + 1)
+                if cur is not None:
+                    cur.frames += 1
+                    if cur.last_idx is None:
+                        cur.last_idx = idx   # the trial's initial frame: a 0x70 for it is not an index change
+                if pattern in pending_first:
+                    cls = "first-after-open"
+                    pending_first.discard(pattern)
+                else:
+                    cls = step_class(prev_cf_idx.get(pattern), idx, frame_count.get(pattern))
+                step_sd[pattern][cls].append(sd_us)
+                prev_cf_idx[pattern] = idx
+                if len(arr) >= 11 and isinstance(arr[8], (int, float)):
+                    v2_frames += 1
+                    age = arr[8]
+                    sup = arr[9] if isinstance(arr[9], int) else 0
+                    flags = arr[10] if isinstance(arr[10], int) else 0
+                    ages.append(age)
+                    if sup:
+                        superseded_frames += 1
+                        superseded_total += sup
+                    if flags & 2:
+                        contiguous_frames += 1
+                    if cur is not None:
+                        cur.superseded += sup
+                        cur.max_age_ms = max(cur.max_age_ms, age / 1000.0)
+                        if age > gap_us:
+                            cur.age_gaps += 1
+                        elif age > target_us:
+                            cur.over_target += 1
+
+    # clusters
+    clusters = []
+    for st in stalls:
+        if clusters and isinstance(st["rx"], (int, float)) and isinstance(clusters[-1][-1]["rx"], (int, float)) \
+                and (st["rx"] - clusters[-1][-1]["rx"]) / 1000.0 < CLUSTER_GAP_S:
+            clusters[-1].append(st)
+        else:
+            clusters.append([st])
+    cluster_rows = []
+    prev = None
+    for c in clusters:
+        first = c[0]
+        row = {
+            "t_s": _round((first["rx"] - first_rx) / 1000.0, 1) if first_rx is not None and isinstance(first["rx"], (int, float)) else None,
+            "trial": first["trial"], "pattern": first["pattern"], "n": len(c),
+            "ms": [_round(x["ms"]) for x in c], "phases": [x["phase"] for x in c],
+            "errors": sum(1 for x in c if x["error"]),
+            "since_prev_cmds": (first["cmds_global"] - prev["cmds_global"]) if prev else None,
+            "since_prev_index_changes": (first["idx_global"] - prev["idx_global"]) if prev else None,
+            "since_prev_s": _round((first["rx"] - prev["rx"]) / 1000.0, 1) if prev and isinstance(first["rx"], (int, float)) and isinstance(prev["rx"], (int, float)) else None,
+        }
+        cluster_rows.append(row)
+        prev = first
+    spacings_cmd = [r["since_prev_cmds"] for r in cluster_rows if r["since_prev_cmds"]]
+    spacings_idx = [r["since_prev_index_changes"] for r in cluster_rows if r["since_prev_index_changes"]]
+    spacings_s = [r["since_prev_s"] for r in cluster_rows if r["since_prev_s"]]
+
+    step_table = {}
+    for pattern, classes in step_sd.items():
+        step_table[pattern] = {}
+        for cls in STEP_CLASSES:
+            v = classes.get(cls)
+            if not v:
+                continue
+            step_table[pattern][cls] = {"n": len(v), "p50": _round(statistics.median(v), 0),
+                                        "p90": pct(v, 0.90), "p99": pct(v, 0.99), "max": max(v)}
+
+    reads_rows = {}
+    for pattern, c in per_pattern.items():
+        cmds = c["cmds70"]
+        reads_rows[pattern] = {
+            "opens": c["opens"], "cmds70": cmds, "index_changes": c["index_changes"],
+            "reads_fw": c["reads_fw"] or None, "frames": c["frames"],
+            "index_changes_per_cmd": _round(c["index_changes"] / cmds, 3) if cmds else None,
+            "reads_fw_per_cmd": _round(c["reads_fw"] / cmds, 3) if cmds and c["reads_fw"] else None,
+            "layout": layout_by_pattern.get(pattern),
+        }
+
+    duration_s = _round((last_rx - first_rx) / 1000.0, 1) if first_rx is not None and last_rx is not None else None
+    trial_rows = [t.row() for t in trials]
+    counts = Counter(r["status"] for r in trial_rows)
+    return {
+        "meta": meta, "lines": lines, "malformed": malformed, "duration_s": duration_s,
+        "gap_ms": gap_ms, "target_ms": target_ms,
+        "reads": reads_rows,
+        "step_cost_us": step_table,
+        "stalls": {
+            "slow_reads_total": slow_all, "over_threshold": len(stalls), "clusters": len(clusters),
+            "cluster_rows": cluster_rows,
+            "spacing_cmds": {"median": _round(statistics.median(spacings_cmd), 0) if spacings_cmd else None,
+                             "min": min(spacings_cmd) if spacings_cmd else None, "max": max(spacings_cmd) if spacings_cmd else None},
+            "spacing_index_changes": {"median": _round(statistics.median(spacings_idx), 0) if spacings_idx else None},
+            "spacing_s": {"median": _round(statistics.median(spacings_s), 1) if spacings_s else None},
+            "duration_hist_ms": dict(sorted(Counter(int(round(s["ms"])) for s in stalls).items())),
+            "phase_hist": dict(Counter(s["phase"] for s in stalls)),
+            "per_1e5_cmds": _round(len(clusters) * 1e5 / cmds_global, 2) if cmds_global else None,
+        },
+        "presentation": {
+            "v2_frames": v2_frames,
+            "req_age_us": {"p50": _round(statistics.median(ages), 0) if ages else None, "p90": pct(ages, 0.9),
+                           "p99": pct(ages, 0.99), "max": max(ages) if ages else None,
+                           "over_target": sum(1 for a in ages if a > target_us),
+                           "over_threshold": sum(1 for a in ages if a > gap_us)},
+            "superseded_frames": superseded_frames, "superseded_total": superseded_total,
+            "superseded_share": _round(superseded_frames / v2_frames, 3) if v2_frames else None,
+            "contiguous_share": _round(contiguous_frames / v2_frames, 3) if v2_frames else None,
+        },
+        "trials": trial_rows,
+        "trial_counts": dict(counts),
+        "flagged_trials": [r["trial"] for r in trial_rows if r["status"] == "fail"],
+    }
+
+
+def render_markdown(rep: dict) -> str:
+    m = rep["meta"]
+    out = [f"# telemetry-report — {m['file']}", ""]
+    out.append(f"firmware: `{m['firmware'] or '?'}` · sd_card: `{m['sd_card'] or '? (no 0xCD in this log)'}` · "
+               f"log: {m['log_format'] or '?'} · telemetry: {m['telemetry'] or '?'} · duration {rep['duration_s']} s · "
+               f"lines {rep['lines']} (malformed {rep['malformed']}) · thresholds: gap {rep['gap_ms']} ms, target {rep['target_ms']} ms")
+    out.append("")
+    out.append("## Reads accounting (per pattern)")
+    out.append("| pattern | opens | accepted 0x70 | index changes | fw reads (kind 13) | frames | idx-changes/cmd | fw reads/cmd | layout |")
+    out.append("|---|---|---|---|---|---|---|---|---|")
+    for p, r in sorted(rep["reads"].items(), key=lambda kv: str(kv[0])):
+        lay = r["layout"]
+        lay_s = "—" if not lay else ("contiguous" if lay["contiguous"] else "FRAGMENTED") + f", {lay['sectors_per_cluster']} spc" + (", exFAT" if lay["exfat"] else "")
+        out.append(f"| {p} | {r['opens']} | {r['cmds70']} | {r['index_changes']} | {r['reads_fw'] if r['reads_fw'] is not None else '—'} | {r['frames']} | {r['index_changes_per_cmd']} | {r['reads_fw_per_cmd'] if r['reads_fw_per_cmd'] is not None else '—'} | {lay_s} |")
+    out.append("")
+    out.append("## SD read cost by index step (sd_load_us of displayed frames)")
+    out.append("| pattern | step | n | p50 | p90 | p99 | max |")
+    out.append("|---|---|---|---|---|---|---|")
+    for p, classes in sorted(rep["step_cost_us"].items(), key=lambda kv: str(kv[0])):
+        for cls in STEP_CLASSES:
+            if cls in classes:
+                c = classes[cls]
+                out.append(f"| {p} | {cls} | {c['n']} | {c['p50']} | {c['p90']} | {c['p99']} | {c['max']} |")
+    out.append("")
+    s = rep["stalls"]
+    out.append(f"## Card stalls (reads > {rep['gap_ms']} ms): {s['over_threshold']} in {s['clusters']} clusters "
+               f"· {s['per_1e5_cmds']} clusters per 10⁵ accepted 0x70 · spacing median {s['spacing_cmds']['median']} cmds / "
+               f"{s['spacing_index_changes']['median']} index changes / {s['spacing_s']['median']} s · "
+               f"durations {s['duration_hist_ms']} · phases {s['phase_hist']}")
+    if s["cluster_rows"]:
+        out.append("| t (s) | trial | pattern | n | ms | phases | since prev (cmds / idx / s) |")
+        out.append("|---|---|---|---|---|---|---|")
+        for r in s["cluster_rows"]:
+            out.append(f"| {r['t_s']} | {r['trial']} | {r['pattern']} | {r['n']} | {r['ms']} | {','.join(r['phases'])} | "
+                       f"{r['since_prev_cmds']} / {r['since_prev_index_changes']} / {r['since_prev_s']} |")
+    out.append("")
+    pr = rep["presentation"]
+    if pr["v2_frames"]:
+        a = pr["req_age_us"]
+        out.append(f"## Request→presentation (ring v2, {pr['v2_frames']} frames): req_age p50 {a['p50']} µs · p90 {a['p90']} · "
+                   f"p99 {a['p99']} · max {a['max']} · over {rep['target_ms']} ms: {a['over_target']} · over {rep['gap_ms']} ms: {a['over_threshold']} · "
+                   f"superseded frames {pr['superseded_share']} ({pr['superseded_total']} loads never shown) · contiguous-path share {pr['contiguous_share']}")
+    else:
+        out.append("## Request→presentation: no ring-v2 FRAME fields in this log (firmware without sd_fastpath)")
+    out.append("")
+    out.append(f"## Trials: {rep['trial_counts']} · flagged {rep['flagged_trials']}")
+    out.append("| trial | pattern | dur s | 0x70 | idx chg | fw reads | frames | slow | max read ms | age gaps | max age ms | >target | superseded | coverage | status |")
+    out.append("|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|")
+    for t in rep["trials"]:
+        out.append(f"| {t['trial']} | {t['pattern']} | {t['duration_s']} | {t['cmds70']} | {t['index_changes']} | "
+                   f"{t['reads_fw'] if t['reads_fw'] is not None else '—'} | {t['frames']} | {t['slow_reads']} | {t['max_read_ms']} | "
+                   f"{t['age_gaps']} | {t['max_age_ms']} | {t['over_target']} | {t['superseded']} | {','.join(t['coverage']) or '—'} | **{t['status']}** |")
+    return "\n".join(out) + "\n"
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("paths", nargs="+", help="behavior_v2 log files (.jsonl / .jsonl.gz)")
+    ap.add_argument("--json", action="store_true", help="machine-readable JSON (list, one object per file)")
+    ap.add_argument("--gap-ms", type=float, default=10.0, help="fail threshold for a read / request age (default 10)")
+    ap.add_argument("--target-ms", type=float, default=5.0, help="target freeze reported as 'over target' (default 5)")
+    args = ap.parse_args(argv)
+    if args.gap_ms <= 0 or args.target_ms <= 0:
+        print("thresholds must be positive", file=sys.stderr)
+        return 2
+    reports = []
+    for p in args.paths:
+        if not os.path.isfile(p):
+            print(f"not a file: {p}", file=sys.stderr)
+            return 2
+        reports.append(analyze_file(p, args.gap_ms, args.target_ms))
+    if args.json:
+        json.dump(reports, sys.stdout, indent=1)
+        sys.stdout.write("\n")
+    else:
+        for r in reports:
+            sys.stdout.write(render_markdown(r))
+            sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/scripts/wedge-scan.py b/scripts/wedge-scan.py
index 969e42ea..cf05d774 100644
--- a/scripts/wedge-scan.py
+++ b/scripts/wedge-scan.py
@@ -85,6 +85,9 @@
     8: "wdog_context",  # code = EXC_RETURN low byte; arg bits 0-8 = stacked IPSR, bits 9-15 = prior isr_last
     9: "prev_isr_count",  # code = ISR id; arg = previous boot's entry count >> 12
     10: "timer_fail",  # IntervalTimer::begin() failed; arg = requested refresh rate
+    11: "sd_layout",  # after sd_open: code bit0 contiguous file, bit1 exFAT; arg = sectors/cluster (fw sd_fastpath)
+    12: "sd_slow_ctx",  # follows sd_slow: code = SdFat card errorCode(), arg = errorData() & 0xFFFF
+    13: "sd_reads",  # at STOP / next trial start: arg = readFrame calls while that pattern was open
 }
 ISR_NAMES = ["none", "refresh_timer", "spi_dma", "watchdog", "usb", "sdhc", "lpspi", "pit"]
 
@@ -430,6 +433,8 @@ def _ctl(self, arr, lineno: int) -> None:
             elif arr[4] == 9 and len(arr) >= 7 and isinstance(arr[5], int):
                 nm = ISR_NAMES[arr[5]] if arr[5] < len(ISR_NAMES) else f"isr_{arr[5]}"
                 kind = f"prev_isr_count({nm})"
+            elif arr[4] == 11 and len(arr) >= 7 and isinstance(arr[5], int):
+                kind = f"sd_layout({'contig' if arr[5] & 1 else 'FRAGMENTED'}, spc={arr[6]})"
             self.ctl_states[kind] += 1
         elif tag == "cc" and len(arr) >= 7 and arr[5] not in (0, None):
             self.ctl_cmd_rejects += 1
diff --git a/tests/test-arena-telemetry.js b/tests/test-arena-telemetry.js
index 644c88cb..d6a68192 100644
--- a/tests/test-arena-telemetry.js
+++ b/tests/test-arena-telemetry.js
@@ -34,8 +34,20 @@ function rec(type, seq, tUs, payload) {
     return [body.length + 1].concat(body);
 }
 const cmdRec = (seq, t, cmd, status, req) => rec(1, seq, t, [cmd, status, req.length].concat(req));
-const frameRec = (seq, t, idx, pat, sd, spi) =>
-    rec(2, seq, t, [].concat(u16(idx), u16(pat), u32(sd), u16(spi)));
+// v1 (20 B) when `v2` is omitted; ring-v2 (26 B: req_age_us u32, superseded u8, flags u8) otherwise.
+const frameRec = (seq, t, idx, pat, sd, spi, v2) =>
+    rec(
+        2,
+        seq,
+        t,
+        [].concat(
+            u16(idx),
+            u16(pat),
+            u32(sd),
+            u16(spi),
+            v2 ? u32(v2.age).concat([v2.sup, v2.flags]) : []
+        )
+    );
 const stateRec = (seq, t, kind, code, arg) => rec(3, seq, t, [kind, code].concat(u16(arg)));
 const padRec = (n) => [n, 0].concat(new Array(n - 2).fill(0));
 function block(h, records) {
@@ -207,6 +219,12 @@ function block(h, records) {
             ['state_change', 'SHOW_FRAME', 36]
         );
         check('no malformed', b.malformed, 0);
+        check('v1 frame has no req_age', b.records[1].reqAgeUs, undefined);
+        check(
+            'sd_slow (v1 code 0): phase unknown, read_us',
+            [b.records[2].phase, b.records[2].readUs, b.records[2].readError],
+            ['unknown', 129000, false]
+        );
         const rows = T.toRows(b, 1789000000000);
         check('rows', rows, [
             ['cc', 1789000000000, 1000, 10, 0x70, 0, '03704e00'],
@@ -214,6 +232,74 @@ function block(h, records) {
             ['cs', 1789000000000, 2000, 12, 4, 0, 1290],
             ['cs', 1789000000000, 2100, 13, 2, 4, 36]
         ]);
+        // Ring v2: 26 B FRAME + kinds 11-13 + sd_slow phase byte.
+        const b2 = T.parseBlock(
+            block({ tNowUs: 9000, firstSeq: 20 }, [
+                frameRec(20, 3000, 152, 36, 88700, 771, { age: 91200, sup: 3, flags: 0x03 }),
+                stateRec(21, 3100, 4, 0x82, 887), // sd_slow: body phase, read error, 88.7 ms
+                stateRec(22, 3200, 11, 0x01, 8), // sd_layout: contiguous, FAT32, 8 sectors/cluster
+                stateRec(23, 3300, 12, 0, 1), // sd_slow_ctx
+                stateRec(24, 3400, 13, 0, 24573) // sd_reads
+            ]),
+            Wire
+        );
+        check(
+            'v2 frame fields',
+            [
+                b2.records[0].reqAgeUs,
+                b2.records[0].superseded,
+                b2.records[0].sdRead,
+                b2.records[0].contiguous
+            ],
+            [91200, 3, true, true]
+        );
+        check('v2 frame req_age > 65 ms representable', b2.records[0].reqAgeUs > 65535, true);
+        check(
+            'sd_slow v2 phase/error',
+            [b2.records[1].phase, b2.records[1].readError, b2.records[1].readUs],
+            ['body', true, 88700]
+        );
+        check(
+            'sd_layout',
+            [
+                b2.records[2].stateName,
+                b2.records[2].contiguous,
+                b2.records[2].exfat,
+                b2.records[2].sectorsPerCluster
+            ],
+            ['sd_layout', true, false, 8]
+        );
+        check(
+            'sd_slow_ctx + sd_reads',
+            [
+                b2.records[3].stateName,
+                b2.records[3].cardErrorCode,
+                b2.records[4].stateName,
+                b2.records[4].reads
+            ],
+            ['sd_slow_ctx', 0, 'sd_reads', 24573]
+        );
+        check('v2 malformed = 0', b2.malformed, 0);
+        const rows2 = T.toRows(b2, 1);
+        check('v2 cf row carries 3 extra fields', rows2[0], [
+            'cf',
+            1,
+            3000,
+            20,
+            152,
+            36,
+            88700,
+            771,
+            91200,
+            3,
+            3
+        ]);
+        check('schema cf cols = 10', T.STREAM_SCHEMA.cf.cols.length, 10);
+        check(
+            'schema kinds 11-13 named',
+            [T.STATE_KINDS[11], T.STATE_KINDS[12], T.STATE_KINDS[13]],
+            ['sd_layout', 'sd_slow_ctx', 'sd_reads']
+        );
         checkBool(
             'status!=0 reply → null',
             T.parseBlock(Uint8Array.from([2, 1, 0xa9]), Wire) === null
diff --git a/tests/test-arena-wire-g6.js b/tests/test-arena-wire-g6.js
index f7a50055..d884929e 100644
--- a/tests/test-arena-wire-g6.js
+++ b/tests/test-arena-wire-g6.js
@@ -686,6 +686,79 @@ check('FIRMWARE_VERSION_PAYLOAD_BYTES', Wire.FIRMWARE_VERSION_PAYLOAD_BYTES, 46)
     check('flags bit 2 = telemetry ring (absent here)', v.telemetry, false);
     check('flags bit 3 = crash report / health v2 (absent here)', v.crashReport, false);
     check('flags bit 4 = free-running refresh timer (absent here)', v.freeRunningTimer, false);
+    check('flags bit 5 = SD fast path / GET_SD_INFO (absent here)', v.sdFastPath, false);
+    {
+        const p2 = payload.slice();
+        p2[3] = 0x3c; // telemetry + crashreport + freerun + sdfast, clean tree
+        const v2 = Wire.decodeFirmwareVersion(
+            Uint8Array.from([p2.length + 2, 0x00, 0xcb].concat(p2))
+        );
+        check(
+            'flags 0x3c decode',
+            [v2.telemetry, v2.crashReport, v2.freeRunningTimer, v2.sdFastPath, v2.dirty].join(','),
+            'true,true,true,true,false'
+        );
+        check('label suffixes', v2.label.endsWith(' freerun sdfast'), true);
+    }
+    // GET_SD_INFO (0xCD): 30 B fixture — SanDisk-style CID, 32 GB SDHC, FAT32, 32 KiB clusters.
+    {
+        checkBytes('encodeGetSdInfo', Wire.encodeGetSdInfo(), '01 cd');
+        const cid = [
+            0x03, 0x53, 0x44, 0x53, 0x43, 0x33, 0x32, 0x47, 0x80, 0x12, 0x34, 0xab, 0xcd, 0x01,
+            0x75, 0x01
+        ];
+        const sd = [1, 0x07, 3, 32].concat(
+            [0x00, 0xb0, 0xb9, 0x03], // 62,500,864 sectors = 32.0 GB
+            [0x00, 0x80, 0x00, 0x00], // 32 KiB clusters
+            cid,
+            [0xff, 0]
+        );
+        check('sd_info fixture is 30 bytes', sd.length, 30);
+        const si = Wire.decodeSdInfo(Uint8Array.from([sd.length + 2, 0x00, 0xcd].concat(sd)));
+        check(
+            'sd_info mounted/cid/csd',
+            [si.mounted, si.cidValid, si.csdValid].join(','),
+            'true,true,true'
+        );
+        check(
+            'sd_info manufacturer + name',
+            [si.manufacturer, si.oid, si.pnm, si.prv].join('|'),
+            'SanDisk|SD|SC32G|8.0'
+        );
+        check(
+            'sd_info serial + date',
+            [si.psnHex, si.mdtYear, si.mdtMonth].join(','),
+            '1234abcd,2023,5'
+        );
+        check(
+            'sd_info geometry',
+            [
+                si.cardTypeName,
+                si.fatTypeName,
+                si.capacityGB,
+                si.bytesPerCluster,
+                si.sectorsPerCluster
+            ].join(','),
+            'SDHC/SDXC,FAT32,32,32768,64'
+        );
+        check(
+            'sd_info label',
+            si.label,
+            'SanDisk SC32G 8.0 sn 1234abcd (2023-05) 32 GB SDHC/SDXC FAT32 32 KiB clusters'
+        );
+        const none = sd.slice();
+        none[1] = 0;
+        const sn = Wire.decodeSdInfo(Uint8Array.from([none.length + 2, 0x01, 0xcd].concat(none)));
+        check(
+            'sd_info status 1 (no card) still decodes',
+            [sn && sn.mounted, sn && sn.label].join(','),
+            'false,no card'
+        );
+        checkBool(
+            'sd_info short payload → null',
+            Wire.decodeSdInfo(Uint8Array.from([5, 0x00, 0xcd, 1, 0, 0])) === null
+        );
+    }
     check(
         'ISR names 4–7 (usb/sdhc/lpspi/pit)',
         Wire.HEALTH_ISR_NAMES.slice(4).join(','),
diff --git a/tests/test-telemetry-report.py b/tests/test-telemetry-report.py
new file mode 100644
index 00000000..6eb669ec
--- /dev/null
+++ b/tests/test-telemetry-report.py
@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+"""Offline tests for scripts/telemetry-report.py (SD-read cost / card-stall / trial-quality report).
+Synthetic behavior_v2 fixture with controller rows, generated in a temp dir. Wired into `pixi run test`.
+
+Run: python tests/test-telemetry-report.py
+"""
+import importlib.util
+import json
+import os
+import subprocess
+import sys
+import tempfile
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+SCRIPT = os.path.join(HERE, "..", "scripts", "telemetry-report.py")
+_spec = importlib.util.spec_from_file_location("telemetry_report", SCRIPT)
+tr = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(tr)
+
+total = 0
+failures = 0
+
+
+def check(name, got, expected):
+    global total, failures
+    total += 1
+    ok = got == expected
+    print(f"  {'PASS' if ok else 'FAIL'}  {name}" + ("" if ok else f" — got {got!r}, expected {expected!r}"))
+    if not ok:
+        failures += 1
+
+
+def req70(idx):
+    return "0370" + f"{idx & 0xff:02x}{idx >> 8:02x}"
+
+
+def build_fixture(v2=True):
+    """Two trials: pattern 36 (200 frames) with a stall cluster, pattern 5 clean."""
+    lines = [{"type": "frame_schema", "level": "behavior_v2", "cols": ["ms"], "t0": 1000000},
+             {"type": "log", "event": "run_metadata", "firmware": "200fada 2x10 2026-09-13 feat/sd-fastpath-2x10",
+              "sd_card": {"label": "SanDisk SC32G 8.0 sn 1234abcd (2023-05) 32 GB SDHC/SDXC FAT32 32 KiB clusters"},
+              "log_format": "behavior_v2", "telemetry": "ring-10hz", "ms": 1000000}]
+    seq = [100]
+    rx = [1000000]
+    t_us = [5_000_000]
+
+    def nxt(dt_ms=5):
+        seq[0] += 1
+        rx[0] += dt_ms
+        t_us[0] += dt_ms * 1000
+        return seq[0], rx[0], t_us[0]
+
+    def cs(kind, code, arg):
+        s, r, t = nxt()
+        lines.append(["cs", r, t, s, kind, code, arg])
+
+    def cc(idx, status=0):
+        s, r, t = nxt()
+        lines.append(["cc", r, t, s, 0x70, status, req70(idx)])
+
+    def cf(idx, pattern, sd, age=4700, sup=0, flags=3):
+        s, r, t = nxt()
+        row = ["cf", r, t, s, idx, pattern, sd, 770]
+        if v2:
+            row += [age, sup, flags]
+        lines.append(row)
+
+    # trial 1: pattern 36
+    cs(7, 0, 36)
+    cs(11, 1, 8)
+    cf(0, 36, 1978)                      # first-after-open
+    idx = 0
+    walk = [1] * 20 + [1, 1, -1, -1, 5, -5, 1, 1, 30, 1] * 5
+    reads = 1
+    for k, step in enumerate(walk):
+        cc(idx)                          # repeated index → no read (v2 semantics)
+        idx = (idx + step) % 200
+        cc(idx)
+        reads += 1
+        sd = 620 if step == 1 else (1996 if step < 0 else (1461 if step < 10 else 1956))
+        cf(idx, 36, sd, age=4700 if k != 30 else 12000, sup=1 if k == 30 else 0)
+    # stall cluster: 33 / 41 / 67 ms, body phase, then contexts
+    cs(4, 2, 330); cs(12, 0, 0)
+    cs(4, 2, 412); cs(12, 0, 0)
+    cs(4, 2, 671); cs(12, 0, 0)
+    cf(idx + 1, 36, 67100, age=69000)
+    cs(4, 2, 80)                          # 8 ms: slow by fw threshold, not over 10 ms
+    cs(13, 0, reads + 1)
+    # trial 2: pattern 5 (20 frames), clean, one repeated index
+    cs(7, 0, 5)
+    cs(11, 1, 8)
+    cf(0, 5, 598)
+    for k in range(1, 20):
+        cc(k)
+        cf(k, 5, 620)
+    cc(19)
+    cs(13, 0, 20)
+    lines.append({"type": "session", "event": "logging_stopped", "ms": rx[0]})
+    return lines
+
+
+def write(lines, path):
+    with open(path, "w") as f:
+        for ln in lines:
+            f.write(json.dumps(ln, separators=(",", ":")) + "\n")
+
+
+with tempfile.TemporaryDirectory() as d:
+    p = os.path.join(d, "fixture.jsonl")
+    write(build_fixture(), p)
+    rep = tr.analyze_file(p)
+
+    print("=== meta ===")
+    check("firmware", rep["meta"]["firmware"].startswith("200fada"), True)
+    check("sd_card label", rep["meta"]["sd_card"].startswith("SanDisk"), True)
+
+    print("=== reads accounting ===")
+    r36 = rep["reads"][36]
+    check("pattern 36 accepted cmds", r36["cmds70"], 2 * 70)
+    check("pattern 36 index changes (initial index not a change)", r36["index_changes"], 70)
+    check("pattern 36 fw reads", r36["reads_fw"], 72)
+    check("idx changes per cmd", r36["index_changes_per_cmd"], 0.5)
+    check("layout contiguous", r36["layout"], {"contiguous": True, "exfat": False, "sectors_per_cluster": 8})
+    check("pattern 5 index changes (repeat not counted)", rep["reads"][5]["index_changes"], 19)
+
+    print("=== step classes ===")
+    sc = rep["step_cost_us"][36]
+    check("+1 median", sc["+1"]["p50"], 620)
+    check("-1 median", sc["-1"]["p50"], 1996)
+    check("+2..9 median", sc["+2..9"]["p50"], 1461)
+    check("jump median", sc["jump>=10"]["p50"], 1956)
+    check("first-after-open", sc["first-after-open"]["n"], 1)
+
+    print("=== stalls ===")
+    st = rep["stalls"]
+    check("slow reads total (incl. 8 ms)", st["slow_reads_total"], 4)
+    check("over threshold", st["over_threshold"], 3)
+    check("one cluster", st["clusters"], 1)
+    check("cluster ms", st["cluster_rows"][0]["ms"], [33, 41.2, 67.1])
+    check("cluster phases", st["cluster_rows"][0]["phases"], ["body", "body", "body"])
+    check("cluster trial/pattern", (st["cluster_rows"][0]["trial"], st["cluster_rows"][0]["pattern"]), (1, 36))
+    check("duration hist", st["duration_hist_ms"], {33: 1, 41: 1, 67: 1})
+
+    print("=== presentation ===")
+    pr = rep["presentation"]
+    check("v2 frames counted", pr["v2_frames"] > 80, True)
+    check("req_age over threshold", pr["req_age_us"]["over_threshold"], 2)   # 12 ms + 69 ms
+    check("req_age max", pr["req_age_us"]["max"], 69000)
+    check("superseded frames", pr["superseded_frames"], 1)
+    check("contiguous share", pr["contiguous_share"], 1.0)
+
+    print("=== trials ===")
+    t = rep["trials"]
+    check("two trials", len(t), 2)
+    check("statuses", [x["status"] for x in t], ["fail", "pass"])
+    check("trial 1 stalls / age gaps / max read", (t[0]["stalls"], t[0]["age_gaps"], t[0]["max_read_ms"]), (3, 2, 67.1))
+    check("trial 1 reads_fw", t[0]["reads_fw"], 72)
+    check("trial 2 clean", (t[1]["stalls"], t[1]["slow_reads"], t[1]["cmds70"]), (0, 0, 20))
+    check("flagged", rep["flagged_trials"], [1])
+
+    print("=== v1 rows (no extras) ===")
+    p1 = os.path.join(d, "v1.jsonl")
+    write(build_fixture(v2=False), p1)
+    rep1 = tr.analyze_file(p1)
+    check("v1: no presentation fields", rep1["presentation"]["v2_frames"], 0)
+    check("v1: stalls still classify the trial", rep1["trials"][0]["status"], "fail")
+
+    print("=== CLI ===")
+    out = subprocess.run([sys.executable, SCRIPT, "--json", p], capture_output=True, text=True)
+    check("--json exit 0", out.returncode, 0)
+    check("--json parses", json.loads(out.stdout)[0]["stalls"]["clusters"], 1)
+    md = subprocess.run([sys.executable, SCRIPT, p], capture_output=True, text=True)
+    check("markdown mentions clusters", "1 clusters" in md.stdout, True)
+    bad = subprocess.run([sys.executable, SCRIPT, os.path.join(d, "missing.jsonl")], capture_output=True, text=True)
+    check("missing file → 2", bad.returncode, 2)
+
+print(f"\n{total - failures} / {total} checks passed")
+sys.exit(1 if failures else 0)
diff --git a/tests/test-trial-quality.js b/tests/test-trial-quality.js
new file mode 100644
index 00000000..618dae04
--- /dev/null
+++ b/tests/test-trial-quality.js
@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+/**
+ * Tests for js/trial-quality.js — per-trial pass/fail/unknown from ring records.
+ * Run: node tests/test-trial-quality.js
+ */
+'use strict';
+
+const TQ = require('../js/trial-quality.js');
+
+let total = 0;
+let failures = 0;
+function check(name, got, expected) {
+    total++;
+    const g = JSON.stringify(got);
+    const e = JSON.stringify(expected);
+    const ok = g === e;
+    console.log(`  ${ok ? 'PASS' : 'FAIL'}  ${name}${ok ? '' : ` — got ${g}, expected ${e}`}`);
+    if (!ok) failures++;
+}
+
+// record builders (the shapes js/arena-telemetry.js parseBlock() produces)
+let seq = 100;
+const S = (stateKind, code, arg, tUs, extra) =>
+    Object.assign({ kind: 'state', stateKind, code, arg, seq: seq++, tUs }, extra || {});
+const F = (idx, tUs, reqAgeUs, superseded) =>
+    Object.assign(
+        { kind: 'frame', idx, pattern: 36, sdLoadUs: 1200, spiUs: 770, seq: seq++, tUs },
+        reqAgeUs == null ? {} : { reqAgeUs, superseded: superseded || 0, flags: 3 }
+    );
+const C70 = (idx, tUs, status) => ({
+    kind: 'cmd',
+    cmd: 0x70,
+    status: status || 0,
+    req:
+        '0370' +
+        (idx & 0xff).toString(16).padStart(2, '0') +
+        (idx >> 8).toString(16).padStart(2, '0'),
+    seq: seq++,
+    tUs
+});
+
+console.log('=== idxFromReq ===');
+check('index from req hex', TQ.idxFromReq('03704e00'), 78);
+check('hi byte', TQ.idxFromReq('03700101'), 257);
+check('short → null', TQ.idxFromReq('0370'), null);
+
+console.log(
+    '\n=== three trials: pass / fail (stall) / fail (frame age), reads + cmd accounting ==='
+);
+{
+    const gaps = [];
+    const closed = [];
+    const q = TQ.createTrialQuality({
+        onGap: (g) => gaps.push(g),
+        onTrial: (t) => closed.push(t.index)
+    });
+    // trial 1: pattern 36, clean
+    q.feed([S(7, 0, 36, 1000), S(11, 1, 8, 1001)]);
+    q.feed([C70(1, 2000), F(1, 4000, 2000), C70(1, 6000), C70(2, 8000), F(2, 10000, 2500)]);
+    q.feed([S(4, 2, 80, 12000, { readUs: 8000, phase: 'body' })]); // 8 ms: slow by fw threshold, under 10 ms
+    q.feed([S(13, 0, 2, 13000, { reads: 2 })]); // reads while pattern 36 was open
+    // trial 2: pattern 5, one 41 ms stall
+    q.feed([
+        S(7, 0, 5, 20000),
+        C70(3, 21000),
+        S(4, 2, 412, 30000, { readUs: 41200, phase: 'body' }),
+        F(3, 31000, 43000, 1)
+    ]);
+    q.feed([S(13, 0, 1, 40000, { reads: 1 })]);
+    // trial 3: pattern 36, a FRAME whose request is 12 ms old (no sd_slow record — e.g. loop stall)
+    q.feed([S(7, 0, 36, 50000), C70(9, 51000), F(9, 63000, 12000, 0)]);
+    const s = q.finish();
+    check('closed order', closed, [1, 2, 3]);
+    check(
+        'statuses',
+        s.trials.map((t) => t.status),
+        ['pass', 'fail', 'fail']
+    );
+    check(
+        'trial 1 accounting',
+        [
+            s.trials[0].cmds70,
+            s.trials[0].index_changes,
+            s.trials[0].reads,
+            s.trials[0].frames,
+            s.trials[0].slow_reads,
+            s.trials[0].stalls
+        ],
+        [3, 2, 2, 2, 1, 0]
+    );
+    check('trial 1 max read 8 ms (recorded, not a fail)', s.trials[0].max_read_ms, 8);
+    check(
+        'trial 2 stall + frame age both flagged',
+        [
+            s.trials[1].stalls,
+            s.trials[1].age_gaps,
+            s.trials[1].max_read_ms,
+            s.trials[1].max_age_ms,
+            s.trials[1].superseded
+        ],
+        [1, 1, 41.2, 43, 1]
+    );
+    check(
+        'trial 3 frame age gap only',
+        [s.trials[2].stalls, s.trials[2].age_gaps, s.trials[2].max_age_ms],
+        [0, 1, 12]
+    );
+    check('counts', s.counts, { pass: 1, fail: 2, unknown: 0, open: 0 });
+    check('flagged trials', s.flagged_trials, [2, 3]);
+    check('worst gap us', s.worst_gap_us, 43000);
+    check(
+        'gap events',
+        gaps.map((g) => [g.event, g.trial, g.kind, g.ms, g.phase || g.idx]),
+        [
+            ['display_gap', 2, 'sd_slow', 41.2, 'body'],
+            ['display_gap', 2, 'frame_age', 43, 3],
+            ['display_gap', 3, 'frame_age', 12, 9]
+        ]
+    );
+}
+
+console.log('\n=== coverage → unknown, never pass; duplicates dropped; boot resets seq ===');
+{
+    seq = 500;
+    const q = TQ.createTrialQuality();
+    q.feed([S(7, 0, 36, 1000), C70(1, 2000)]);
+    const dup = C70(2, 3000);
+    q.feed([dup, dup]); // re-delivered record
+    check('duplicate dropped', q.current.cmds70, 2);
+    seq = 600; // a seq gap: records evicted before the drain
+    q.feed([C70(3, 4000)]);
+    q.noteCoverage('poller_paused', 'bridge not logging');
+    q.feed([S(7, 0, 5, 9000)]); // closes trial 1
+    // trial 2: clean, then a controller reboot (seq restarts)
+    q.feed([C70(1, 9500)]);
+    seq = 1; // fresh ring after a watchdog reset
+    q.feed([S(1, 0x80, 0, 100)]);
+    const s = q.finish();
+    check(
+        'trial 1 unknown with reasons',
+        [s.trials[0].status, s.trials[0].coverage],
+        ['unknown', ['seq_gap', 'poller_paused']]
+    );
+    check(
+        'trial 2 unknown after reboot',
+        [s.trials[1].status, s.trials[1].coverage],
+        ['unknown', ['controller_reboot']]
+    );
+    check('duplicates counted', s.duplicates_dropped, 1);
+    check('unknown trials listed', s.unknown_trials, [1, 2]);
+}
+
+console.log(
+    '\n=== v1 firmware records (no req_age, code 0 sd_slow) still classify by read time ==='
+);
+{
+    seq = 900;
+    const q = TQ.createTrialQuality();
+    q.feed([S(7, 0, 36, 1000), F(1, 2000), S(4, 0, 330, 3000), F(2, 4000)]); // arg 330 → 33 ms, phase unknown
+    const s = q.finish();
+    check(
+        'v1 stall flagged',
+        [s.trials[0].status, s.trials[0].stalls, s.trials[0].max_read_ms, s.trials[0].max_age_ms],
+        ['fail', 1, 33, 0]
+    );
+}
+
+console.log('\n=== reset() clears everything ===');
+{
+    const q = TQ.createTrialQuality();
+    q.feed([S(7, 0, 36, 1000)]);
+    q.reset();
+    check('empty after reset', q.summary().trials.length, 0);
+    check('threshold default', q.thresholdUs, 10000);
+}
+
+console.log(`\n${total - failures} / ${total} checks passed`);
+process.exit(failures ? 1 : 0);

From 204758ff419eeace02b296f3febb3b721b4e768d Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 11:26:54 -0400
Subject: [PATCH 02/67] fix(telemetry): decode sd_reads as arg << code and
 sd_slow_ctx as USDHC error bits (fw round-1 review changes); CLAUDE.md
 telemetry/stimulus-quality rule

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 CLAUDE.md                     |  9 +++++++++
 js/arena-telemetry.js         | 11 ++++++-----
 tests/test-arena-telemetry.js |  5 +++--
 3 files changed, 18 insertions(+), 7 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 299fa528..f6eeaf82 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -348,6 +348,15 @@ fix flows to every page automatically; two hand-written HTML pages never will.
   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.
+- **Controller telemetry rows + stimulus quality (v0.77, fw `sdfast`):** `cf` rows carry three OPTIONAL trailing fields
+  (`req_age_us`, `superseded`, `flags`) from ring-v2 firmware (0xCB flags bit 5) — readers must accept 8- or
+  11-element `cf` rows and STATE kinds 11–13 (`sd_layout`/`sd_slow_ctx`/`sd_reads`, reads = arg << code). `GET_SD_INFO`
+  0xCD is gated on 0xCB bit 5 only. Per-trial pass/flagged/unknown verdicts come from `js/trial-quality.js` (fed from
+  the drainer in ring order, dedup by seq; fail = any read or request age > 10 ms; `unknown` never becomes `pass`) →
+  `display_gap` + `trial_quality` run-log events; the Studio flags, never auto-excludes. Offline analysis:
+  `scripts/telemetry-report.py` (also reads the firmware repo's `scripts/sd_stall_test.py` logs). The card stalls
+  themselves are card-internal (read-count maintenance, ~24.5k reads of a large file); see
+  `docs/development/sd-read-jitter-2026-09-13.md`.
 - Bump the footer version/timestamp on every edit; never Prettier the HTML.
 
 - **Telemetry ring — four rules from the 2026-09-12 Codex review (all tested):** (1) the ONLY gate
diff --git a/js/arena-telemetry.js b/js/arena-telemetry.js
index 9dc3bbe8..a80d0a50 100644
--- a/js/arena-telemetry.js
+++ b/js/arena-telemetry.js
@@ -54,8 +54,8 @@
         9: 'prev_isr_count',
         10: 'timer_fail', // IntervalTimer::begin() failed: arg = requested refresh rate (Hz)
         11: 'sd_layout', // after sd_open: code bit0 contiguous file, bit1 exFAT; arg = sectors/cluster
-        12: 'sd_slow_ctx', // follows sd_slow: code = SdFat card errorCode(), arg = errorData() & 0xFFFF
-        13: 'sd_reads' // at STOP / next trial start: arg = readFrame calls while that pattern was open
+        12: 'sd_slow_ctx', // follows sd_slow: code = SdFat card errorCode() (sticky), arg = errorData() >> 16 (USDHC error bits)
+        13: 'sd_reads' // at STOP / next trial start: reads = arg << code (readFrame calls while that pattern was open)
     };
     // sd_slow (kind 4) code byte, ring v2: bits 0-1 = slowest phase of the read, bit 7 = read error.
     const SD_SLOW_PHASES = ['unknown', 'seek', 'body', 'tail'];
@@ -196,10 +196,11 @@
                     rec.sectorsPerCluster = rec.arg;
                 }
                 if (rec.stateKind === 12) {
-                    rec.cardErrorCode = rec.code;
-                    rec.irqstatLo = rec.arg;
+                    rec.cardErrorCode = rec.code; // sticky SdFat errorCode(): 0 = no driver error this boot
+                    rec.irqstatHi = rec.arg; // USDHC IRQSTAT bits 16-31 at the driver's LAST error
+                    rec.driverSawError = rec.code !== 0;
                 }
-                if (rec.stateKind === 13) rec.reads = rec.arg;
+                if (rec.stateKind === 13) rec.reads = rec.arg * Math.pow(2, rec.code); // code = binary shift
             } else {
                 rec.kind = 'unknown';
                 rec.raw = hex(m.subarray(p, p + plen));
diff --git a/tests/test-arena-telemetry.js b/tests/test-arena-telemetry.js
index d6a68192..5099a165 100644
--- a/tests/test-arena-telemetry.js
+++ b/tests/test-arena-telemetry.js
@@ -239,7 +239,7 @@ function block(h, records) {
                 stateRec(21, 3100, 4, 0x82, 887), // sd_slow: body phase, read error, 88.7 ms
                 stateRec(22, 3200, 11, 0x01, 8), // sd_layout: contiguous, FAT32, 8 sectors/cluster
                 stateRec(23, 3300, 12, 0, 1), // sd_slow_ctx
-                stateRec(24, 3400, 13, 0, 24573) // sd_reads
+                stateRec(24, 3400, 13, 3, 45000) // sd_reads: 45000 << 3 = 360000
             ]),
             Wire
         );
@@ -274,10 +274,11 @@ function block(h, records) {
             [
                 b2.records[3].stateName,
                 b2.records[3].cardErrorCode,
+                b2.records[3].driverSawError,
                 b2.records[4].stateName,
                 b2.records[4].reads
             ],
-            ['sd_slow_ctx', 0, 'sd_reads', 24573]
+            ['sd_slow_ctx', 0, false, 'sd_reads', 360000]
         );
         check('v2 malformed = 0', b2.malformed, 0);
         const rows2 = T.toRows(b2, 1);

From 4876330618f7c0098e23ebb53dabf8af825690a7 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 11:28:34 -0400
Subject: [PATCH 03/67] =?UTF-8?q?docs(sd):=20SD-read=20jitter=20+=20card-s?=
 =?UTF-8?q?tall=20evidence,=20corrections,=20what=20shipped,=20card=20prot?=
 =?UTF-8?q?ocol,=20read-free=20path=20(=C2=A76);=20bench=20log=20entry=20f?=
 =?UTF-8?q?or=20the=202026-09-13=20performance=20session?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/development/mode3-wedge-soak-plan.md     |  21 +++
 docs/development/sd-read-jitter-2026-09-13.md | 154 ++++++++++++++++++
 2 files changed, 175 insertions(+)
 create mode 100644 docs/development/sd-read-jitter-2026-09-13.md

diff --git a/docs/development/mode3-wedge-soak-plan.md b/docs/development/mode3-wedge-soak-plan.md
index 16d2a404..6a88f9bd 100644
--- a/docs/development/mode3-wedge-soak-plan.md
+++ b/docs/development/mode3-wedge-soak-plan.md
@@ -307,6 +307,27 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   3 % instead of P ≈ 0.0007, invariant-framed upstream fix); final texts await Michael. Handover for the
   performance session: `mode3-perf-handover-2026-09-13.md`. Controller left on `394dee45`, Studio connected idle.
 
+- **2026-09-13 09:53–11:30 ET — performance session (Claude, worktree `vigilant-tereshkova`, host branch
+  `claude/mode3-perf-sd` on #198; firmware `feat/sd-fastpath-2x10` on the ring branch, local).** Bench untouched so far
+  (Studio connected idle on `394dee45`, bridge + sim still up). Log analysis of the 75 ring-era files: per-read cost by
+  index step (+1 620 µs; non-sequential 1.18 ms grating / 1.46–2.0 ms bar — SdFat FAT-chain walk on backward seeks);
+  **the 30–90 ms stalls are card-internal**: 716 stalls / 197 clusters, quantised 23/33/41/67/89 ms, every ~48k accepted
+  0x70s at every rate, **712/716 while the 813 KB bar pattern was open** (24,573 bar reads between clusters, IQR
+  23.5–25.5k), position-dependent inside the file (frames 80–160 stall 1.5× the mean, frames 20–59 0.2×), unbroken
+  across the 16:45 power cycle; displayed-frame gap = stall + ~2 ms. Michael: acceptable freeze 5 ms target / 10 ms
+  worst case; ≥ 30 ms invalidates a trial; cards for comparison available later, not today. Codex plan review
+  (`.codex-review/report-20260913-1030-sd-stalls.md`): copy rotation withdrawn (conservation), FAT-cache explanation
+  corrected (separate FAT cache on ARM), u32 request age, screen ≠ qualify, current card is the untouched baseline.
+  Built + reviewed: fw `200fada` (contiguous O(1) seeks, same-index skip, sd_slow phase + ctx, sd_layout/sd_reads,
+  FRAME 26 B ring v2, GET_SD_INFO 0xCD, 0xCB bit 5) + `8968fb7` hygiene + `519d794` Codex round-1 fixes (skip requires
+  a running timer; presentation accounting on every transfer; provenance reset; USDHC error bits; sd_reads shift) +
+  `3c71953` `scripts/sd_stall_test.py`; host Studio v0.77 (`b96ea85`, `cfbe8a8`): trial-quality pass/flagged/unknown,
+  0xCD → `run_metadata.sd_card`, telemetry-report.py; all suites green. Read-free access-pattern research (agent +
+  Codex brainstorm): every course motion pattern except looming is an exact +1 px/frame roll; independent-frame LZ4
+  shrinks the 813 KB bar to 15 KB → complete compressed RAM cache loaded in the ITI is the recommended next step;
+  panel PSRAM write path is specified but unimplemented in panel firmware (`docs/development/sd-read-jitter-2026-09-13.md` §6).
+  Codex round 2 on the round-1 fixes running; flash follows its reconciliation.
+
 ## 11. T4 as built (2026-09-12) — soak with ring-buffer logging
 
 Decision (Michael, 11:30 ET): skip the instrument-dependent T2/T3 for now; build the ring (T1
diff --git a/docs/development/sd-read-jitter-2026-09-13.md b/docs/development/sd-read-jitter-2026-09-13.md
new file mode 100644
index 00000000..3a969dcc
--- /dev/null
+++ b/docs/development/sd-read-jitter-2026-09-13.md
@@ -0,0 +1,154 @@
+# SD-read jitter and card stalls in Mode 3 — evidence, corrections, what shipped, and the read-free path
+
+**Written:** 2026-09-13 (session after the fw #50 wedge campaign). **Status:** firmware `feat/sd-fastpath-2x10`
+(local, off `feat/telemetry-ring-2x10`) + webDisplayTools `claude/mode3-perf-sd` (stacked on PR #198) built;
+bench validation pending (§7 records it). **Reviews:** Codex gpt-6-astra plan review
+(`.codex-review/report-20260913-1030-sd-stalls.md` on the branch) and two firmware diff reviews; the
+"alternative perspective" brainstorm on read-free access patterns is summarised in §6.
+
+## 1. The question this answers
+
+Michael's request: reduce jitter *inside* the SD frame read (no RAM-preload work-around); then, once the data
+showed 30–90 ms display freezes, treat those as the first-class problem — is it the card, would another card
+fix it, and could a different access pattern avoid the reads altogether? Acceptable display freeze:
+**5 ms target, 10 ms worst case; ≥ 30 ms is a visible stimulus artifact and should invalidate a trial.**
+
+## 2. Evidence (75 ring-era soak logs, 9.9 M accepted 0x70s, 2026-09-12/13)
+
+### 2.1 Per-read cost by index step (`cf.sd_load_us`, fix build `394dee45`, run 01:40)
+
+| step class | 20-frame grating (81 KB) | 200-frame bar (813 KB) |
+|---|---|---|
+| +1 sequential | 620 µs | 621 µs |
+| forward jump 2–9 | 1181 µs | 1461 µs |
+| backward −1 / −2..−9 | 1182 µs | 1996 µs |
+| jump ≥ 10 | 1191 µs | ~1960 µs |
+
+A +1 step continues the card's open CMD18 stream. Every other step pays one stream restart (≈ 0.55 ms of card
+latency, irreducible for random access). The bar pattern's extra 0.3–0.8 ms is SdFat's `FatFile::seekSet`
+re-walking the FAT chain from the first cluster on backward seeks; **correction from review:** the ARM build
+keeps a separate FAT cache (`USE_SEPARATE_FAT_CACHE 1`), so the cost is the chain walk crossing FAT sectors
+(implies small clusters on this card — the `sd_layout` record now reports sectors/cluster), not data-read
+eviction as first written.
+
+### 2.2 The card stalls
+
+- 716 reads > 20 ms in 197 clusters; durations quantised 23/33/41/67/89 ms; a cluster = 3–4 stalls within
+  ≤ 0.5 s (≈ 160–180 ms of card time). **Displayed-frame gap = stall + ~2 ms** (measured). Worst 96 ms, i.e.
+  just under the SD spec's 100 ms read timeout.
+- Count-triggered, not time-triggered: every ~48k accepted 0x70s at 100, 200 and 286 Hz alike.
+- **Per file:** 712/716 stalls while the 813 KB bar pattern was open, 4 while the 81 KB grating was open, at
+  equal read shares (2.69 M vs 2.70 M reads). Reads of the bar pattern between clusters: **24,573 (IQR
+  23.5–25.5k, n = 107)**.
+- Stalls attach to non-sequential reads (+1 steps: 7 of 395 — the card acts at a new command boundary);
+  position in the file matters: stall/read ratio by 20-frame bin = 0.47/0.26/0.17/0.86/1.54/1.35/1.54/1.67/
+  1.20/0.95 with uniform reads (a 3–6× difference between the first ~250 KB and the rest).
+- The interval sequence is unbroken across MCU resets and the 16:45 power cycle — the counter lives in the card.
+- Impact: at 200 Hz roughly one 60 s bar-pattern trial in four contains a cluster; at 100 Hz about one in ten.
+
+### 2.3 What is inferred, not proven
+
+Card-internal read-disturb / block-refresh maintenance keyed to reads of the region holding the big file.
+Vendors document exactly this mechanism (ATP: "after ~100,000 read cycles… AutoRefresh"; Swissbit: "read
+commands are monitored and the content is refreshed"; Kingston: "auto-refresh read disturb protection") but no
+vendor publishes the stall duration, and no public long-run per-card read-latency data exists. The small file's
+immunity is **not** explained by a per-block read counter alone (candidates: the card's read cache serves an
+81 KB working set; SLC vs TLC placement; block geometry). `readFrame` timing wraps seek + data + CRC and does
+not by itself identify the SD transaction; logical offset is not a NAND address. The instrumentation that
+shipped (§4) is what turns these into measurements.
+
+## 3. What was rejected and why
+
+- **Copy rotation** (k copies of the file, rotate per trial): k copies each refresh k× less often, but there are
+  k of them — the same number of stalls per read. Conservation argument; all three reviewers agreed.
+- **Whole-pattern RAM preload as first proposed:** the controller has **no external PSRAM** (hardware BOM +
+  `.bss.extram = 0`); 390 KiB of free OCRAM2 holds at most 97 uncompressed GS16 frames. (Compressed or
+  synthesised residency is a different matter — §6.)
+- **Deferring the card's maintenance from the host:** SD 6.0 §4.18 does define maintenance windows
+  (Performance Enhancement register, CMD48/49, A2 cards), but SdFat's SDIO driver has no ACMD13/CMD48/49
+  support, the spec does not require a card to defer read-disturb refresh to the window, and the only hard bound
+  is the 100 ms read timeout. Worth a capability probe later, not a plan.
+
+## 4. What shipped today (firmware `feat/sd-fastpath-2x10`, host `claude/mode3-perf-sd`)
+
+Firmware (0xCB flags **bit 5 `sdfast`**; ring layout **v2**):
+- **A — O(1) seeks:** pattern held as an SdFat `FsFile`, `contiguousRange()` once at open (sets
+  `FILE_FLAG_CONTIGUOUS` → arithmetic seeks); fragmented file → old path; `STATE(sd_layout)` says which +
+  sectors/cluster. Target: bar non-sequential medians ≈ 1.18 ms, p99 ≤ 1.6 ms.
+- **B — same-index skip:** a `SET_FRAME_POSITION` for the index already in `frame_buf_` (loaded by a successful
+  `loadFrame`, not overwritten since, refresh timer running) is answered without an SD read (~24 % of
+  closed-loop commands; effect on stall rate is measured, not claimed).
+- **Attribution:** `readFrame` times seek / body / trailer; `sd_slow` threshold 20 → **10 ms**, code byte = slowest
+  phase (+ error flag); `sd_slow_ctx` (kind 12) = SdFat `errorCode()` (sticky) + USDHC IRQSTAT error bits;
+  `sd_reads` (kind 13) = reads while the pattern was open (`arg << code`).
+- **FRAME 20 → 26 B:** `req_age_us` u32 (0x70 dispatch → SPI start; u32 so a 90 ms stall is representable),
+  `superseded` (buffers replaced before any transfer, counted on every transfer), `flags` (bit0 SD read, bit1
+  contiguous). Ring `kVersion` 2: a kept v1 ring re-initialises at boot instead of being truncated — drain first.
+- **`GET_SD_INFO` 0xCD** (30 B): CID/CSD identity, card + FAT type, capacity, cluster size — every measurement is
+  attributable to a physical card.
+- Hygiene: NVIC enable-state preserved in `disarmRefreshTimer`; `armRefreshTimer` returns bool and uses
+  `IntervalTimer::update()` for rate changes; 0x16/0x70/trial start refuse a display state without a timer;
+  `platform = teensy@5.1.0`; dead duplicate and stale comment removed.
+- `scripts/sd_stall_test.py`: browser-free card-comparison driver writing behavior_v2 rows + inline summary.
+
+Host (Studio v0.77):
+- ring-v2 decode (`cf` rows gain three optional fields; kinds 11–13), 0xCB bit 5, 0xCD decode → `run_metadata.sd_card`;
+- **`js/trial-quality.js`**: per-trial **pass / flagged / unknown** from ring records in seq order (fail = read or
+  request age > 10 ms; coverage gaps → unknown, never pass; dedup by seq) → `display_gap` and `trial_quality`
+  run-log events + banner. Flag only; exclusion/repeat is the experimenter's decision.
+- drainer per-poll budget 40 → 200 chunks (background-tab polling could not keep up with 26 B FRAMEs);
+- `scripts/telemetry-report.py`: reads accounting, step-class cost table, stall clusters with spacing in commands /
+  index changes / seconds, request→presentation percentiles, per-trial verdicts — for Studio and stall-test logs.
+
+## 5. Card characterisation protocol (cards available later; the tooling is ready)
+
+- **Never reformat the current card**: it is the baseline (identity via 0xCD). Screen candidates on other cards.
+- One frozen firmware build for all comparisons.
+- **Working-set test on the current card first** (no new files): `sd_stall_test.py --window 50 / 100 / 200`
+  on the bar pattern → does a 50-frame working set inside the same file stall? (H-cache vs H-placement.) A GS2
+  control pattern later (bytes vs reads).
+- **Screening** (per card, ~25 min): FAT32 formatted on a PC (the Studio's purge → `SD.format()` → exFAT above
+  32 GiB), the two soak patterns uploaded through the Studio, one 20-min run at 200 Hz (≈ 5 baseline cycles).
+  Zero clusters is a *screen pass* (95 % upper bound ≈ 3/exposure), not a qualification.
+- **Qualification** of a screen-passer: ≥ 3 h continuous (≈ 40 baseline cycles), a second specimen, after
+  representative upload/delete/idle history; report clusters per 10⁵ reads, max stall, affected-trial rate.
+  Candidates: SanDisk Industrial (SDSDQAF3), Kingston Industrial SDCIT2 (pSLC), Swissbit S-56u (pSLC), Samsung
+  PRO Endurance; exact SKU + capacity recorded.
+
+## 6. The read-free path (Michael's question: can a different access pattern prevent the reads?)
+
+Two independent probes (a code/patterns research pass and a Codex gpt-6-astra brainstorm) converged.
+
+**What the actual course patterns look like** (`cshl-2026-course/patterns/`, 45 files): every motion pattern
+except the looming ones is an **exact +1 px/frame azimuthal roll of frame 0** (heisenberg/bar/edge/checker/
+grating families; 100 or 200 distinct frames); the looming discs/annuli are 75 frames = 305 KB (48 distinct).
+Compression: whole file zlib 1–4 %; **independent-frame LZ4: 200-frame bar 813 KB → 15 KB, 20-frame grating →
+1 KB, even a 2,000-frame sine → 374 KB**; byte-RLE is useless for gratings/checkers.
+
+| option | mechanism | in-trial SD reads | latency | cost | status |
+|---|---|---|---|---|---|
+| **R1 Complete compressed RAM cache** (independent-frame LZ4 or per-frame zlib, offset table; loaded + CRC-validated in the inter-trial interval; hard "no SD during trial" invariant; fallback = today's path with a loud flag) | pattern fits 390 KiB compressed (all course patterns do, by 10–100×) | **none** | decode (budget ≤ 0.5 ms, measure) + 0.77 ms SPI | 2–4 days fw | **recommended first** (Codex + this session) |
+| R2 Declared shift synthesis (base frame + step, index → transform) | pattern declared as an exact roll (manifest or v3 header; v2 header has no free byte) | none | repack + 0.77 ms | 2–5 days | special case of R1's coverage; keeps RAM at 4 KB; needs a declaration path |
+| R3 Panel-resident PSRAM | panel fw implements the specified `0x3F` write / `0x2F` status / `0x4F` mark-loaded (today only display `0x50–0x63` exists; 16- vs 24-bit index drift) | none | 0.02 ms index transport + panel latency; upload ≈ 160 ms per 200-frame pattern (both buses), ~5 s for the whole course library at power-on (not persistent) | 5–10 days panel + controller | the architectural exit; also removes the 0.77 ms transfer |
+| R4 Onboard NOR flash (Teensy 4.1 8 MB program flash, `PROGMEM` / `LittleFS_Program` region) | reserve ~1 MiB per pattern; no erase/program during trials | none | flash copy + 0.77 ms (cold-read timing to measure) | 1–2 days proof | fallback for incompressible images |
+| R5 Host streams frame data (`0x32`, already implemented) | host has the pattern; USB 0.8 MB/s at 200 Hz (high-speed CDC is fine) | none | USB queueing + 0.77 ms; host stalls unbounded | 0.5–2 days experiment | **cheapest discriminating experiment**: removes SD without new firmware |
+| R6 Partial cache / chunk LRU / prefetch | locality | reduced, not zero; a miss still exposes 90 ms | — | 1–4 days | rejected as a solution (misses land inside trials) |
+| R7 Reachable-set cache | max step ±1 during a 90 ms outage → 19/37/53 frames at 100/200/286 Hz | hides a stall only if no jump lands in the window (8–23 % chance per stall) | — | needs async SD | partial answer; not for the current architecture |
+
+Key reasoning: a card stall during a **preload in the inter-trial interval** merely delays a trial start by
+≤ 100 ms; the same stall during the trial is a 90 ms freeze. Moving every read out of the trial is the
+mitigation that does not depend on the card. R1 covers the current course library outright (the 305 KB looming
+patterns even fit uncompressed) and degrades gracefully to R4/R5 for incompressible images. R3 remains the
+long-term direction because it also removes the 4 KB SPI transfer per frame.
+
+Bench-afternoon sequence proposed by the brainstorm and adopted for the next session: (1) baseline clusters on
+the unchanged card with the new instrumentation (today), (2) `0x32` streaming at 100/200/286 Hz from the real
+host (does removing SD remove the failure? does USB meet the deadline?), (3) resident-decode proof on the
+Teensy (bar pattern: decode all 200 frames, verify CRCs, max decode cycles; random indices from RAM with SD
+disabled), (4) command-count vs transferred-volume discrimination (same sector trace, different transaction
+grouping; hot vs quiet window), (5) maintenance-capability probe and flash-region sizing.
+
+## 7. Bench results (filled in as they arrive)
+
+_See `mode3-wedge-soak-plan.md` §10 for the timestamped log; summary table to be added after the control
+iteration on the new build._

From 384da8947fed69f3ca868e1b9045e8d43282ad5c Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 11:48:06 -0400
Subject: [PATCH 04/67] docs: telemetry review handoff (what is logged,
 three-clock model + evidence, round-trip recipe, Teensy-only timing
 proposals, next experiments); bench log: flash, HIL, card identity, soak
 restart, first look

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/development/mode3-wedge-soak-plan.md     |  31 ++++
 .../telemetry-review-handoff-2026-09-13.md    | 172 ++++++++++++++++++
 2 files changed, 203 insertions(+)
 create mode 100644 docs/development/telemetry-review-handoff-2026-09-13.md

diff --git a/docs/development/mode3-wedge-soak-plan.md b/docs/development/mode3-wedge-soak-plan.md
index 6a88f9bd..b90378d6 100644
--- a/docs/development/mode3-wedge-soak-plan.md
+++ b/docs/development/mode3-wedge-soak-plan.md
@@ -328,6 +328,37 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   panel PSRAM write path is specified but unimplemented in panel firmware (`docs/development/sd-read-jitter-2026-09-13.md` §6).
   Codex round 2 on the round-1 fixes running; flash follows its reconciliation.
 
+- **2026-09-13 11:35:07–11:35:13 ET — flashed `3c71953` (SD fast path build) via the bootloader route** after Michael
+  disconnected the old Studio tab (port free; HalfKay immediate; CDC back in 6 s; no button). Codex round 2 on the
+  round-1 fixes: firmware accepted, harness findings deferred (`.codex-review/report-20260913-fw-sdfast-rounds.md` in
+  the ring worktree). HIL subset (version/health/telemetry) run with the port free before the Studio reconnects.
+
+- **2026-09-13 11:36–11:48 ET — HIL on `3c71953` (port free):** version/health/telemetry: same-index skip verified
+  (3 repeated 0x70s → cmd70 +3, sd_reads +0), frame storm: 26 B FRAMEs, `sd_layout` + trailing `sd_reads` after
+  ALL_OFF as designed (needed an 81 KB grating uploaded as `conftest.pat`, deleted again; listing back to 45 files,
+  idx 36/5 unchanged). **Card identity (0xCD): MID 0x00, OEM "42", PNM `SD8GB`, PRV 0.0, PSN 0x14d4, made 2025-06,
+  8.0 GB SDHC, FAT32, 4 KB clusters (8 sectors/cluster)** — an unbranded 8 GB card; the 4 KB clusters (≈ 200-cluster
+  chain for the 813 KB pattern → two FAT sectors) are what made the backward-seek FAT walk cost ~0.5 ms. Two unrelated
+  failures noted, not chased: `test_crashreport_passthrough` (PJRC CrashReport region holds junk after the HalfKay
+  reflash, len 35340264) and `test_overfill_evicts_oldest_and_reports_dropped` (ring_overrun marker position, timing
+  sensitive). Next: Studio v0.77 on :8092 connects (user gesture), soak protocol rebuilt, 2 iterations.
+
+- **2026-09-13 11:45 ET — soak restarted on `3c71953`** from Studio v0.77 (worktree served on :8092; new origin →
+  Michael clicked Connect once). Protocol `soak_mode3_card.yaml` rebuilt from the repo soak protocol (ids 36/5, frames
+  200/20 via the `__framesRepatch` hook), rig set explicitly to `cshl_g6_2x10_ball` (the page derived `g6_3x10`; the
+  mismatch chip still reads "bench ≠ protocol" — cosmetic, to check), advanced mode forced on the new origin,
+  `startSoak({iterations:2, gapS:10, firstFault:'halt', policy:'reset-continue'})`; sim 200 Hz + 90° jumps unchanged,
+  bridge 3.1 logging behavior_v2. This is the CONTROL iteration on the new build (same card, same workload).
+
+- **2026-09-13 11:46 ET — first look at the control iteration (66 s snapshot, `telemetry-report.py`):** fw reads per
+  accepted 0x70 = **0.755** (8,972 reads / 11,884 commands on the bar — the same-index skip removes the 24 % as
+  predicted); bar pattern non-sequential reads now **all ≈ 1.46 ms** (−1 was 2.00 ms: the FAT-walk penalty is gone;
+  +2..9 unchanged at 1.44; jumps 1.96 → 1.46); grating non-sequential 1.18 ms as before; +1 sequential 620 µs both.
+  Bar (813 KB) still costs ~280 µs more per random read than the grating (81 KB) with identical code paths → consistent
+  with the card serving part of the small working set from its own cache (the H-cache reading of the small file's
+  stall immunity). `req_age_us` (0x70 dispatch → SPI start) p50 1.77 ms, p99 2.56 ms, max 2.56 ms; superseded 1.2 %
+  of frames. No stall yet in 66 s (expected spacing ~250 s). Layout: contiguous, 8 sectors/cluster, both patterns.
+
 ## 11. T4 as built (2026-09-12) — soak with ring-buffer logging
 
 Decision (Michael, 11:30 ET): skip the instrument-dependent T2/T3 for now; build the ring (T1
diff --git a/docs/development/telemetry-review-handoff-2026-09-13.md b/docs/development/telemetry-review-handoff-2026-09-13.md
new file mode 100644
index 00000000..7ed109ba
--- /dev/null
+++ b/docs/development/telemetry-review-handoff-2026-09-13.md
@@ -0,0 +1,172 @@
+# Handoff — telemetry review session: what is logged now, how the three clocks relate, how to measure round-trip latency, and what to test next (Teensy-only timing)
+
+**Written:** 2026-09-13 (performance session, Studio v0.77 / firmware `feat/sd-fastpath-2x10` `3c71953`).
+**For:** a review session that does NOT implement anything. Deliverables of that session: (1) an authoritative
+"what gets logged" reference (the pieces below are scattered over five docs and three code bases); (2) a
+timestamp/clock model for FicTrac → bridge → Studio → controller with the evidence for each edge; (3) a
+round-trip-latency measurement plan; (4) the next experiments, favouring measurements the Teensy can make on
+its own (no Analog Discovery, no Saleae). **Michael's acceptance numbers:** display freeze 5 ms target, 10 ms
+worst case; ≥ 30 ms is a visible artifact.
+
+Read in this order: this file → `telemetry-performance-handover-2026-09-12.md` §4–§6 (log format as of the
+ring's first night) → `sd-read-jitter-2026-09-13.md` (what changed today and why) → firmware README
+"Telemetry ring", "Health + breadcrumb", "Free-running refresh timer", "SD fast path" sections (ring
+worktree `/Users/reiserm/Documents/GitHub/LED-Display_G6_Firmware_Arena-ring/README.md`) →
+`controller-telemetry-ring-buffer-proposal.md` (the original design + §8 clock fit, §9 instrument plan).
+
+---
+
+## 1. The three systems and what each one stamps
+
+| system | clock | what it stamps | where it lands |
+|---|---|---|---|
+| **FicTrac (or `fictrac_sim.py`)** | camera hardware clock (real rigs: col 22 in ns, converted to ms by the bridge; sim: `frame × dt_ms`, monotonic from 0) | one row per tracked frame: `fc` frame counter, `ft` col-22 timestamp, heading, x/y | behavior_v2 frame rows `[ms, fc, idx, ft, x, y, hd]` |
+| **bridge** (`fictrac-bridge/bridge.py` 3.1, Python, same machine as the browser) | `time.time()` wall clock, epoch ms | `ms` = bridge receipt of the FicTrac packet; `rx_off` = bridge receipt of a Studio echo; `rx` = bridge receipt of a drained ring block; `t0` in `frame_schema` = log origin (epoch ms) | every row it writes; `frame_schema.t0`; `log_control_ack` |
+| **Studio** (browser, `js/arena-session.js`) | `Date.now()` epoch for stamps, `performance.now()` for durations | `t_off` = `Date.now() − t0` when the command is SENT; `dt` = monotonic round trip **including queue wait** (single-flight link) | `["a", t_off, dt, hex, status, rx_off(, error)]` |
+| **controller** (Teensy, `micros()` u32, wraps every 71.6 min) | `t_us` | CMD record: dispatch entry of every command; FRAME record: **start of the SPI transfer** of a displayed frame change; STATE records: at the event; 0xA9 block header `t_now_us`: reply time | ring records → `cc` / `cf` / `cs` rows (`rx` = bridge receipt of the DRAIN, not of the event) |
+
+Known relationships (measured): host↔controller drift **−3 ppm** (fit of `a`-row send time vs `cc.t_us` paired by
+order, 2026-09-12); Chrome background-tab throttling quantises timers to ~1 s (night 1). Missing today: **no field
+links a FicTrac frame (`fc`) to the 0x70 it produced** — the bridge client coalesces frames (newest index wins,
+`FicTracBridgeClient._drain`) and the `a` row carries only the request bytes. That is the first gap to close if
+end-to-end latency (FicTrac frame → LED) is wanted (§4).
+
+## 2. What gets logged, by layer (as of Studio v0.77 + fw 3c71953)
+
+### 2.1 Bridge log file (behavior_v2 NDJSON, one file per run / soak iteration, rotated by `log_control`)
+
+- Line 1 `{"type":"frame_schema","level":"behavior_v2","cols":[…],"arena_cols":["t_off","dt","hex","status","rx_off"],"t0":<epoch ms>}`.
+- FicTrac rows `[ms, fc, idx, ft, x, y, hd]` (numbers first). `idx` = the frame index the bridge derived
+  (gain × heading, wrapped modulo the trial's `frames` — pushed by the runner per trial via `config`).
+- Host echoes `["a", t_off, dt, "03 70 lo hi", status|null, rx_off(, "error")]` for every arena command
+  (0x70 stream + protocol commands); requests > 8 B (TRIAL_PARAMS) fall back to the v1 `arena_command` object.
+- Controller ring rows, in **ring `seq` order** (never sort by `rx`/`t_us`):
+  - `["cc", rx, t_us, seq, cmd, status, "reqhex"]` — every command the controller dispatched (except 0xA9);
+    `reqhex` = first ≤ 8 request bytes incl. `len cmd` (so `03 70 4e 00` → index 78); `status` = the reply's status.
+  - `["cf", rx, t_us, seq, idx, pattern, sd_load_us, spi_us, req_age_us, superseded, flags]` — a displayed frame
+    CHANGE (held frames are not recorded). Last three fields are **ring v2 only** (fw 0xCB bit 5): `req_age_us` =
+    dispatch of the 0x70 that requested this frame (or the `loadFrame` decision in Mode 2/4) → SPI start, u32;
+    `superseded` = SD frames loaded into the buffer but replaced before any transfer since the last FRAME record;
+    `flags` bit0 SD read, bit1 contiguous-file fast path.
+  - `["cs", rx, t_us, seq, kind, code, arg]` — STATE: 1 boot (code = reset cause, arg = prev breadcrumb), 2 state_change,
+    3 error_glyph, **4 sd_slow** (arg = read µs/100; threshold **10 ms** on v2 (20 ms on v1); v2 code bits 0-1 = slowest
+    phase 1 seek / 2 body / 3 CRC trailer, bit7 = read error), 5 ring_overrun, 6 telemetry, 7 sd_open (arg = pattern),
+    8 wdog_context, 9 prev_isr_count, 10 timer_fail, **11 sd_layout** (code bit0 contiguous, bit1 exFAT; arg =
+    sectors/cluster), **12 sd_slow_ctx** (code = SdFat sticky errorCode, arg = USDHC IRQSTAT bits 16-31 at the last
+    driver error), **13 sd_reads** (reads while the pattern was open, `arg << code`).
+- Events (JSON objects): `run_metadata` (protocol, rig, `firmware` = 0xCB label, **`sd_card`** = 0xCD identity
+  {manufacturer, pnm, prv, psn_hex, mdt, capacity_gb, card_type, fat, bytes_per_cluster, cid_hex, label},
+  `telemetry` ring-10hz|off, `log_format`, `gap_threshold_ms`, `soak{…}`), `stream_schema` (the cc/cf/cs columns +
+  kind names), `runner` phases, `soak` phases (`iteration-end` carries `applied_0x70`, drainer stats),
+  **`display_gap`** (trial, pattern, seq, t_us, ms, kind sd_slow|frame_age, phase/idx) and **`trial_quality`**
+  (per-trial table + counts, at run end), `probe` / `telemetry_dump` / `crash_report` (post-mortem),
+  `health` snapshots, `soak_note`.
+- Analyzers: `scripts/wedge-scan.py` (faults, RTT, controller states), **`scripts/telemetry-report.py`** (reads
+  accounting, SD cost by step class, stall clusters with spacing in commands/index changes/seconds,
+  request→presentation percentiles, per-trial pass/flagged/unknown), `js/runlog-format.js` readers skip tagged rows.
+
+### 2.2 Controller-side, on demand (not streamed)
+
+- `GET_HEALTH` 0xCA (v5, 114 B): uptime, loop max, sd_reads / sd_read_max_us / last_sd_read_us, frames, ISR counters,
+  cmd70_count, state, reset cause, reset-surviving **breadcrumb** (last op + arg + stamp; 0x70 sub-ops preload/arm/
+  respond), previous boot's slowest op, watchdog fields (`ver` is a wire byte — do NOT bump it per build).
+- `GET_FIRMWARE_VERSION` 0xCB: sha, branch, date, arena, flags (bit2 ring, bit3 crashreport, bit4 freerun, **bit5 sdfast**).
+- `GET_SD_INFO` 0xCD (new): CID/CSD identity + FAT type + cluster size (the bench card: MID 0x00 OEM "42" `SD8GB`,
+  8 GB SDHC, FAT32, 4 KB clusters).
+- `GET_CRASHREPORT` 0xCC: raw PJRC fault region (junk after a bootloader reflash — known).
+- RAM-only counters not on the wire yet: `cmd70_same_index` (Health stats).
+
+### 2.3 Standalone (no browser)
+
+- Firmware `scripts/sd_stall_test.py` — Mode-3 driver + ring drainer writing the same row shapes + inline stall
+  summary (card comparisons). **Codex review flagged it as not yet measurement-grade** (pacing bursts after stalls,
+  backlog contamination, capture validity, clustering by host receipt time) — fixes are in the perf session's queue;
+  do not compare cards with it until they land.
+- Firmware `scripts/telemetry_drain.py`, `scripts/soak_mode3.py` (older, no 0xCB/0xCD).
+
+## 3. Evidence for the clock model (what has actually been checked)
+
+| edge | evidence | confidence |
+|---|---|---|
+| sim → bridge (`ft` vs `ms`) | sim `ft` is synthetic (frame × dt); `ms` is bridge receipt; UDP on localhost | trivial; **real FicTrac never measured** |
+| bridge → Studio (WebSocket) | not separately stamped; `a.t_off` is the SEND time after the client coalesced frames | gap: no per-frame receipt stamp in the browser |
+| Studio send → controller dispatch | pair `a` rows with `cc` 0x70 records by order (drop the pre-run ring backlog); linear fit `t_host = a + b·t_us` → −3 ppm; residual = USB/CDC queueing + `serviceUsb` (one command per `loop()` iteration) | measured once (T4 iteration 1) |
+| dispatch → SPI start | `cc.t_us` → next `cf.t_us` (seq+1) = 4.7 ms median / 5.8 p99 at 100 Hz (2026-09-12); now directly as `cf.req_age_us` per displayed frame | measured; now first-class |
+| SPI start → photons | `spi_us` 0.77 ms is the transfer; panel latch + LED update after that is **unmeasured** (needs an optical sensor) | not measured |
+| controller reply → Studio | `a.dt` − (controller time) — `dt` includes queue wait, so subtract the in-controller time from `cc`/`cf` pairing | derivable |
+| ring record → log | `rx` is drain receipt (≤ 100 ms late, up to seconds when the bridge refuses rows); ordering by `seq` is exact; a CMD is appended AFTER its handler's STATE records (lower seq for the STATEs, later `t_us`) | documented |
+
+## 4. How to determine round-trip latency (recipe for the review)
+
+Define the chain for one closed-loop step: FicTrac frame `k` (ft/ms) → bridge → browser `apply` → 0x70 sent
+(`a.t_off`) → controller dispatch (`cc.t_us`) → SD read (`sd_load_us`, inside `req_age_us`) → SPI start
+(`cf.t_us`) → LEDs (unknown) ; reply → browser (`a.t_off + a.dt`).
+
+1. **Per run, fit the host↔controller clock**: pair 0x70 `a` rows with `cc` rows by order (counts differ by the
+   in-flight ones; discard ring records whose `rx − t_us/1000` offset differs from the run's by > 2 s = backlog);
+   fit `t_host = a + b·t_us`; report slope (ppm) and residual distribution = USB + CDC + parse latency.
+2. **Dispatch → presentation**: `cf.req_age_us` directly (v2), or `cc→cf` by seq (v1). Split it into SD
+   (`sd_load_us`) + wait-for-tick + queue.
+3. **Host-observed**: `a.dt` minus the controller's dispatch→reply time (reply is queued right after the handler;
+   approximate with `cf.req_age_us` when the frame changed, else ~0.1 ms).
+4. **FicTrac → command**: **not derivable today** — add `fc` (or the FicTrac `ft`) to the `a` row (or a per-command
+   `fc` field the bridge fills when it forwards the derived index) and, ideally, echo it in the 0x70 payload so it
+   appears in `cc.req` too (a 2-byte extension the firmware ignores). Then FicTrac frame → LED = (a.t_off − ms) +
+   host→controller offset + `req_age_us` + SPI + latch.
+5. **Superseded / coalescing**: `superseded` per FRAME (controller side) + the bridge client's coalescing count
+   (host side; not logged today — add a counter to `iteration-end`).
+
+## 5. Timing directly on the Teensy — proposals that need no AD3 / Saleae
+
+The controller already owns the two ends that matter (command arrival, SPI start). What it cannot see is the
+light. Options, cheapest first:
+
+1. **USB arrival stamp (free).** Today `cc.t_us` is dispatch entry; `SerialManager::parseIncoming` sets
+   `cmd_ready_` when the frame is complete. Stamp `micros()` there and carry it on `ParsedCommand` → a new CMD field
+   (or a STATE) gives USB-queue vs dispatch split with no hardware.
+2. **Framescan loopback (a wire).** `out_debug_framescan` on Digital IO 1 already envelopes the SPI transfer;
+   loop it to Digital IO 2 configured as an input with an edge interrupt → the controller timestamps its own frame
+   envelope in `micros()` and can cross-check `spi_us` and the tick phase. Proves the DIO path; does not see light.
+3. **Photodiode on Analog In (the real glass-to-glass measurement, Teensy-only).** A phototransistor/photodiode
+   taped to one panel into "Analog In 1 (±10 V)"; the analog-in path (fw F1/F2, 12-bit, `GET_ANALOG_IN` 0xA4) exists.
+   Two ways to timestamp the edge without busy-waiting the whole loop: (a) the i.MX RT ADC has a hardware
+   **compare function with interrupt** — arm it after each transfer with a threshold, and the ISR records
+   `micros()` → `light_us − cf.t_us` per frame as a new FRAME field or STATE; (b) bench-only diag mode: after
+   `transferFrame`, poll the ADC for ≤ 5 ms (blocking, acceptable on a bench build) and record the crossing.
+   Use a pattern that alternates a dark and a lit frame at the sensor's location (or the all-on/off glyph path).
+   This gives **SPI start → LED update** per frame with the controller's own clock — the number nobody has.
+4. **Panel-side confirmation.** The panels answer on CIPO (the DEBUG_SERIAL build captures 3 bytes per panel set
+   every 300th frame). A per-frame "panel accepted" timestamp is possible but needs the debug capture path on
+   every frame; lower value than 3.
+5. **Refresh-tick phase.** Record `micros()` in `refreshISR` (or a 16-bit counter) and log tick→transfer latency
+   per FRAME → separates "waited for the tick" from "loop was busy".
+6. **Host-side without instruments:** the sim can stamp its send time into `ft`; the browser can add
+   `performance.now()` at WebSocket receipt to the `apply` path; both are software.
+
+## 6. Critical next experiments (with what they discriminate)
+
+1. **Control iteration on the new build** (running today): step-class table (did contiguous seeks collapse the
+   backward-seek penalty?), reads/command (~0.76 expected from the same-index skip), `req_age_us` distribution,
+   stall cluster spacing in reads (expected unchanged — card).
+2. **Working-set test on the same file** (`sd_stall_test.py --window 50/100/200`, after the harness fixes): does a
+   50-frame working set inside the 813 KB file stall? Discriminates card read-cache vs placement explanations.
+3. **`0x32` host streaming at 100/200/286 Hz** (existing opcode; no SD at all): does the failure vanish, and does USB
+   meet the deadline under the real host load? Cheapest test of "remove SD from the trial".
+4. **Photodiode-on-AIN glass-to-glass** (§5.3): the only way to turn `req_age_us` into a latency to light.
+5. **FicTrac → command linkage** (§4.4) then the full chain on a real FicTrac rig (camera clock, not the sim).
+6. **Telemetry-on vs -off control iteration** (Debug ▾ toggle): the instrumentation's own cost.
+7. **Card screening** when cards arrive (protocol in `sd-read-jitter-2026-09-13.md` §5); never reformat the
+   current card.
+8. **Resident-decode proof** (next implementation session, not this review): LZ4/zlib per-frame RAM cache of the
+   bar pattern loaded in the ITI; the read-free path (`sd-read-jitter-2026-09-13.md` §6).
+
+## 7. Known gaps / caveats for the reviewer
+
+- `cf.rx` is NOT the event time; FRAME `t_us` is SPI start, not photons; CMD `t_us` is dispatch entry, not USB arrival.
+- FRAME records exist only for displayed CHANGES; held frames and superseded loads are invisible except via
+  `superseded` and the per-trial `sd_reads`.
+- `sd_slow_ctx` is sticky last-error context, not per-read evidence; `sd_slow` is a threshold event (10 ms).
+- The bridge log's `rx` for ring rows can lag by the drain period (100 ms) or more when the bridge refuses rows.
+- Ring capacity ≈ 5–6 s of Mode-3 traffic; drops are counted (`dropped`, seq gaps) — the trial-quality module marks
+  such trials `unknown`.
+- No log carries which physical card served runs before 2026-09-13 11:44 ET (0xCD did not exist).

From 2f4e3b8a39ff75f47f9730ba4b54bf22a539bbae Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 11:48:47 -0400
Subject: [PATCH 05/67] fix(telemetry): SET_FRAME_POSITION index from the
 firmware's request bytes (after len,cmd); host-prefixed form tolerated

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../telemetry-review-handoff-2026-09-13.md           |  2 +-
 js/trial-quality.js                                  | 12 +++++++-----
 scripts/telemetry-report.py                          |  9 +++++++--
 tests/test-telemetry-report.py                       |  9 ++++++++-
 tests/test-trial-quality.js                          |  3 ++-
 5 files changed, 25 insertions(+), 10 deletions(-)

diff --git a/docs/development/telemetry-review-handoff-2026-09-13.md b/docs/development/telemetry-review-handoff-2026-09-13.md
index 7ed109ba..15135b7a 100644
--- a/docs/development/telemetry-review-handoff-2026-09-13.md
+++ b/docs/development/telemetry-review-handoff-2026-09-13.md
@@ -42,7 +42,7 @@ end-to-end latency (FicTrac frame → LED) is wanted (§4).
   (0x70 stream + protocol commands); requests > 8 B (TRIAL_PARAMS) fall back to the v1 `arena_command` object.
 - Controller ring rows, in **ring `seq` order** (never sort by `rx`/`t_us`):
   - `["cc", rx, t_us, seq, cmd, status, "reqhex"]` — every command the controller dispatched (except 0xA9);
-    `reqhex` = first ≤ 8 request bytes incl. `len cmd` (so `03 70 4e 00` → index 78); `status` = the reply's status.
+    `reqhex` = first ≤ 8 request bytes AFTER `len cmd` (so `2d00` → index 45; the host `a` row keeps the full `03 70 2d 00`); `status` = the reply's status.
   - `["cf", rx, t_us, seq, idx, pattern, sd_load_us, spi_us, req_age_us, superseded, flags]` — a displayed frame
     CHANGE (held frames are not recorded). Last three fields are **ring v2 only** (fw 0xCB bit 5): `req_age_us` =
     dispatch of the 0x70 that requested this frame (or the `loadFrame` decision in Mode 2/4) → SPI start, u32;
diff --git a/js/trial-quality.js b/js/trial-quality.js
index 8dd5d534..a4ec0135 100644
--- a/js/trial-quality.js
+++ b/js/trial-quality.js
@@ -282,12 +282,14 @@
         return (b - a) >>> 0 < 0x80000000;
     }
 
-    // CMD record `req` = hex of the first ≤ 8 request bytes after [len, cmd]:
-    // for SET_FRAME_POSITION that is "03 70 lo hi" → index = lo | hi << 8.
+    // CMD record `req` = hex of the request bytes AFTER [len, cmd] as the firmware
+    // records them: for SET_FRAME_POSITION "2d00" → index 45. Host-style echoes that
+    // still carry the prefix ("03702d00") are tolerated for older fixtures.
     function idxFromReq(req) {
-        if (typeof req !== 'string' || req.length < 8) return null;
-        const lo = parseInt(req.slice(4, 6), 16);
-        const hi = parseInt(req.slice(6, 8), 16);
+        if (typeof req !== 'string' || req.length < 4) return null;
+        const off = req.length >= 8 && req.slice(2, 4) === '70' ? 4 : 0;
+        const lo = parseInt(req.slice(off, off + 2), 16);
+        const hi = parseInt(req.slice(off + 2, off + 4), 16);
         if (Number.isNaN(lo) || Number.isNaN(hi)) return null;
         return lo | (hi << 8);
     }
diff --git a/scripts/telemetry-report.py b/scripts/telemetry-report.py
index ae3ef589..b9b429b9 100644
--- a/scripts/telemetry-report.py
+++ b/scripts/telemetry-report.py
@@ -94,10 +94,15 @@ def step_class(prev_idx, idx, frame_count):
 
 
 def idx_from_req(req) -> int | None:
-    if not isinstance(req, str) or len(req) < 8:
+    """SET_FRAME_POSITION index from a CMD record's request hex.
+
+    The firmware records the bytes AFTER [len, cmd] ("2d00" → 45). Host-style echoes that
+    still carry the len/cmd prefix ("03702d00") are tolerated for older fixtures."""
+    if not isinstance(req, str) or len(req) < 4:
         return None
+    off = 4 if len(req) >= 8 and req[2:4] == "70" else 0
     try:
-        return int(req[4:6], 16) | (int(req[6:8], 16) << 8)
+        return int(req[off:off + 2], 16) | (int(req[off + 2:off + 4], 16) << 8)
     except ValueError:
         return None
 
diff --git a/tests/test-telemetry-report.py b/tests/test-telemetry-report.py
index 6eb669ec..9aa04cd1 100644
--- a/tests/test-telemetry-report.py
+++ b/tests/test-telemetry-report.py
@@ -31,7 +31,8 @@ def check(name, got, expected):
 
 
 def req70(idx):
-    return "0370" + f"{idx & 0xff:02x}{idx >> 8:02x}"
+    # the firmware records the bytes after [len, cmd]: "2d00" → 45 (see telemetry_report.idx_from_req)
+    return f"{idx & 0xff:02x}{idx >> 8:02x}"
 
 
 def build_fixture(v2=True):
@@ -110,6 +111,12 @@ def write(lines, path):
     write(build_fixture(), p)
     rep = tr.analyze_file(p)
 
+    print("=== idx_from_req ===")
+    check("fw form", tr.idx_from_req("2d00"), 45)
+    check("host-prefixed form", tr.idx_from_req("03704e00"), 78)
+    check("hi byte", tr.idx_from_req("0101"), 257)
+    check("short", tr.idx_from_req("2d"), None)
+
     print("=== meta ===")
     check("firmware", rep["meta"]["firmware"].startswith("200fada"), True)
     check("sd_card label", rep["meta"]["sd_card"].startswith("SanDisk"), True)
diff --git a/tests/test-trial-quality.js b/tests/test-trial-quality.js
index 618dae04..8668fe95 100644
--- a/tests/test-trial-quality.js
+++ b/tests/test-trial-quality.js
@@ -42,7 +42,8 @@ const C70 = (idx, tUs, status) => ({
 console.log('=== idxFromReq ===');
 check('index from req hex', TQ.idxFromReq('03704e00'), 78);
 check('hi byte', TQ.idxFromReq('03700101'), 257);
-check('short → null', TQ.idxFromReq('0370'), null);
+check('short → null', TQ.idxFromReq('2d'), null);
+check('firmware form (bytes after len,cmd)', TQ.idxFromReq('2d00'), 45);
 
 console.log(
     '\n=== three trials: pass / fail (stall) / fail (frame age), reads + cmd accounting ==='

From f1535df0a92b27f9a09d48f088e916cc157d2a71 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 11:53:23 -0400
Subject: [PATCH 06/67] =?UTF-8?q?fix(telemetry):=20sd=5Freads=20checkpoint?=
 =?UTF-8?q?=20bit=20(code=20bit=207)=20=E2=80=94=20cumulative=20mid-open?=
 =?UTF-8?q?=20checkpoints,=20largest=20value=20wins?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 js/arena-telemetry.js | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/js/arena-telemetry.js b/js/arena-telemetry.js
index a80d0a50..df8d55cd 100644
--- a/js/arena-telemetry.js
+++ b/js/arena-telemetry.js
@@ -200,7 +200,10 @@
                     rec.irqstatHi = rec.arg; // USDHC IRQSTAT bits 16-31 at the driver's LAST error
                     rec.driverSawError = rec.code !== 0;
                 }
-                if (rec.stateKind === 13) rec.reads = rec.arg * Math.pow(2, rec.code); // code = binary shift
+                if (rec.stateKind === 13) {
+                    rec.reads = rec.arg * Math.pow(2, rec.code & 0x7f); // code bits 0-6 = binary shift
+                    rec.checkpoint = !!(rec.code & 0x80); // cumulative mid-open checkpoint (every 30k reads), not a close
+                }
             } else {
                 rec.kind = 'unknown';
                 rec.raw = hex(m.subarray(p, p + plen));

From 6ceeafeb18bc2558e0ebee62ec25cfdbd11b2414 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 11:53:50 -0400
Subject: [PATCH 07/67] fix(telemetry): sd_reads checkpoint semantics in
 trial-quality + telemetry-report (largest cumulative value per open)

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 js/trial-quality.js | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/js/trial-quality.js b/js/trial-quality.js
index a4ec0135..bdadd423 100644
--- a/js/trial-quality.js
+++ b/js/trial-quality.js
@@ -165,7 +165,14 @@
                             break;
                         }
                         case 13: // sd_reads for the pattern being left
-                            if (current) current.reads = r.reads != null ? r.reads : r.arg;
+                            // checkpoints (code bit 7) and the closing record are cumulative: keep the largest
+                            if (current) {
+                                const v =
+                                    r.reads != null
+                                        ? r.reads
+                                        : r.arg * Math.pow(2, (r.code || 0) & 0x7f);
+                                if (current.reads == null || v > current.reads) current.reads = v;
+                            }
                             break;
                         case 5: // ring_overrun: records evicted before the host read them
                             coverage('ring_overrun', { code: r.code, arg: r.arg });

From 2377a1bfa12ce61b5c0177e965a20bdbbb31ced8 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 11:54:21 -0400
Subject: [PATCH 08/67] fix(telemetry-report): sd_slow_ctx as USDHC error bits,
 sd_reads checkpoint semantics; test fixtures for the checkpoint bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 scripts/telemetry-report.py    | 12 +++++++++---
 tests/test-arena-telemetry.js  |  7 ++++---
 tests/test-telemetry-report.py |  1 +
 3 files changed, 14 insertions(+), 6 deletions(-)

diff --git a/scripts/telemetry-report.py b/scripts/telemetry-report.py
index b9b429b9..b64fbed9 100644
--- a/scripts/telemetry-report.py
+++ b/scripts/telemetry-report.py
@@ -253,11 +253,17 @@ def analyze_file(path: str, gap_ms: float = 10.0, target_ms: float = 5.0) -> dic
                             cur.stalls.append((ms, phase))
                 elif kind == 12:
                     if stalls and stalls[-1]["ctx"] is None:
-                        stalls[-1]["ctx"] = {"card_error_code": code, "irqstat_lo": arg}
+                        stalls[-1]["ctx"] = {"card_error_code": code, "irqstat_hi": arg, "driver_saw_error": bool(code)}
                 elif kind == 13:
+                    shift = (code & 0x7F) if isinstance(code, int) else 0   # bits 0-6 = binary shift; bit 7 = mid-open checkpoint
+                    reads = arg << shift
                     if cur is not None:
-                        cur.reads_fw = arg
-                        per_pattern[cur.pattern]["reads_fw"] += arg
+                        # checkpoints and the closing record are cumulative for the same open: keep the largest,
+                        # and count the per-pattern total once per open (replace the previous contribution)
+                        prev = cur.reads_fw or 0
+                        if reads > prev:
+                            per_pattern[cur.pattern]["reads_fw"] += reads - prev
+                            cur.reads_fw = reads
                 elif kind == 1:
                     if cur is not None:
                         cur.coverage.append("controller_reboot")
diff --git a/tests/test-arena-telemetry.js b/tests/test-arena-telemetry.js
index 5099a165..e2457a35 100644
--- a/tests/test-arena-telemetry.js
+++ b/tests/test-arena-telemetry.js
@@ -239,7 +239,7 @@ function block(h, records) {
                 stateRec(21, 3100, 4, 0x82, 887), // sd_slow: body phase, read error, 88.7 ms
                 stateRec(22, 3200, 11, 0x01, 8), // sd_layout: contiguous, FAT32, 8 sectors/cluster
                 stateRec(23, 3300, 12, 0, 1), // sd_slow_ctx
-                stateRec(24, 3400, 13, 3, 45000) // sd_reads: 45000 << 3 = 360000
+                stateRec(24, 3400, 13, 0x83, 45000) // sd_reads checkpoint: 45000 << 3 = 360000, bit 7 = checkpoint
             ]),
             Wire
         );
@@ -276,9 +276,10 @@ function block(h, records) {
                 b2.records[3].cardErrorCode,
                 b2.records[3].driverSawError,
                 b2.records[4].stateName,
-                b2.records[4].reads
+                b2.records[4].reads,
+                b2.records[4].checkpoint
             ],
-            ['sd_slow_ctx', 0, false, 'sd_reads', 360000]
+            ['sd_slow_ctx', 0, false, 'sd_reads', 360000, true]
         );
         check('v2 malformed = 0', b2.malformed, 0);
         const rows2 = T.toRows(b2, 1);
diff --git a/tests/test-telemetry-report.py b/tests/test-telemetry-report.py
index 9aa04cd1..a1b1a95b 100644
--- a/tests/test-telemetry-report.py
+++ b/tests/test-telemetry-report.py
@@ -86,6 +86,7 @@ def cf(idx, pattern, sd, age=4700, sup=0, flags=3):
     cs(4, 2, 671); cs(12, 0, 0)
     cf(idx + 1, 36, 67100, age=69000)
     cs(4, 2, 80)                          # 8 ms: slow by fw threshold, not over 10 ms
+    cs(13, 0x80, 30)                      # mid-open checkpoint (cumulative), superseded by the close below
     cs(13, 0, reads + 1)
     # trial 2: pattern 5 (20 frames), clean, one repeated index
     cs(7, 0, 5)

From 7b3e619acdd8191ddf70876f314c160d5254703f Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 11:55:12 -0400
Subject: [PATCH 09/67] docs(bench log): H-FAT prediction recorded before the
 control iteration completes

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/development/mode3-wedge-soak-plan.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/docs/development/mode3-wedge-soak-plan.md b/docs/development/mode3-wedge-soak-plan.md
index b90378d6..8ca28c76 100644
--- a/docs/development/mode3-wedge-soak-plan.md
+++ b/docs/development/mode3-wedge-soak-plan.md
@@ -359,6 +359,20 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   stall immunity). `req_age_us` (0x70 dispatch → SPI start) p50 1.77 ms, p99 2.56 ms, max 2.56 ms; superseded 1.2 %
   of frames. No stall yet in 66 s (expected spacing ~250 s). Layout: contiguous, 8 sectors/cluster, both patterns.
 
+- **2026-09-13 11:55 ET — prediction recorded before the iteration completes:** 10 min / 11 trials into the control
+  iteration on `3c71953`, **zero `sd_slow` records** (baseline `394dee45`: a cluster every ~250 s at this rate; with 24 %
+  fewer reads the first cluster was due by ~330 s). Hypothesis H-FAT: the card's read-count hot spot was the **FAT
+  sector(s)**, not the pattern data — on this 4 KB-cluster card the 813 KB pattern's cluster chain (≈ 200 entries ×
+  4 B = 800 B) spans TWO FAT sectors, so every backward seek's chain walk (`FatFile::seekSet` from the first cluster)
+  missed SdFat's one-sector FAT cache and re-read a FAT sector from the card (~12k FAT reads per 24.5k pattern reads);
+  the 81 KB grating's chain (80 B) lives in one FAT sector that stays cached → never a FAT read → never a stall.
+  Explains: per-file, count-based, rate-independent, power-cycle-persistent, position-dependent (seeks to high frames
+  cross the FAT-sector boundary), non-sequential-only. `contiguousRange()` (fix A) removed every FAT read, so if the
+  full iteration and iteration 2 stay at zero stalls, the stall was firmware-induced (a read-disturb hot spot on the
+  FAT's flash block) and fix A is the fix for this workload. Discriminator if wanted: one iteration on `394dee45`
+  (stalls return at ~24.5k reads) or a build with `contiguousRange()` disabled — the new `sd_slow` phase byte would
+  read `seek`.
+
 ## 11. T4 as built (2026-09-12) — soak with ring-buffer logging
 
 Decision (Michael, 11:30 ET): skip the instrument-dependent T2/T3 for now; build the ring (T1

From 8446911d5c185a4f75752d71b7d2d742115e617d Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 11:57:29 -0400
Subject: [PATCH 10/67] docs(bench log): offline FAT-cache simulation
 inconclusive; bench A/B is the discriminator

---
 docs/development/mode3-wedge-soak-plan.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/development/mode3-wedge-soak-plan.md b/docs/development/mode3-wedge-soak-plan.md
index 8ca28c76..1d476911 100644
--- a/docs/development/mode3-wedge-soak-plan.md
+++ b/docs/development/mode3-wedge-soak-plan.md
@@ -373,6 +373,13 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   (stalls return at ~24.5k reads) or a build with `contiguousRange()` disabled — the new `sd_slow` phase byte would
   read `seek`.
 
+- **2026-09-13 12:00 ET — offline check of H-FAT on the 200 Hz fix-build block (21 files, 200 bar trials, 1.77 M reads,
+  308 stalls):** a one-sector FAT-cache simulation of SdFat's chain walk (unknown first-cluster offset swept 0–127)
+  puts 42–77 % of stalls on FAT-fetching reads, but only by driving the fetch rate toward 100 %, and it does not
+  reproduce the position dependence (stalls 14–17 % in bins 4–8 vs 9–13 % simulated). Inconclusive — the model may
+  miss SdFat details or the stall may attach to a later command than the fetch. The bench A/B (zero stalls on
+  `3c71953` vs one cluster per ~250 s on `394dee45`, same card, same workload) is the discriminator.
+
 ## 11. T4 as built (2026-09-12) — soak with ring-buffer logging
 
 Decision (Michael, 11:30 ET): skip the instrument-dependent T2/T3 for now; build the ring (T1

From 04dca6bbdcd40a461535e112adbd43c5b73b6ad4 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 12:07:27 -0400
Subject: [PATCH 11/67] docs: control iteration 1 results on 3c71953 vs
 baseline (0 stalls vs 4 clusters; FAT-walk penalty gone; 0.76 reads/cmd;
 req_age max 4.8 ms)

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/development/mode3-wedge-soak-plan.md     | 18 +++++++++++++
 docs/development/sd-read-jitter-2026-09-13.md | 27 +++++++++++++++++--
 2 files changed, 43 insertions(+), 2 deletions(-)

diff --git a/docs/development/mode3-wedge-soak-plan.md b/docs/development/mode3-wedge-soak-plan.md
index 1d476911..26458496 100644
--- a/docs/development/mode3-wedge-soak-plan.md
+++ b/docs/development/mode3-wedge-soak-plan.md
@@ -380,6 +380,24 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   miss SdFat details or the stall may attach to a later command than the fetch. The bench A/B (zero stalls on
   `3c71953` vs one cluster per ~250 s on `394dee45`, same card, same workload) is the discriminator.
 
+- **2026-09-13 12:06 ET — control iteration 1 on `3c71953` COMPLETE (1273 s, 20 trials, 240,258 accepted 0x70s, 0 faults)
+  vs the baseline iteration `arena-log-20260913-014056-656.jsonl` on `394dee45` (same card, same sim/protocol):**
+  | quantity | baseline 394dee45 | new 3c71953 |
+  |---|---|---|
+  | stalls > 10 ms / clusters | 15 / 4 (every 253 s ≈ 47.4k cmds) | **0 / 0** |
+  | bar −1 / −2..−9 / jump / +2..9 (p50 µs) | 1999 / 1998 / 1977 / 1461 | **1460 / 1460 / 1460 / 1460** |
+  | bar +1 | 621 | 621 |
+  | grating non-sequential | 1181 | 1181 |
+  | max sd_load (bar) | 88.6 ms | **1.8 ms** |
+  | SD reads per accepted 0x70 | 1.0 (every command read) | **0.761** (= index changes; kind 13 confirms) |
+  | req_age (0x70 dispatch → SPI start) | n/a | p50 1.73 ms · p99 2.56 · **max 4.8 ms** (under the 5 ms target) |
+  | superseded loads | n/a | 0.6 % of frames |
+  | trials flagged (> 10 ms) | 4 of 20 | **0 of 20** |
+  All 20 trials `pass` with full coverage. Zero clusters where ~3 were expected (P ≈ 0.05 for one iteration under the
+  baseline rate × 0.76) — iteration 2 doubles the exposure. If it stays clean, H-FAT (the FAT-sector re-reads were the
+  card's hot spot) is the working explanation and fix A removed the stalls on this card; a back-to-back reflash of
+  `394dee45` for one iteration would make it causal (proposed to Michael).
+
 ## 11. T4 as built (2026-09-12) — soak with ring-buffer logging
 
 Decision (Michael, 11:30 ET): skip the instrument-dependent T2/T3 for now; build the ring (T1
diff --git a/docs/development/sd-read-jitter-2026-09-13.md b/docs/development/sd-read-jitter-2026-09-13.md
index 3a969dcc..e9e76e42 100644
--- a/docs/development/sd-read-jitter-2026-09-13.md
+++ b/docs/development/sd-read-jitter-2026-09-13.md
@@ -150,5 +150,28 @@ grouping; hot vs quiet window), (5) maintenance-capability probe and flash-regio
 
 ## 7. Bench results (filled in as they arrive)
 
-_See `mode3-wedge-soak-plan.md` §10 for the timestamped log; summary table to be added after the control
-iteration on the new build._
+Control iteration 1 on `3c71953` (12:06 ET; 1273 s, 20 trials, 240k accepted 0x70s) vs the baseline iteration on
+`394dee45` (01:40; same card = the unbranded SD8GB, same 200 Hz + 90° jumps workload):
+
+| quantity | baseline | new build |
+|---|---|---|
+| stalls > 10 ms / clusters | 15 / 4 (every ~253 s ≈ 47.4k commands) | **0 / 0** |
+| bar pattern −1 / −2..−9 / jump ≥10 / +2..9, p50 | 2.00 / 2.00 / 1.98 / 1.46 ms | **1.46 ms for all four** |
+| +1 sequential (both patterns) | 0.62 ms | 0.62 ms |
+| grating non-sequential | 1.18 ms | 1.18 ms |
+| worst SD read (bar) | 88.6 ms | **1.8 ms** |
+| SD reads per accepted 0x70 | 1.00 | **0.76** (= index changes; firmware count agrees) |
+| request → SPI start (`req_age_us`) | — | p50 1.73 ms · p99 2.56 ms · **max 4.8 ms** |
+| trials flagged | 4 / 20 | **0 / 20** |
+
+Reading: fix A removed the FAT-chain walk (bar backward seeks now cost the same as forward jumps); fix B removed the
+repeated-index reads exactly (0.76 = the index-change rate); every frame reached the SPI bus within 4.8 ms of its
+request. The stalls did not occur at all in 1273 s where ~3 clusters were expected — see the H-FAT hypothesis in the
+bench log (§10, 11:55 entry): on this 4 KB-cluster card the 813 KB pattern's chain spans two FAT sectors, so the old
+firmware re-read a FAT sector from the card on most backward seeks; the grating's chain fits one cached sector. If
+iteration 2 stays clean, the stalls were induced by those FAT-sector reads and the contiguous-file path is the fix
+for this card and workload. A back-to-back reflash of `394dee45` (stalls should return at ~24.5k bar reads) is the
+causal test. **The read-free path (§6) stays valuable** — it also takes the 0.6–1.5 ms read and the card out of
+the loop entirely — but it is no longer the only route to a stall-free trial.
+
+See `mode3-wedge-soak-plan.md` §10 for the timestamped log.

From 946e89070080388292d5436ec19e7f8211ec5b35 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 12:28:36 -0400
Subject: [PATCH 12/67] =?UTF-8?q?docs:=20iteration=202=20results=20?=
 =?UTF-8?q?=E2=80=94=20482k=20commands,=200=20stalls=20on=203c71953;=20rev?=
 =?UTF-8?q?iew=20handoff=20experiment=201=20marked=20done?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/development/mode3-wedge-soak-plan.md               | 7 +++++++
 docs/development/sd-read-jitter-2026-09-13.md           | 4 ++++
 docs/development/telemetry-review-handoff-2026-09-13.md | 8 +++++---
 3 files changed, 16 insertions(+), 3 deletions(-)

diff --git a/docs/development/mode3-wedge-soak-plan.md b/docs/development/mode3-wedge-soak-plan.md
index 26458496..19f11f12 100644
--- a/docs/development/mode3-wedge-soak-plan.md
+++ b/docs/development/mode3-wedge-soak-plan.md
@@ -398,6 +398,13 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   card's hot spot) is the working explanation and fix A removed the stalls on this card; a back-to-back reflash of
   `394dee45` for one iteration would make it causal (proposed to Michael).
 
+- **2026-09-13 12:27 ET — iteration 2 COMPLETE, soak ended (2 iterations, 0 faults, 0 resets, 2576 s).** Iteration 2:
+  1281 s, 242,178 accepted 0x70s, **0 reads > 10 ms**, 20/20 trials pass, reads/cmd 0.76, req_age p50 1.72 ms / max
+  4.8 ms, superseded 0.5 %. Two iterations on `3c71953`: **482k commands, 2554 s of streaming, 0 stalls** where the
+  baseline rate (4 clusters / 1238 s, scaled by 0.76 reads/cmd) predicts ≈ 6 clusters (P(0) ≈ 0.003). Controller left
+  idle on `3c71953`, Studio v0.77 (:8092) connected. Awaiting Michael's decision on the causal test (reflash
+  `394dee45` for one iteration).
+
 ## 11. T4 as built (2026-09-12) — soak with ring-buffer logging
 
 Decision (Michael, 11:30 ET): skip the instrument-dependent T2/T3 for now; build the ring (T1
diff --git a/docs/development/sd-read-jitter-2026-09-13.md b/docs/development/sd-read-jitter-2026-09-13.md
index e9e76e42..6f706380 100644
--- a/docs/development/sd-read-jitter-2026-09-13.md
+++ b/docs/development/sd-read-jitter-2026-09-13.md
@@ -150,6 +150,10 @@ grouping; hot vs quiet window), (5) maintenance-capability probe and flash-regio
 
 ## 7. Bench results (filled in as they arrive)
 
+Iteration 2 (12:27 ET) repeated iteration 1 to the decimal: 1281 s, 242k accepted 0x70s, 0 reads > 10 ms, 20/20 pass,
+req_age max 4.8 ms. **Two iterations, 482k commands, 2554 s, zero stalls** where the baseline rate predicts ≈ 6
+clusters (P(0) ≈ 0.003).
+
 Control iteration 1 on `3c71953` (12:06 ET; 1273 s, 20 trials, 240k accepted 0x70s) vs the baseline iteration on
 `394dee45` (01:40; same card = the unbranded SD8GB, same 200 Hz + 90° jumps workload):
 
diff --git a/docs/development/telemetry-review-handoff-2026-09-13.md b/docs/development/telemetry-review-handoff-2026-09-13.md
index 15135b7a..5e167d41 100644
--- a/docs/development/telemetry-review-handoff-2026-09-13.md
+++ b/docs/development/telemetry-review-handoff-2026-09-13.md
@@ -145,9 +145,11 @@ light. Options, cheapest first:
 
 ## 6. Critical next experiments (with what they discriminate)
 
-1. **Control iteration on the new build** (running today): step-class table (did contiguous seeks collapse the
-   backward-seek penalty?), reads/command (~0.76 expected from the same-index skip), `req_age_us` distribution,
-   stall cluster spacing in reads (expected unchanged — card).
+1. **Control iterations on the new build — DONE 2026-09-13 12:27 ET:** two iterations, 482k commands, **0 stalls**
+   (baseline: 4 clusters per iteration on the same card); bar backward-seek cost 2.0 → 1.46 ms; reads/command 0.76;
+   `req_age_us` p50 1.7 ms, max 4.8 ms; all 40 trials pass. Working explanation: the FAT-sector re-reads of the
+   old seek path were the card's read-disturb hot spot (`sd-read-jitter-2026-09-13.md` §7, bench log 11:55). The
+   causal test (reflash `394dee45` for one iteration) is pending Michael's decision.
 2. **Working-set test on the same file** (`sd_stall_test.py --window 50/100/200`, after the harness fixes): does a
    50-frame working set inside the 813 KB file stall? Discriminates card read-cache vs placement explanations.
 3. **`0x32` host streaming at 100/200/286 Hz** (existing opcode; no SD at all): does the failure vanish, and does USB

From 94d84e4c505a397fed70500a95542e2efe401779 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 12:29:21 -0400
Subject: [PATCH 13/67] =?UTF-8?q?docs(bench=20log):=20session=20close=20?=
 =?UTF-8?q?=E2=80=94=20causal=20reflash=20deferred,=20bench=20state,=20nex?=
 =?UTF-8?q?t=20steps?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/development/mode3-wedge-soak-plan.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/docs/development/mode3-wedge-soak-plan.md b/docs/development/mode3-wedge-soak-plan.md
index 19f11f12..7268a3f3 100644
--- a/docs/development/mode3-wedge-soak-plan.md
+++ b/docs/development/mode3-wedge-soak-plan.md
@@ -405,6 +405,15 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   idle on `3c71953`, Studio v0.77 (:8092) connected. Awaiting Michael's decision on the causal test (reflash
   `394dee45` for one iteration).
 
+- **2026-09-13 12:29 ET — session closed at the bench (Michael: laptop must disconnect; no third trial).** Causal
+  reflash test of `394dee45` DEFERRED (next bench session: one iteration on the old build, stalls expected at ~24.5k bar
+  reads; then back to the fast-path build). Controller left on `3c71953`, display stopped, Studio disconnected (port
+  free); the :8092 worktree server stopped; bridge 3.1 + sim (200 Hz) left as Michael started them. Host branch
+  `claude/mode3-perf-sd` pushed; firmware `feat/sd-fastpath-2x10` stays local (tip `f6c11d2` built, `3c71953` on the
+  controller). Standing next steps: causal reflash; card screening with `sd_stall_test.py` when cards arrive; read-free
+  path (compressed RAM cache in the ITI, `sd-read-jitter-2026-09-13.md` §6); Codex diff review of `f6c11d2` before it
+  is flashed; #201 PR consolidation; telemetry review session (`telemetry-review-handoff-2026-09-13.md`).
+
 ## 11. T4 as built (2026-09-12) — soak with ring-buffer logging
 
 Decision (Michael, 11:30 ET): skip the instrument-dependent T2/T3 for now; build the ring (T1

From 18c4ee26138dbee8764ae6824863af3f12244a35 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 12:34:25 -0400
Subject: [PATCH 14/67] feat(studio): SET_SD_DIAG 0xCE host side (encoder,
 GET_SD_INFO byte 29 decode, sd_layout arm bits, Studio.setSdDiag,
 run_metadata.sd_card.sd_diag) + causal test plan for the SD-card stalls
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Four arms on one firmware build, switched at soak-iteration boundaries: legacy FAT-chain seek and/or no
same-index skip. The telemetry report labels each iteration's arm from the sd_layout records; the plan
(docs/development/sd-stall-causal-test-plan-2026-09-13.md) gives predictions per hypothesis, the phase-byte
fingerprint (H-FAT ⇒ stalls inside the seek), stopping rules and the procedure. Bench run pending.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 arena_studio.html                             |  23 +++-
 .../development/arena-studio-release-notes.md |   3 +
 docs/development/mode3-wedge-soak-plan.md     |   7 ++
 .../sd-stall-causal-test-plan-2026-09-13.md   | 108 ++++++++++++++++++
 js/arena-telemetry.js                         |   2 +
 js/arena-wire-g6.js                           |  28 ++++-
 scripts/telemetry-report.py                   |   5 +-
 tests/test-arena-telemetry.js                 |  14 +++
 tests/test-arena-wire-g6.js                   |  24 ++++
 tests/test-telemetry-report.py                |   2 +-
 10 files changed, 210 insertions(+), 6 deletions(-)
 create mode 100644 docs/development/sd-stall-causal-test-plan-2026-09-13.md

diff --git a/arena_studio.html b/arena_studio.html
index db1c7be1..ebcc4225 100644
--- a/arena_studio.html
+++ b/arena_studio.html
@@ -2959,7 +2959,7 @@ <h2 id="modalTitle">Import error</h2>
 </div>
 
 <footer id="footer">
-  <span class="foot-left">Arena Studio v0.77 | 2026-09-13 11:19 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.77 | 2026-09-13 12:32 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)">
@@ -8402,6 +8402,26 @@ <h2 id="modalTitle">Import error</h2>
 // PJRC CrashReport passthrough (0xCC, fw fb11681) — gated like the ring on the
 // 0xCB telemetry flag. Logged as a `crash_report` event (raw hex kept). Null when
 // the firmware lacks it or the link is down; never throws.
+// Bench A/B switches for the causal test of the SD-card stalls (SET_SD_DIAG 0xCE,
+// fw sd_fastpath only): flags bit0 = legacy FAT-chain seek at the next pattern open,
+// bit1 = no same-index skip. Refreshes Studio.sdCard so run_metadata.sd_card.sd_diag
+// records the arm. Console: `await Studio.setSdDiag(1)` … `await Studio.setSdDiag(0)`.
+Studio.setSdDiag = async function (flags) {
+    const fv = Studio.firmwareVersion;
+    if (!fv || !fv.sdFastPath || !Wire.encodeSetSdDiag || !Studio.session || !Studio.session.connected) {
+        Studio.rawLog('sd diag: firmware has no SD fast path (0xCB bit 5) or not connected', 'warn');
+        return null;
+    }
+    const r = Wire.decodeResponse(await Studio.session.send(Wire.encodeSetSdDiag(flags), { timeoutMs: 2000 }));
+    if (!r || !r.ok) { Studio.rawLog('sd diag: refused', 'warn'); return null; }
+    const si = Wire.decodeSdInfo(await Studio.session.send(Wire.encodeGetSdInfo(), { timeoutMs: 2000 }));
+    if (si) Studio.sdCard = si;
+    const b = Studio.session.bridge;
+    if (b && b.logging) b.log({ event: 'sd_diag', flags: flags, in_force: si ? si.sdDiag : null, label: si ? si.label : null });
+    Studio.rawLog('sd diag flags now ' + (si ? si.sdDiag : '?') + (flags & 1 ? ' — legacy FAT-chain seek from the next pattern open' : '') + (flags & 2 ? ' — every 0x70 reads (no same-index skip)' : '') + (!flags ? ' — production behaviour' : ''), 'info');
+    return si;
+};
+
 Studio.readCrashReport = async function () {
     const fv = Studio.firmwareVersion;
     if (!fv || !fv.crashReport || !Wire.encodeGetCrashReport || !Studio.session || !Studio.session.connected) return null; // 0xCB flags bit 3, never the ring bit (c47ee68 has the ring but not 0xCC)
@@ -8588,6 +8608,7 @@ <h2 id="modalTitle">Import error</h2>
                 card_type: sc.cardTypeName, fat: sc.fatTypeName, bytes_per_cluster: sc.bytesPerCluster, cid_hex: sc.cidHex
             } : null;
             md.gap_threshold_ms = Studio.trialQuality ? Studio.trialQuality.thresholdUs / 1000 : null;
+            if (md.sd_card) md.sd_card.sd_diag = sc.sdDiag || 0; // A/B arm in force (SET_SD_DIAG 0xCE); 0 = production
             bridge.log(md);
         }
         // Controller telemetry streams (T4): declare the compact row schema once
diff --git a/docs/development/arena-studio-release-notes.md b/docs/development/arena-studio-release-notes.md
index cc064d5b..4f8e7298 100644
--- a/docs/development/arena-studio-release-notes.md
+++ b/docs/development/arena-studio-release-notes.md
@@ -23,6 +23,9 @@ history lives here. Newest first. (Per-session engineering detail stays in
   pattern file is on the fast (contiguous) seek path. Readers treat the new columns as optional.
 - Telemetry drain keeps up in a background tab (per-poll budget raised 5×); new analysis script
   `scripts/telemetry-report.py` (SD read cost by step, stall clusters, per-trial verdicts).
+- Bench A/B helper `Studio.setSdDiag(flags)` (firmware with `SET_SD_DIAG` 0xCE): forces the legacy FAT-chain
+  seek and/or disables the same-index read skip per iteration for the causal test of the card stalls
+  (`docs/development/sd-stall-causal-test-plan-2026-09-13.md`); the arm is recorded in `run_metadata.sd_card.sd_diag`.
 
 ## v0.76 (2026-09-11) · Controller-fault detection, post-mortem probes, soak driver (fw #50)
 
diff --git a/docs/development/mode3-wedge-soak-plan.md b/docs/development/mode3-wedge-soak-plan.md
index 7268a3f3..583dc135 100644
--- a/docs/development/mode3-wedge-soak-plan.md
+++ b/docs/development/mode3-wedge-soak-plan.md
@@ -414,6 +414,13 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   path (compressed RAM cache in the ITI, `sd-read-jitter-2026-09-13.md` §6); Codex diff review of `f6c11d2` before it
   is flashed; #201 PR consolidation; telemetry review session (`telemetry-review-handoff-2026-09-13.md`).
 
+- **2026-09-13 12:45 ET — causal test prepared (bench later, Michael):** firmware `2c83f45` adds `SET_SD_DIAG` 0xCE
+  (bit0 legacy FAT-chain seek at the next open, bit1 no same-index skip; readback 0xCD byte 29; `sd_layout` bits 2/3;
+  STATE marker), built, Codex round 3 running — NOT flashed (controller stays on `3c71953`). Studio v0.77 gains
+  `Studio.setSdDiag(flags)` + `run_metadata.sd_card.sd_diag`; telemetry-report labels the arm. Plan with predictions,
+  stopping rules and procedure: `docs/development/sd-stall-causal-test-plan-2026-09-13.md` (arms 3 → 1 → 2 → 0 on one
+  build, ~70 min; H-FAT fingerprint = `sd_slow` phase `seek` in the legacy-seek arms).
+
 ## 11. T4 as built (2026-09-12) — soak with ring-buffer logging
 
 Decision (Michael, 11:30 ET): skip the instrument-dependent T2/T3 for now; build the ring (T1
diff --git a/docs/development/sd-stall-causal-test-plan-2026-09-13.md b/docs/development/sd-stall-causal-test-plan-2026-09-13.md
new file mode 100644
index 00000000..8c523a92
--- /dev/null
+++ b/docs/development/sd-stall-causal-test-plan-2026-09-13.md
@@ -0,0 +1,108 @@
+# Causal test plan — did the contiguous-seek fix remove the SD-card stalls? (bench, ~70 min)
+
+**Written:** 2026-09-13 12:45 ET. **Status:** code ready (firmware `feat/sd-fastpath-2x10` with `SET_SD_DIAG` 0xCE,
+built, Codex review round 3 in progress; Studio v0.77 `Studio.setSdDiag`), **bench test pending** (Michael: no time
+today). **Prerequisite:** flash the reviewed 0xCE build via `scripts/flash_bootloader_route.sh` (port released by the
+Studio first), verify 0xCB label `… freerun sdfast` and `GET_SD_INFO` byte 29 = 0.
+
+## 1. What we know and what is still only correlational
+
+Same card (unbranded `SD8GB`, 8 GB SDHC, FAT32, **4 KB clusters**), same workload (200 Hz + 90° jumps, alternating
+the 813 KB bar pattern id 36 and the 81 KB grating id 5):
+
+| build | iterations | commands | reads > 10 ms | clusters | reads/cmd |
+|---|---|---|---|---|---|
+| `394dee45` (free-running timer, old seek path) | 19 + 5 (night) | 5.15 M | 716 in 197 clusters | one per ~24.5k bar reads | 1.00 |
+| `3c71953` (contiguous seeks **A** + same-index skip **B**) | 2 | 482k | **0** | **0** (≈ 6 expected) | 0.76 |
+
+Two things changed at once (A and B), and the build also changed the instrumentation. The working hypothesis
+**H-FAT**: on 4 KB clusters the bar pattern's cluster chain (~200 entries, 800 B) spans **two FAT sectors**; SdFat's
+`FatFile::seekSet` walks the chain from the first cluster on every backward seek and its one-sector FAT cache misses
+whenever the walk crosses the sector boundary → a FAT-sector read from the card on most backward seeks (~12k per 24.5k
+pattern reads). Those two sectors were the card's read-disturb hot spot; the grating's 80 B chain fits one cached
+sector, hence its immunity. **A** removes every FAT read (arithmetic seeks); **B** only removes 24 % of data reads.
+
+Competing explanations still open: **H-count** (any 24 % reduction in reads merely stretched the cycle; we stopped
+too early — but 482k commands at 0.76 = 367k reads ≈ 15 baseline cycles, so this needs the count to be per something
+else), **H-data** (the data region is the hot spot and something else about the new build changed its access), and
+plain luck (P ≈ 0.003).
+
+## 2. Design — four arms on ONE build, switched at iteration boundaries, no reflash
+
+`SET_SD_DIAG` 0xCE (`Studio.setSdDiag(flags)`): bit0 = legacy seek (the next pattern open skips `contiguousRange()`
+→ the old FAT-chain walk), bit1 = no same-index skip (every 0x70 reads). Every `sd_layout` record carries the arm
+(bits 2/3), `GET_SD_INFO` byte 29 reports it, `run_metadata.sd_card.sd_diag` and an `sd_diag` event mark the switch.
+
+| arm | flags | A (contiguous seeks) | B (same-index skip) | H-FAT predicts | H-count predicts | H-data predicts |
+|---|---|---|---|---|---|---|
+| 3 — **positive control first** | 3 | off | off | clusters every ~24.5k bar reads, **`sd_slow` phase = `seek`** | clusters every ~24.5k | clusters, phase `body` |
+| 1 — the decisive arm | 1 | off | **on** | clusters at ~24.5k bar reads (unchanged: B does not touch the FAT), phase `seek` | clusters every ~32k (24.5k/0.76) | clusters every ~32k, phase `body` |
+| 2 — the control for B | 2 | **on** | off | **0 clusters** | clusters every ~24.5k | clusters every ~24.5k |
+| 0 — production | 0 | on | on | 0 | clusters every ~32k | clusters every ~32k |
+
+Arm 0 is already measured (0 in 2 iterations). The **phase byte** is the fingerprint: under H-FAT the stall lands
+inside the seek (FAT-sector read), under H-data inside the body read — visible in arm 3 with a single stall.
+
+**Exposure and stopping rule.** One soak iteration ≈ 1250 s ≈ 120k bar-pattern commands ≈ 4–5 baseline cycles.
+- Arm 3 (20 min): must reproduce ≥ 2 clusters — if it does not, the card's behaviour has changed since last night
+  (its own counter, or a placement change from the `conftest.pat` upload/delete this morning) and the rest of the day's
+  arms are uninterpretable → stop and rethink.
+- Arm 1 (20 min): ≥ 2 clusters with phase `seek` ⇒ H-FAT confirmed; 0 clusters ⇒ H-FAT rejected (B or luck).
+- Arm 2 (20 min): 0 clusters (95 % upper bound ≈ 3 per iteration) ⇒ B is irrelevant to the stalls; clusters ⇒ H-count.
+- Order 3 → 1 → 2 → back to 0. Total ≈ 70 min including the 10 s gaps; no flash between arms.
+
+Every arm: same simulator (`--rate 200 --seed 1 --jump-every 100 --jump-deg 90`), same protocol
+`soak_mode3_card.yaml` (ids 36/5, frames 200/20 via the `__framesRepatch` hook), same rig `cshl_g6_2x10_ball`.
+
+## 3. Procedure (Studio v0.77 on the granted origin, Claude-in-Chrome or the console)
+
+```js
+// after connect: identity + baseline state
+Studio.firmware              // must end with "freerun sdfast" (build with 0xCE: see the bench log for its SHA)
+Studio.sdCard.sdDiag         // 0
+// arm 3 (positive control): legacy seek + no skip, then one iteration
+await Studio.setSdDiag(3);
+Studio.startSoak({iterations:1, gapS:10, firstFault:'halt', policy:'reset-continue', maxResets:3});
+// wait for the soak "end" event (≈ 21 min), then:
+await Studio.setSdDiag(1);   // arm 1: legacy seek, skip ON
+Studio.startSoak({iterations:1, gapS:10, firstFault:'halt', policy:'reset-continue', maxResets:3});
+// … end … 
+await Studio.setSdDiag(2);   // arm 2: contiguous seeks, skip OFF
+Studio.startSoak({iterations:1, gapS:10, firstFault:'halt', policy:'reset-continue', maxResets:3});
+// … end …
+await Studio.setSdDiag(0);   // back to production
+```
+
+Note the arm applies **from the next pattern open**; switching at an iteration boundary (soak ended) guarantees the
+whole iteration runs under one arm. Each iteration's `run_metadata.sd_card.sd_diag` and every `sd_layout` record say
+which arm it was.
+
+## 4. Analysis (per iteration file)
+
+```bash
+pixi run python scripts/telemetry-report.py soak-logs/arena-log-<arm3>.jsonl soak-logs/arena-log-<arm1>.jsonl soak-logs/arena-log-<arm2>.jsonl
+```
+Read off: `Card stalls` (count, clusters, spacing in commands / index changes, **phases**), `Reads accounting`
+(fw reads/cmd: 1.00 in arms 3/2, 0.76 in arm 1; layout column shows `LEGACY-SEEK arm` / `NO-SKIP arm`), the
+step-class table (arm 3/1: bar −1 back to ~2.0 ms, arm 2/0: 1.46 ms), `req_age_us` (arms with stalls: max ≈ stall
++ 2 ms), and the per-trial verdicts. Log every step in `mode3-wedge-soak-plan.md` §10 with ET stamps; add the
+result table to `sd-read-jitter-2026-09-13.md` §7.
+
+## 5. If H-FAT is confirmed — consequences
+
+- The stalls were **firmware-induced** (a read-disturb hot spot on the FAT sectors created by the chain walk), not an
+  intrinsic property of the card; the contiguous-seek path is the fix for every pattern whose chain spans > 1 FAT
+  sector (any pattern > ~512 KB on 4 KB clusters, > 4 MB on 32 KB clusters). Fragmented files must be flagged
+  (`sd_layout` bit0 = 0) and made contiguous (`preAllocate` on upload, or re-upload).
+- Course cards: check cluster size with `GET_SD_INFO`; a 32 KB-cluster format keeps even 4 MB patterns in one FAT
+  sector — but the fast path makes that moot.
+- The read-free path (`sd-read-jitter-2026-09-13.md` §6) remains the way to remove the 0.6–1.5 ms read and the card
+  from the loop entirely; it is no longer required to reach the 10 ms bound.
+- fw #54: close the "card housekeeping" mitigation thread with this result; the card-comparison protocol becomes
+  optional.
+
+## 6. If H-FAT is rejected
+
+Arm 1 clean but arm 3 stalls ⇒ B (read count) is what matters ⇒ H-count: the card's counter is per read; the
+read-free path becomes the priority again and the card comparison matters. Arm 3 clean ⇒ the card changed (or the
+morning's upload moved something) ⇒ characterise afresh with `sd_stall_test.py` before any conclusion.
diff --git a/js/arena-telemetry.js b/js/arena-telemetry.js
index df8d55cd..3bb2205c 100644
--- a/js/arena-telemetry.js
+++ b/js/arena-telemetry.js
@@ -193,6 +193,8 @@
                 if (rec.stateKind === 11) {
                     rec.contiguous = !!(rec.code & 0x01);
                     rec.exfat = !!(rec.code & 0x02);
+                    rec.legacySeek = !!(rec.code & 0x04); // SET_SD_DIAG bit0 in force at this open (A/B arm)
+                    rec.noSameIndexSkip = !!(rec.code & 0x08); // SET_SD_DIAG bit1 in force
                     rec.sectorsPerCluster = rec.arg;
                 }
                 if (rec.stateKind === 12) {
diff --git a/js/arena-wire-g6.js b/js/arena-wire-g6.js
index 4876288d..de45516d 100644
--- a/js/arena-wire-g6.js
+++ b/js/arena-wire-g6.js
@@ -70,6 +70,7 @@ const ArenaWireG6 = (function () {
         GET_CRASHREPORT: 0xcc, // [01 CC] raw 128 B at OCRAM 0x2027FF80: PJRC arm_fault_info_struct + breadcrumbs (ring fw; gate on 0xCB flags bit 2)
         GET_FIRMWARE_VERSION: 0xcb, // [01 CB] build identity: git SHA, branch, date, arena rows×cols (gate on cap bit 7)
         GET_SD_INFO: 0xcd, // SD card identity + volume geometry (fw sd_fastpath; gate on 0xCB flags bit 5)
+        SET_SD_DIAG: 0xce, // [02 CE flags] bench A/B: bit0 legacy FAT-chain seek (next open), bit1 no same-index skip (gate on 0xCB bit 5)
         SET_TELEMETRY: 0xa8, // [04 A8 flags rate_lo rate_hi] telemetry ring: bit0 events on/off (fw feat/telemetry-ring)
         GET_TELEMETRY_BLOCK: 0xa9, // [08 A9 ack_seq u32 max_bytes u16 flags] ack-cursor drain of the ring (js/arena-telemetry.js decodes)
         SET_AO_VOLTAGE: 0xa0, // [03 A0 mv_lo mv_hi] set analog output (BNC J27) 0–5000 mV
@@ -984,6 +985,17 @@ const ArenaWireG6 = (function () {
     function encodeGetSdInfo() {
         return frame(OPCODES.GET_SD_INFO); // 01 CD
     }
+    // set-sd-diag (0xCE) — bench A/B switches for the causal test of the SD-card
+    // stalls: bit0 legacy seek (the NEXT pattern open skips contiguousRange →
+    // FAT-chain-walking seeks), bit1 no same-index skip (every 0x70 reads). Both
+    // off at boot; readback = GET_SD_INFO byte 29. Gate on 0xCB flags bit 5.
+    const SD_DIAG_LEGACY_SEEK = 0x01;
+    const SD_DIAG_NO_SAME_INDEX_SKIP = 0x02;
+    function encodeSetSdDiag(flags) {
+        const f = u8(flags, 'sd diag flags');
+        if (f & ~0x03) throw new RangeError('sd diag flags: bits 2-7 are reserved');
+        return frame(OPCODES.SET_SD_DIAG, [f]); // 02 CE flags
+    }
     // Payload (30 B): ver u8 · flags u8 (bit0 mounted, bit1 CID valid, bit2 CSD
     // valid) · card_type u8 · fat_type u8 (12/16/32, 64 = exFAT) · sectors u32 ·
     // bytes_per_cluster u32 · cid[16] raw · sd_status_maint u8 (0xFF = not read) ·
@@ -1047,7 +1059,10 @@ const ArenaWireG6 = (function () {
             psn: ((cid[9] << 24) | (cid[10] << 16) | (cid[11] << 8) | cid[12]) >>> 0,
             mdtYear: 2000 + (((cid[13] & 0x0f) << 4) | (cid[14] >> 4)),
             mdtMonth: cid[14] & 0x0f,
-            sdStatusMaint: m[28]
+            sdStatusMaint: m[28],
+            sdDiag: m[29], // SET_SD_DIAG flags in force (0 = production behaviour)
+            legacySeek: !!(m[29] & 0x01),
+            noSameIndexSkip: !!(m[29] & 0x02)
         };
         v.psnHex = v.psn.toString(16).padStart(8, '0');
         v.label = !v.mounted
@@ -1073,7 +1088,13 @@ const ArenaWireG6 = (function () {
               (v.bytesPerCluster >= 1024
                   ? v.bytesPerCluster / 1024 + ' KiB'
                   : v.bytesPerCluster + ' B') +
-              ' clusters';
+              ' clusters' +
+              (v.sdDiag
+                  ? ' [diag ' +
+                    (v.legacySeek ? 'legacy-seek ' : '') +
+                    (v.noSameIndexSkip ? 'no-skip' : '') +
+                    ']'
+                  : '');
         return v;
     }
 
@@ -1296,6 +1317,9 @@ const ArenaWireG6 = (function () {
         encodeGetFramePosition,
         encodeGetFirmwareVersion,
         encodeGetSdInfo,
+        encodeSetSdDiag,
+        SD_DIAG_LEGACY_SEEK,
+        SD_DIAG_NO_SAME_INDEX_SKIP,
         encodeSetTelemetry,
         encodeGetTelemetryBlock,
         TELEMETRY_NO_ACK,
diff --git a/scripts/telemetry-report.py b/scripts/telemetry-report.py
index b64fbed9..e152fa46 100644
--- a/scripts/telemetry-report.py
+++ b/scripts/telemetry-report.py
@@ -232,7 +232,8 @@ def analyze_file(path: str, gap_ms: float = 10.0, target_ms: float = 5.0) -> dic
                     pending_first.add(arg)
                     per_pattern[arg]["opens"] += 1
                 elif kind == 11:
-                    lay = {"contiguous": bool(code & 1), "exfat": bool(code & 2), "sectors_per_cluster": arg}
+                    lay = {"contiguous": bool(code & 1), "exfat": bool(code & 2), "sectors_per_cluster": arg,
+                           "legacy_seek": bool(code & 4), "no_same_index_skip": bool(code & 8)}   # bits 2/3 = SET_SD_DIAG arm
                     if cur is not None:
                         cur.layout = lay
                         layout_by_pattern[cur.pattern] = lay
@@ -415,7 +416,7 @@ def render_markdown(rep: dict) -> str:
     out.append("|---|---|---|---|---|---|---|---|---|")
     for p, r in sorted(rep["reads"].items(), key=lambda kv: str(kv[0])):
         lay = r["layout"]
-        lay_s = "—" if not lay else ("contiguous" if lay["contiguous"] else "FRAGMENTED") + f", {lay['sectors_per_cluster']} spc" + (", exFAT" if lay["exfat"] else "")
+        lay_s = "—" if not lay else ("contiguous" if lay["contiguous"] else "FRAGMENTED") + f", {lay['sectors_per_cluster']} spc" + (", exFAT" if lay["exfat"] else "") + (", LEGACY-SEEK arm" if lay.get("legacy_seek") else "") + (", NO-SKIP arm" if lay.get("no_same_index_skip") else "")
         out.append(f"| {p} | {r['opens']} | {r['cmds70']} | {r['index_changes']} | {r['reads_fw'] if r['reads_fw'] is not None else '—'} | {r['frames']} | {r['index_changes_per_cmd']} | {r['reads_fw_per_cmd'] if r['reads_fw_per_cmd'] is not None else '—'} | {lay_s} |")
     out.append("")
     out.append("## SD read cost by index step (sd_load_us of displayed frames)")
diff --git a/tests/test-arena-telemetry.js b/tests/test-arena-telemetry.js
index e2457a35..18c36264 100644
--- a/tests/test-arena-telemetry.js
+++ b/tests/test-arena-telemetry.js
@@ -269,6 +269,20 @@ function block(h, records) {
             ],
             ['sd_layout', true, false, 8]
         );
+        check(
+            'sd_layout diag bits default off',
+            [b2.records[2].legacySeek, b2.records[2].noSameIndexSkip],
+            [false, false]
+        );
+        const b3 = T.parseBlock(
+            block({ tNowUs: 1, firstSeq: 30 }, [stateRec(30, 10, 11, 0x0c, 8)]),
+            Wire
+        );
+        check(
+            'sd_layout arm bits',
+            [b3.records[0].contiguous, b3.records[0].legacySeek, b3.records[0].noSameIndexSkip],
+            [false, true, true]
+        );
         check(
             'sd_slow_ctx + sd_reads',
             [
diff --git a/tests/test-arena-wire-g6.js b/tests/test-arena-wire-g6.js
index d884929e..95f6202a 100644
--- a/tests/test-arena-wire-g6.js
+++ b/tests/test-arena-wire-g6.js
@@ -758,6 +758,30 @@ check('FIRMWARE_VERSION_PAYLOAD_BYTES', Wire.FIRMWARE_VERSION_PAYLOAD_BYTES, 46)
             'sd_info short payload → null',
             Wire.decodeSdInfo(Uint8Array.from([5, 0x00, 0xcd, 1, 0, 0])) === null
         );
+        check(
+            'sd_info diag byte 0 → no diag',
+            [si.sdDiag, si.legacySeek, si.noSameIndexSkip].join(','),
+            '0,false,false'
+        );
+        const dg = sd.slice();
+        dg[29] = 0x03;
+        const sdg = Wire.decodeSdInfo(Uint8Array.from([dg.length + 2, 0x00, 0xcd].concat(dg)));
+        check(
+            'sd_info diag byte 3 decodes + label suffix',
+            [
+                sdg.legacySeek,
+                sdg.noSameIndexSkip,
+                sdg.label.endsWith('[diag legacy-seek no-skip]')
+            ].join(','),
+            'true,true,true'
+        );
+        checkBytes('encodeSetSdDiag(1)', Wire.encodeSetSdDiag(1), '02 ce 01');
+        checkBytes(
+            'encodeSetSdDiag(legacy|noskip)',
+            Wire.encodeSetSdDiag(Wire.SD_DIAG_LEGACY_SEEK | Wire.SD_DIAG_NO_SAME_INDEX_SKIP),
+            '02 ce 03'
+        );
+        checkThrows('encodeSetSdDiag rejects reserved bits', () => Wire.encodeSetSdDiag(4));
     }
     check(
         'ISR names 4–7 (usb/sdhc/lpspi/pit)',
diff --git a/tests/test-telemetry-report.py b/tests/test-telemetry-report.py
index a1b1a95b..3f630730 100644
--- a/tests/test-telemetry-report.py
+++ b/tests/test-telemetry-report.py
@@ -128,7 +128,7 @@ def write(lines, path):
     check("pattern 36 index changes (initial index not a change)", r36["index_changes"], 70)
     check("pattern 36 fw reads", r36["reads_fw"], 72)
     check("idx changes per cmd", r36["index_changes_per_cmd"], 0.5)
-    check("layout contiguous", r36["layout"], {"contiguous": True, "exfat": False, "sectors_per_cluster": 8})
+    check("layout contiguous", r36["layout"], {"contiguous": True, "exfat": False, "sectors_per_cluster": 8, "legacy_seek": False, "no_same_index_skip": False})
     check("pattern 5 index changes (repeat not counted)", rep["reads"][5]["index_changes"], 19)
 
     print("=== step classes ===")

From 9cd00bc745c0b4d0360eba739d8a5ddaa31f6a23 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 12:35:43 -0400
Subject: [PATCH 15/67] =?UTF-8?q?docs(sd):=20=C2=A78=20=E2=80=94=20does=20?=
 =?UTF-8?q?the=20fix=20generalise=3F=20(no=20size=20limit=20under=20H-FAT,?=
 =?UTF-8?q?=20contiguity=20is=20the=20precondition;=20read-path,=20timing?=
 =?UTF-8?q?=20and=20memory=20diagrams)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/development/sd-read-jitter-2026-09-13.md | 84 +++++++++++++++++++
 1 file changed, 84 insertions(+)

diff --git a/docs/development/sd-read-jitter-2026-09-13.md b/docs/development/sd-read-jitter-2026-09-13.md
index 6f706380..fafcbc15 100644
--- a/docs/development/sd-read-jitter-2026-09-13.md
+++ b/docs/development/sd-read-jitter-2026-09-13.md
@@ -179,3 +179,87 @@ causal test. **The read-free path (§6) stays valuable** — it also takes the 0
 the loop entirely — but it is no longer the only route to a stall-free trial.
 
 See `mode3-wedge-soak-plan.md` §10 for the timestamped log.
+
+## 8. Does the fix generalise to all patterns? (Michael's question, 2026-09-13 12:50 ET)
+
+**Under H-FAT: yes for any file size — the only condition is that the pattern file is contiguous on the card.**
+The stall trigger was not the pattern data but the FAT sectors that SdFat re-read from the card on every
+chain-walking seek. With `FILE_FLAG_CONTIGUOUS` set, a seek is arithmetic (`first_cluster + n`) and a frame read
+touches only the frame's own sectors — for a 20-frame grating and for a 2,000-frame, 8 MB sine alike. Nothing
+scales with file size except the one-time `contiguousRange()` walk at pattern open (one FAT sector per 128
+clusters = per 512 KB on this 4 KB-cluster card: an 8 MB pattern costs ~16 FAT-sector reads ≈ 10 ms, once, in
+the inter-trial interval).
+
+### 8.1 Where the reads go — old seek path vs fast path (SD card, 4 KB clusters)
+
+```
+SD card (logical)                       old path, backward seek to frame j        fast path
+┌──────────────┐
+│ FAT sector 0 │ ◄─ entries for clusters   1. walk chain from cluster 0:            (no FAT access;
+│ (128 × 4 B)  │    0..127 of the file        fatGet × j  → FAT sector 0            cluster = first + n)
+├──────────────┤                              (cache MISS if sector 1 was cached)
+│ FAT sector 1 │ ◄─ clusters 128..199      2. crossing cluster 128 → FAT sector 1
+│              │    (813 KB file = 200 cl.)    (MISS)  ← the hot spot: ~12k reads
+├──────────────┤                              of 2 sectors per 24.5k frame reads
+│ …            │
+├──────────────┤
+│ pattern data │  frame j = 4066 B at        3. CMD12 stop + CMD18 restart,          3. CMD12 + CMD18,
+│ 200 × 4066 B │  offset 18 + j·4066            8–9 sectors, ~0.6–0.9 ms                 8–9 sectors, ~0.6–0.9 ms
+│ (misaligned) │  (spans 2 clusters, so      4. one fatGet at the cluster boundary   4. cluster++ (no FAT)
+│              │   one boundary per read)       inside the read (cache hit/miss)
+└──────────────┘
+grating (81 KB = 20 clusters, 80 B of FAT): its whole chain sits in ONE FAT sector → always a cache hit → never a
+FAT read from the card → never a stall. That is the size dependence we saw — of the OLD path, not of the fix.
+```
+
+### 8.2 Timing per SET_FRAME_POSITION at 200 Hz (5 ms budget; measured medians)
+
+```
+              host send   USB/CDC   dispatch  skip?      readFrame                   wait tick   SPI      LEDs
+old, −1 seek  |──────────|·········|▌        |          |seek≈0.5 (FAT rd)|body 1.4|░░░░░░░░░░|▓▓▓▓ 0.77|~?
+              0          ~1 ms     t_rx                  ─── 2.0 ms ───────────────  0–3.3 ms   0.77 ms
+old, stall    |──────────|·········|▌        |          |seek: FAT read held by card housekeeping 33–89 ms ····|▓▓▓▓|
+                                                        └── display frozen, queued commands coalesced ──────┘
+new, −1 seek  |──────────|·········|▌        |          |seek 0|body 1.46 ms      |░░░░░░░░░░|▓▓▓▓ 0.77|
+new, +1 seek  |──────────|·········|▌        |          |0.62 ms (stream continues)|░░░░░░░░░░|▓▓▓▓|
+new, same idx |──────────|·········|▌ reply  |(no read) |                                        (frame already shown)
+measured new: req_age (dispatch → SPI start) p50 1.7 ms · p99 2.6 ms · max 4.8 ms;  superseded 0.5 % of frames
+```
+`░` = waiting for the next 300 Hz refresh tick (0–3.3 ms, phase-random); the panels latch after the transfer.
+
+### 8.3 Controller memory (Teensy 4.1, no external PSRAM) — why RAM caching, not the fix, has the size limit
+
+```
+OCRAM2  0x20200000 ┌──────────────────────────┐
+                   │ .bss.dma (DMAMEM) 55.7 KB │  SPI/DMA buffers, SdFat caches (data 512 B + FAT 512 B)
+        0x2020D9A0 ├──────────────────────────┤
+                   │ heap ↑                    │
+                   │                           │  ≈ 390 KiB unused today
+                   │  ← a frame/pattern cache  │  uncompressed: ≤ 97 GS16 frames (394 KB) or ≤ 370 GS2 frames
+                   │     would live here →     │  compressed (per-frame LZ4/zlib): the whole course library
+                   │                           │  (813 KB bar → 15 KB; 305 KB looming → ~30 KB; 8 MB sine → 374 KB)
+        0x2026F000 ├──────────────────────────┤
+                   │ telemetry ring 64 KiB     │  survives resets (fixed address)
+        0x2027F000 ├──────────────────────────┤
+                   │ Health ISR/wdog records,  │
+                   │ breadcrumb, CrashReport   │
+        0x20280000 └──────────────────────────┘
+DTCM (512 KB)      .data 32 KB + .bss 131 KB (frame_buf_ 4064 B, names_[] 32 KB, …) + stack; ~97 KB free
+```
+
+### 8.4 What still scales with the pattern, and the residual risks
+
+| effect | scales with size? | status |
+|---|---|---|
+| FAT reads during a trial (the stall trigger under H-FAT) | **no** — zero for any contiguous file | fixed (A) |
+| seek cost | **no** — arithmetic | fixed (A) |
+| per-read card latency (one CMD18 restart + 8–9 sectors) | no — 1.2–1.5 ms whatever the file | inherent to reading the card per frame; only the read-free path removes it |
+| read count | no — 0.76 per command after B | — |
+| read-disturb of the **data** region | yes, but the *other* way: a bigger file spreads its reads over more flash pages, so each page is read *less* often; a small working set is served from the card's cache | not observed in 5 M reads at 24.5k per cycle; a refresh of a data block would still be a 30–90 ms freeze — the per-trial flag catches it |
+| `contiguousRange()` at open | yes, ~1 FAT sector per 512 KB (4 KB clusters) | µs–ms, in the ITI |
+| **fragmentation** | independent of size, depends on card history | the one real precondition: `sd_layout` bit0 = 0 falls back to the old path (and its FAT reads). Make uploads contiguous (`preAllocate` on 0x8D) and have the Studio warn on a fragmented pattern |
+
+So: **for every pattern that is stored contiguously, the same code path runs and the FAT is never touched during
+a trial — no size limit.** The read-free path (§6) is the one with a size ceiling (RAM), and its value is now the
+remaining 0.6–1.5 ms per read and the theoretical data-region disturb, not the 30–90 ms stalls. The causal test
+(`sd-stall-causal-test-plan-2026-09-13.md`) is what turns "under H-FAT" into a statement of fact.

From a4ced8380dfb3b53001d3cd08e7cfde9de1d01bf Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 12:40:42 -0400
Subject: [PATCH 16/67] fix(telemetry): STATE kind 14 sd_reads_ckpt (kind 13
 keeps its meaning), 0xCB bit 6 gates SET_SD_DIAG, GET_SD_INFO byte 29 bit 2 =
 legacy seek applied

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 arena_studio.html              | 4 ++--
 js/arena-telemetry.js          | 9 +++++----
 js/arena-wire-g6.js            | 8 +++++---
 js/trial-quality.js            | 5 ++---
 scripts/telemetry-report.py    | 6 +++---
 scripts/wedge-scan.py          | 1 +
 tests/test-arena-telemetry.js  | 4 ++--
 tests/test-telemetry-report.py | 2 +-
 8 files changed, 21 insertions(+), 18 deletions(-)

diff --git a/arena_studio.html b/arena_studio.html
index ebcc4225..d2a5a622 100644
--- a/arena_studio.html
+++ b/arena_studio.html
@@ -8408,8 +8408,8 @@ <h2 id="modalTitle">Import error</h2>
 // records the arm. Console: `await Studio.setSdDiag(1)` … `await Studio.setSdDiag(0)`.
 Studio.setSdDiag = async function (flags) {
     const fv = Studio.firmwareVersion;
-    if (!fv || !fv.sdFastPath || !Wire.encodeSetSdDiag || !Studio.session || !Studio.session.connected) {
-        Studio.rawLog('sd diag: firmware has no SD fast path (0xCB bit 5) or not connected', 'warn');
+    if (!fv || !fv.sdDiag || !Wire.encodeSetSdDiag || !Studio.session || !Studio.session.connected) {
+        Studio.rawLog('sd diag: firmware has no SET_SD_DIAG (0xCB bit 6) or not connected', 'warn');
         return null;
     }
     const r = Wire.decodeResponse(await Studio.session.send(Wire.encodeSetSdDiag(flags), { timeoutMs: 2000 }));
diff --git a/js/arena-telemetry.js b/js/arena-telemetry.js
index 3bb2205c..e2dad8d7 100644
--- a/js/arena-telemetry.js
+++ b/js/arena-telemetry.js
@@ -55,7 +55,8 @@
         10: 'timer_fail', // IntervalTimer::begin() failed: arg = requested refresh rate (Hz)
         11: 'sd_layout', // after sd_open: code bit0 contiguous file, bit1 exFAT; arg = sectors/cluster
         12: 'sd_slow_ctx', // follows sd_slow: code = SdFat card errorCode() (sticky), arg = errorData() >> 16 (USDHC error bits)
-        13: 'sd_reads' // at STOP / next trial start: reads = arg << code (readFrame calls while that pattern was open)
+        13: 'sd_reads', // at STOP / next trial start: reads = arg << code (readFrame calls while that pattern was open)
+        14: 'sd_reads_ckpt' // every 30k reads while open: cumulative so far = arg << code (lower bound if the run dies)
     };
     // sd_slow (kind 4) code byte, ring v2: bits 0-1 = slowest phase of the read, bit 7 = read error.
     const SD_SLOW_PHASES = ['unknown', 'seek', 'body', 'tail'];
@@ -202,9 +203,9 @@
                     rec.irqstatHi = rec.arg; // USDHC IRQSTAT bits 16-31 at the driver's LAST error
                     rec.driverSawError = rec.code !== 0;
                 }
-                if (rec.stateKind === 13) {
-                    rec.reads = rec.arg * Math.pow(2, rec.code & 0x7f); // code bits 0-6 = binary shift
-                    rec.checkpoint = !!(rec.code & 0x80); // cumulative mid-open checkpoint (every 30k reads), not a close
+                if (rec.stateKind === 13 || rec.stateKind === 14) {
+                    rec.reads = rec.arg * Math.pow(2, rec.code); // code = binary shift
+                    rec.checkpoint = rec.stateKind === 14; // 14: cumulative so far (lower bound); 13: final for that open
                 }
             } else {
                 rec.kind = 'unknown';
diff --git a/js/arena-wire-g6.js b/js/arena-wire-g6.js
index de45516d..acc3da73 100644
--- a/js/arena-wire-g6.js
+++ b/js/arena-wire-g6.js
@@ -959,6 +959,7 @@ const ArenaWireG6 = (function () {
             crashReport: !!(m[3] & 0x08), // GET_CRASHREPORT 0xCC + GET_HEALTH ver 2 (fw fb11681+): the ONLY gate for 0xCC
             freeRunningTimer: !!(m[3] & 0x10), // fw eca07f6+: SET_FRAME_POSITION never disarms/re-arms the refresh timer
             sdFastPath: !!(m[3] & 0x20), // fw 200fada+: O(1) seeks, same-index skip, 26 B FRAME (ring v2), GET_SD_INFO 0xCD — the ONLY gate for 0xCD
+            sdDiag: !!(m[3] & 0x40), // fw 2c83f45+: SET_SD_DIAG 0xCE + STATE kind 14 — the ONLY gate for 0xCE
             sha: ascii(4, 8),
             date: ascii(12, 10),
             branch: ascii(22, 24)
@@ -1061,8 +1062,9 @@ const ArenaWireG6 = (function () {
             mdtMonth: cid[14] & 0x0f,
             sdStatusMaint: m[28],
             sdDiag: m[29], // SET_SD_DIAG flags in force (0 = production behaviour)
-            legacySeek: !!(m[29] & 0x01),
-            noSameIndexSkip: !!(m[29] & 0x02)
+            legacySeek: !!(m[29] & 0x01), // requested (next open)
+            noSameIndexSkip: !!(m[29] & 0x02),
+            legacySeekApplied: !!(m[29] & 0x04) // in force for the currently open file
         };
         v.psnHex = v.psn.toString(16).padStart(8, '0');
         v.label = !v.mounted
@@ -1089,7 +1091,7 @@ const ArenaWireG6 = (function () {
                   ? v.bytesPerCluster / 1024 + ' KiB'
                   : v.bytesPerCluster + ' B') +
               ' clusters' +
-              (v.sdDiag
+              (v.sdDiag & 0x03
                   ? ' [diag ' +
                     (v.legacySeek ? 'legacy-seek ' : '') +
                     (v.noSameIndexSkip ? 'no-skip' : '') +
diff --git a/js/trial-quality.js b/js/trial-quality.js
index bdadd423..f8db7697 100644
--- a/js/trial-quality.js
+++ b/js/trial-quality.js
@@ -164,13 +164,12 @@
                             }
                             break;
                         }
+                        case 14: // sd_reads_ckpt: cumulative so far (lower bound)
                         case 13: // sd_reads for the pattern being left
                             // checkpoints (code bit 7) and the closing record are cumulative: keep the largest
                             if (current) {
                                 const v =
-                                    r.reads != null
-                                        ? r.reads
-                                        : r.arg * Math.pow(2, (r.code || 0) & 0x7f);
+                                    r.reads != null ? r.reads : r.arg * Math.pow(2, r.code || 0);
                                 if (current.reads == null || v > current.reads) current.reads = v;
                             }
                             break;
diff --git a/scripts/telemetry-report.py b/scripts/telemetry-report.py
index e152fa46..f1ce75c4 100644
--- a/scripts/telemetry-report.py
+++ b/scripts/telemetry-report.py
@@ -48,7 +48,7 @@
 
 STATE_KINDS = {1: "boot", 2: "state_change", 3: "error_glyph", 4: "sd_slow", 5: "ring_overrun", 6: "telemetry",
                7: "sd_open", 8: "wdog_context", 9: "prev_isr_count", 10: "timer_fail", 11: "sd_layout",
-               12: "sd_slow_ctx", 13: "sd_reads"}
+               12: "sd_slow_ctx", 13: "sd_reads", 14: "sd_reads_ckpt"}
 SD_SLOW_PHASES = ["unknown", "seek", "body", "tail"]
 CLUSTER_GAP_S = 5.0
 STEP_CLASSES = ("+1", "-1", "+2..9", "-2..-9", "jump>=10", "first-after-open", "other")
@@ -255,8 +255,8 @@ def analyze_file(path: str, gap_ms: float = 10.0, target_ms: float = 5.0) -> dic
                 elif kind == 12:
                     if stalls and stalls[-1]["ctx"] is None:
                         stalls[-1]["ctx"] = {"card_error_code": code, "irqstat_hi": arg, "driver_saw_error": bool(code)}
-                elif kind == 13:
-                    shift = (code & 0x7F) if isinstance(code, int) else 0   # bits 0-6 = binary shift; bit 7 = mid-open checkpoint
+                elif kind in (13, 14):
+                    shift = code if isinstance(code, int) else 0   # binary shift; 14 = mid-open checkpoint (cumulative), 13 = final
                     reads = arg << shift
                     if cur is not None:
                         # checkpoints and the closing record are cumulative for the same open: keep the largest,
diff --git a/scripts/wedge-scan.py b/scripts/wedge-scan.py
index cf05d774..704508f2 100644
--- a/scripts/wedge-scan.py
+++ b/scripts/wedge-scan.py
@@ -88,6 +88,7 @@
     11: "sd_layout",  # after sd_open: code bit0 contiguous file, bit1 exFAT; arg = sectors/cluster (fw sd_fastpath)
     12: "sd_slow_ctx",  # follows sd_slow: code = SdFat card errorCode(), arg = errorData() & 0xFFFF
     13: "sd_reads",  # at STOP / next trial start: arg = readFrame calls while that pattern was open
+    14: "sd_reads_ckpt",  # every 30k reads while open: cumulative so far = arg << code
 }
 ISR_NAMES = ["none", "refresh_timer", "spi_dma", "watchdog", "usb", "sdhc", "lpspi", "pit"]
 
diff --git a/tests/test-arena-telemetry.js b/tests/test-arena-telemetry.js
index 18c36264..759d30c3 100644
--- a/tests/test-arena-telemetry.js
+++ b/tests/test-arena-telemetry.js
@@ -239,7 +239,7 @@ function block(h, records) {
                 stateRec(21, 3100, 4, 0x82, 887), // sd_slow: body phase, read error, 88.7 ms
                 stateRec(22, 3200, 11, 0x01, 8), // sd_layout: contiguous, FAT32, 8 sectors/cluster
                 stateRec(23, 3300, 12, 0, 1), // sd_slow_ctx
-                stateRec(24, 3400, 13, 0x83, 45000) // sd_reads checkpoint: 45000 << 3 = 360000, bit 7 = checkpoint
+                stateRec(24, 3400, 14, 3, 45000) // sd_reads_ckpt: 45000 << 3 = 360000 (cumulative checkpoint)
             ]),
             Wire
         );
@@ -293,7 +293,7 @@ function block(h, records) {
                 b2.records[4].reads,
                 b2.records[4].checkpoint
             ],
-            ['sd_slow_ctx', 0, false, 'sd_reads', 360000, true]
+            ['sd_slow_ctx', 0, false, 'sd_reads_ckpt', 360000, true]
         );
         check('v2 malformed = 0', b2.malformed, 0);
         const rows2 = T.toRows(b2, 1);
diff --git a/tests/test-telemetry-report.py b/tests/test-telemetry-report.py
index 3f630730..41920c26 100644
--- a/tests/test-telemetry-report.py
+++ b/tests/test-telemetry-report.py
@@ -86,7 +86,7 @@ def cf(idx, pattern, sd, age=4700, sup=0, flags=3):
     cs(4, 2, 671); cs(12, 0, 0)
     cf(idx + 1, 36, 67100, age=69000)
     cs(4, 2, 80)                          # 8 ms: slow by fw threshold, not over 10 ms
-    cs(13, 0x80, 30)                      # mid-open checkpoint (cumulative), superseded by the close below
+    cs(14, 0, 30)                         # mid-open checkpoint (cumulative), superseded by the close below
     cs(13, 0, reads + 1)
     # trial 2: pattern 5 (20 frames), clean, one repeated index
     cs(7, 0, 5)

From 627d94efe969ac17d660e8bc34daba58ef0abfaf Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 13:18:28 -0400
Subject: [PATCH 17/67] =?UTF-8?q?docs:=20causal-test=20plan=20=E2=80=94=20?=
 =?UTF-8?q?round-3=20prerequisites=20(bit=206,=20applied-mode=20byte,=20ex?=
 =?UTF-8?q?FAT=20caveat)=20+=20=C2=A77=20extended=20multi-hour=20campaign?=
 =?UTF-8?q?=20(patterns=20=C3=97=20Mode=202/3=20=C3=97=20speeds);=20bench?=
 =?UTF-8?q?=20log?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/development/mode3-wedge-soak-plan.md     | 11 ++++++
 .../sd-stall-causal-test-plan-2026-09-13.md   | 38 ++++++++++++++++++-
 2 files changed, 47 insertions(+), 2 deletions(-)

diff --git a/docs/development/mode3-wedge-soak-plan.md b/docs/development/mode3-wedge-soak-plan.md
index 583dc135..d82473ad 100644
--- a/docs/development/mode3-wedge-soak-plan.md
+++ b/docs/development/mode3-wedge-soak-plan.md
@@ -421,6 +421,17 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   stopping rules and procedure: `docs/development/sd-stall-causal-test-plan-2026-09-13.md` (arms 3 → 1 → 2 → 0 on one
   build, ~70 min; H-FAT fingerprint = `sd_slow` phase `seek` in the legacy-seek arms).
 
+- **2026-09-13 13:00 ET — Codex round 3 on the 0xCE build (`.codex-review/codex-diff-review-20260913-123149-22302`):**
+  blocking — `openPattern` reused the open handle on a same-pattern restart, so the legacy-seek arm would not have
+  applied there (fixed `35bb196`: reopen when the applied mode differs; 0xCD byte 29 bit 2 = applied); also fixed:
+  cache reuse separated from presentation accounting (`sd_cache_ok_`), checkpoints as STATE kind 14 (kind 13 unchanged),
+  0xCB bit 6 gates 0xCE, exFAT caveat documented; harness `sd_stall_test.py` hardened (capture completeness incl.
+  trial open/close + command reconciliation + incarnation check, exact over-gap counter, block-anchored wrap-safe
+  controller time, bounded stall detail, per-open read totals, resync after a timeout, `--sd-diag N` arm with
+  applied-mode verification, exit 4 unless usable). Firmware tip built, NOT flashed; a Codex diff review of the
+  round-3 delta is owed before it goes on the controller. Extended campaign matrix (patterns × Mode 2/3 × speeds)
+  added to `sd-stall-causal-test-plan-2026-09-13.md` §7.
+
 ## 11. T4 as built (2026-09-12) — soak with ring-buffer logging
 
 Decision (Michael, 11:30 ET): skip the instrument-dependent T2/T3 for now; build the ring (T1
diff --git a/docs/development/sd-stall-causal-test-plan-2026-09-13.md b/docs/development/sd-stall-causal-test-plan-2026-09-13.md
index 8c523a92..0ae18859 100644
--- a/docs/development/sd-stall-causal-test-plan-2026-09-13.md
+++ b/docs/development/sd-stall-causal-test-plan-2026-09-13.md
@@ -2,8 +2,10 @@
 
 **Written:** 2026-09-13 12:45 ET. **Status:** code ready (firmware `feat/sd-fastpath-2x10` with `SET_SD_DIAG` 0xCE,
 built, Codex review round 3 in progress; Studio v0.77 `Studio.setSdDiag`), **bench test pending** (Michael: no time
-today). **Prerequisite:** flash the reviewed 0xCE build via `scripts/flash_bootloader_route.sh` (port released by the
-Studio first), verify 0xCB label `… freerun sdfast` and `GET_SD_INFO` byte 29 = 0.
+today). **Prerequisite:** flash the reviewed 0xCE build (firmware tip after `35bb196`; run a Codex diff review of anything
+newer first) via `scripts/flash_bootloader_route.sh` (port released by the Studio first), verify 0xCB flags bit 6
+(`sdDiag`), label `… freerun sdfast`, and `GET_SD_INFO` byte 29 = 0. The legacy-seek arm only reproduces the FAT-chain
+walk on FAT16/32 volumes (the bench card is FAT32); byte 29 bit 2 reports the mode actually applied to the open file.
 
 ## 1. What we know and what is still only correlational
 
@@ -106,3 +108,35 @@ result table to `sd-read-jitter-2026-09-13.md` §7.
 Arm 1 clean but arm 3 stalls ⇒ B (read count) is what matters ⇒ H-count: the card's counter is per read; the
 read-free path becomes the priority again and the card comparison matters. Arm 3 clean ⇒ the card changed (or the
 morning's upload moved something) ⇒ characterise afresh with `sd_stall_test.py` before any conclusion.
+
+
+## 7. Extended validation campaign (multi-hour, later) — patterns × modes × speeds
+
+Purpose: after the causal test, establish the **operating envelope** of the fast-path build with the per-trial
+quality verdicts as the acceptance metric (target 5 ms, worst case 10 ms, ≥ 30 ms invalidates), not just "no wedge".
+Each cell below is one soak protocol (Studio, `?soak=1`, behavior_v2 logging, telemetry on) analysed with
+`scripts/telemetry-report.py`; the firmware stays fixed for the whole campaign.
+
+| axis | levels | why |
+|---|---|---|
+| pattern size / geometry | grating 20 f (81 KB) · bar 200 f (813 KB) · looming 75 f (305 KB) · a 2,000-frame sine (8 MB, GS16) · a GS2 200-frame pattern (213 KB) | FAT-chain length (1 → 2 → 16 FAT sectors), file span, frame size (1 vs 4 KB reads) |
+| mode | **3** (host-stepped, sim random walk + jumps) · **2** (controller-timed open loop at the pattern's frame rate) · 3 with a *sequential* index sweep | Mode 2 is the sequential-read control (no seeks at all, should be stall-free at any size); Mode 3 random is the stress; sequential Mode 3 separates seek cost from command load |
+| speed | Mode 3: 100 / 200 / 286 Hz commands; Mode 2: 50 / 100 / 200 fps | read rate (stall recurrence is count-based), tick starvation (300 Hz refresh), USB load |
+| duration | ≥ 1 h per cell (≈ 3 iterations); the bar-pattern cells ≥ 3 h (≈ 40 baseline stall cycles) | zero clusters in 1 h ⇒ 95 % upper bound ≈ 3 clusters/h; the long cells are the "still clean after N× the old period" evidence |
+| card | current card (baseline, never reformatted) first; candidates later via `sd_stall_test.py` screens | keep the card fixed while the firmware envelope is measured |
+
+**Predictions under H-FAT (fast path):** no stall in any cell; per-read cost 0.62 ms sequential / 1.2–1.5 ms random
+for every size (the 8 MB sine included); `req_age_us` max < 5 ms at 100–200 Hz, some frames over 5 ms at 286 Hz
+(tick coalescing, not SD); Mode 2 `superseded` ≈ 0. **Fail signatures to watch:** any `sd_slow` in the 8 MB or
+GS2 cells (a data-region disturb with size/geometry dependence), phase `body` with error bits (driver), `unknown`
+trials (coverage — drain budget at 286 Hz).
+
+**Order:** bar 200 f, Mode 3, 200 Hz, 3 h (continuation of today's evidence) → 8 MB sine Mode 3 200 Hz 1 h →
+Mode 2 controls (bar 100 fps, sine 100 fps) 1 h each → 286 Hz Mode 3 bar 1 h → 100 Hz Mode 3 bar 1 h (course
+rate) → GS2 + looming 1 h each. Roughly one bench day. Report per cell: the `telemetry-report.py` tables +
+`trial_quality` counts, into `sd-read-jitter-2026-09-13.md` §7.
+
+Things the campaign will need that do not exist yet: the 2,000-frame sine and GS2 200-frame patterns on the card
+(upload via the Studio, contiguous — check `sd_layout` bit0), a Mode-2 soak protocol (trialParams mode 2 with
+`frame_rate`, no FicTrac plugin), and the frame-count-from-0x88 fix (#201) so the `__framesRepatch` hook is not
+needed for new patterns.

From b0a6ce7f29d8f3f58c11f98ee3145c51d6d1bcce Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 13:43:26 -0400
Subject: [PATCH 18/67] =?UTF-8?q?feat(soak):=20stress-first=20SD=20campaig?=
 =?UTF-8?q?n=20=E2=80=94=20soak=5Fmode3=5Fstress.yaml=20(8=20MB=20sine=20+?=
 =?UTF-8?q?=20bar=20at=20286=20Hz),=20soak=5Fmode2=5Fopen=5Floop.yaml=20(s?=
 =?UTF-8?q?equential=20control),=20make-stress-patterns.js;=20soak=20drive?=
 =?UTF-8?q?r=20accepts=20open-loop=20protocols=20(Studio=20v0.77);=20plan?=
 =?UTF-8?q?=20=C2=A77=20trimmed,=20=C2=A75=20extent-table=20next=20step,?=
 =?UTF-8?q?=20round-4=20review=20state;=20bench=20log?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .gitignore                                    |   1 +
 arena_studio.html                             |  17 ++-
 .../development/arena-studio-release-notes.md |   5 +
 docs/development/mode3-wedge-soak-plan.md     |  11 ++
 .../sd-stall-causal-test-plan-2026-09-13.md   |  80 +++++-----
 protocols/soak_mode2_open_loop.yaml           |  94 ++++++++++++
 protocols/soak_mode3_stress.yaml              | 137 ++++++++++++++++++
 scripts/make-stress-patterns.js               |  95 ++++++++++++
 8 files changed, 401 insertions(+), 39 deletions(-)
 create mode 100644 protocols/soak_mode2_open_loop.yaml
 create mode 100644 protocols/soak_mode3_stress.yaml
 create mode 100644 scripts/make-stress-patterns.js

diff --git a/.gitignore b/.gitignore
index 298538f4..904e4dc1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -11,3 +11,4 @@ test_patterns/
 __pycache__/
 *.pyc
 *.jsonl
+soak-patterns/
diff --git a/arena_studio.html b/arena_studio.html
index d2a5a622..7500253f 100644
--- a/arena_studio.html
+++ b/arena_studio.html
@@ -2959,7 +2959,7 @@ <h2 id="modalTitle">Import error</h2>
 </div>
 
 <footer id="footer">
-  <span class="foot-left">Arena Studio v0.77 | 2026-09-13 12:32 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.77 | 2026-09-13 13:58 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)">
@@ -8189,9 +8189,13 @@ <h2 id="modalTitle">Import error</h2>
         return;
     }
     // Input freshness: without simulator/FicTrac frames a Mode-3 soak drives nothing.
+    // An OPEN-LOOP soak (no fictrac plugin in the protocol — e.g. the Mode-2 SD
+    // control, protocols/soak_mode2_open_loop.yaml) needs the bridge only as the
+    // run logger: skip the frames gate and the applied-0x70 exposure test.
+    const closedLoop = fictracPluginNames(doc.experiment).length > 0;
     let rate = bridge.stats ? bridge.stats.rateHz : 0;
-    if (!(rate > 0)) { await sleepMs(1500); rate = bridge.stats ? bridge.stats.rateHz : 0; }
-    if (!(rate > 0)) { Studio.showBanner('Soak refused: no FicTrac frames arriving at the bridge — start `pixi run sim -- --count 0 --rate 100`.'); return; }
+    if (closedLoop && !(rate > 0)) { await sleepMs(1500); rate = bridge.stats ? bridge.stats.rateHz : 0; }
+    if (closedLoop && !(rate > 0)) { Studio.showBanner('Soak refused: no FicTrac frames arriving at the bridge — start `pixi run sim -- --count 0 --rate 100`.'); return; }
     const s = Studio.soak = Object.assign({}, SOAK_DEFAULTS, cfg || {}, {
         iteration: 0, faults: 0, resets: 0, stop: false, stopReason: null, startedMs: Date.now(),
         untilMs: 0
@@ -8202,7 +8206,7 @@ <h2 id="modalTitle">Import error</h2>
     const logSoak = (o) => { if (bridge.logging) bridge.log(Object.assign({ event: 'soak' }, o)); };
     const desc = (s.iterations ? s.iterations + ' iterations' : 'until stopped') + (s.hours ? ', ≤ ' + s.hours + ' h' : '') +
         ', gap ' + s.gapS + ' s, first fault: ' + s.firstFault + ', then: ' + s.policy + ' (max ' + s.maxResets + ' resets)';
-    logSoak({ phase: 'start', protocol: doc.filename, sha256: doc.sha256, config: { iterations: s.iterations, hours: s.hours, gap_s: s.gapS, first_fault: s.firstFault, policy: s.policy, max_resets: s.maxResets }, sim_rate_hz: rate });
+    logSoak({ phase: 'start', protocol: doc.filename, sha256: doc.sha256, config: { iterations: s.iterations, hours: s.hours, gap_s: s.gapS, first_fault: s.firstFault, policy: s.policy, max_resets: s.maxResets }, sim_rate_hz: rate, closed_loop: closedLoop });
     Studio.rawLog('soak started — ' + desc, 'info');
     Studio.showBanner('Soak running — ' + desc + '. File ▾ → Soak… to stop.');
     (async () => {
@@ -8227,7 +8231,9 @@ <h2 id="modalTitle">Import error</h2>
                 // 'unexercised', not 'completed' — it must not count as clean soak time.
                 const applied = (bridge.stats ? bridge.stats.applied : 0) - applied0;
                 const durS = (Date.now() - t0) / 1000;
-                const exercised = applied >= Math.min(1000, 5 * durS); // ≥ 5 Hz average, or 1000 total
+                // Open loop: the controller steps the pattern itself (no 0x70s) — exposure is
+                // in the telemetry FRAME rows, judged by telemetry-report.py, not here.
+                const exercised = !closedLoop || applied >= Math.min(1000, 5 * durS); // ≥ 5 Hz average, or 1000 total
                 let outcome = !res ? 'not-started' : res.fault ? 'fault' : res.aborted ? 'aborted' : exercised ? 'completed' : 'unexercised';
                 logSoak({
                     phase: 'iteration-end', iteration: s.iteration,
@@ -8261,6 +8267,7 @@ <h2 id="modalTitle">Import error</h2>
                     for (let i = 0; i < 40 && !bridge.connected; i++) await sleepMs(50);
                     await sleepMs(1200); // one rate-timer tick so rateHz is fresh
                 }
+                if (!closedLoop) { if (!bridge.connected) { reason = 'bridge-lost'; break; } continue; }
                 let r2 = bridge.stats ? bridge.stats.rateHz : 0;
                 let waited = 0;
                 while (!(r2 > 0) && !s.stop && waited < 600) {
diff --git a/docs/development/arena-studio-release-notes.md b/docs/development/arena-studio-release-notes.md
index 4f8e7298..a6f1ea3a 100644
--- a/docs/development/arena-studio-release-notes.md
+++ b/docs/development/arena-studio-release-notes.md
@@ -26,6 +26,11 @@ history lives here. Newest first. (Per-session engineering detail stays in
 - Bench A/B helper `Studio.setSdDiag(flags)` (firmware with `SET_SD_DIAG` 0xCE): forces the legacy FAT-chain
   seek and/or disables the same-index read skip per iteration for the causal test of the card stalls
   (`docs/development/sd-stall-causal-test-plan-2026-09-13.md`); the arm is recorded in `run_metadata.sd_card.sd_diag`.
+- **Open-loop soak.** The soak driver accepts protocols without a FicTrac plugin (e.g. the Mode-2
+  SD control `protocols/soak_mode2_open_loop.yaml`): the bridge is still the logger, but the
+  "simulator frames arriving" gate and the 0x70 exposure test are skipped. New campaign protocols
+  `soak_mode3_stress.yaml` (8 MB sine + 813 KB bar at 286 Hz) and the generator
+  `scripts/make-stress-patterns.js`.
 
 ## v0.76 (2026-09-11) · Controller-fault detection, post-mortem probes, soak driver (fw #50)
 
diff --git a/docs/development/mode3-wedge-soak-plan.md b/docs/development/mode3-wedge-soak-plan.md
index d82473ad..a6b313e6 100644
--- a/docs/development/mode3-wedge-soak-plan.md
+++ b/docs/development/mode3-wedge-soak-plan.md
@@ -431,6 +431,17 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   applied-mode verification, exit 4 unless usable). Firmware tip built, NOT flashed; a Codex diff review of the
   round-3 delta is owed before it goes on the controller. Extended campaign matrix (patterns × Mode 2/3 × speeds)
   added to `sd-stall-causal-test-plan-2026-09-13.md` §7.
+- **2026-09-13 13:30–14:15 ET — Michael back online (remote, no bench). Codex round 4 on the round-3 delta
+  (`0fc6b01..9de97fe`, `.codex-review/codex-diff-review-20260913-133230-26229`, report `report-20260913-fw-round4.md`):
+  no blocking firmware finding; harness/codec fixes committed as `75405ee` (exact worst/cluster statistics, legacy
+  kind-13 checkpoint decode, `--allow-v1` completion, single-probe resync, arm restore + consistency, exFAT refusal,
+  offline `tests/test_sd_stall_stats.py`, two stale comments) and built — **`75405ee` is the build to flash next
+  session** (bootloader route, port released first). Campaign trimmed to stress-first (plan §7: S1 8 MB sine + 813 KB
+  bar at 286 Hz overnight, S2 at 200 Hz, C1 Mode-2 200 fps control); new `protocols/soak_mode3_stress.yaml`,
+  `protocols/soak_mode2_open_loop.yaml`, `scripts/make-stress-patterns.js` (8.1 MB `sine_2000f_gs16`, 213 KB
+  `bar_200f_gs2`, verified by re-parse), Studio soak driver accepts open-loop protocols (v0.77, 13:58 ET). Michael's
+  design question answered in plan §5: cache the cluster chain per pattern open (extent table) → no contiguity
+  precondition; to implement after the causal test.
 
 ## 11. T4 as built (2026-09-12) — soak with ring-buffer logging
 
diff --git a/docs/development/sd-stall-causal-test-plan-2026-09-13.md b/docs/development/sd-stall-causal-test-plan-2026-09-13.md
index 0ae18859..84aaa265 100644
--- a/docs/development/sd-stall-causal-test-plan-2026-09-13.md
+++ b/docs/development/sd-stall-causal-test-plan-2026-09-13.md
@@ -1,9 +1,10 @@
 # Causal test plan — did the contiguous-seek fix remove the SD-card stalls? (bench, ~70 min)
 
-**Written:** 2026-09-13 12:45 ET. **Status:** code ready (firmware `feat/sd-fastpath-2x10` with `SET_SD_DIAG` 0xCE,
-built, Codex review round 3 in progress; Studio v0.77 `Studio.setSdDiag`), **bench test pending** (Michael: no time
-today). **Prerequisite:** flash the reviewed 0xCE build (firmware tip after `35bb196`; run a Codex diff review of anything
-newer first) via `scripts/flash_bootloader_route.sh` (port released by the Studio first), verify 0xCB flags bit 6
+**Written:** 2026-09-13 12:45 ET; updated 14:15 ET. **Status:** code ready and **reviewed** (firmware
+`feat/sd-fastpath-2x10` tip `75405ee`: `SET_SD_DIAG` 0xCE, Codex rounds 3 + 4 reconciled in the ring worktree's
+`.codex-review/report-20260913-fw-round4.md`; Studio v0.77 `Studio.setSdDiag`), **bench test pending**.
+**Prerequisite:** flash `75405ee` (built `.pio/build/teensy41-performance/firmware.hex`; anything newer needs its own
+Codex diff review) via `scripts/flash_bootloader_route.sh` (port released by the Studio first), verify 0xCB flags bit 6
 (`sdDiag`), label `… freerun sdfast`, and `GET_SD_INFO` byte 29 = 0. The legacy-seek arm only reproduces the FAT-chain
 walk on FAT16/32 volumes (the bench card is FAT32); byte 29 bit 2 reports the mode actually applied to the open file.
 
@@ -98,6 +99,15 @@ result table to `sd-read-jitter-2026-09-13.md` §7.
   (`sd_layout` bit0 = 0) and made contiguous (`preAllocate` on upload, or re-upload).
 - Course cards: check cluster size with `GET_SD_INFO`; a 32 KB-cluster format keeps even 4 MB patterns in one FAT
   sector — but the fast path makes that moot.
+- **Next firmware step (Michael, 13:40 ET): drop the contiguity precondition by caching the file's cluster chain in
+  RAM at pattern open** — read the FAT once per open (in the inter-trial interval), store it as a list of contiguous
+  extents (a contiguous file is one extent; an 8 MB file on 4 KB clusters is at most 2000 entries = 8 KB), and turn
+  every frame seek into table lookup + sector arithmetic. Random access is then O(1) inside any pattern file, fragmented
+  or not, and the FAT is never touched during a trial; `sd_layout` bit0 becomes informational. Small change in
+  `SdManager` (SdFat exposes the FAT lookup and cluster→sector helpers its own seek uses); implement after the causal
+  test so the production arm measured here stays the one on the card. Ensuring contiguity at upload (`preAllocate`
+  on 0x8D, or the Studio's purge-and-reupload set flow) stays worthwhile for sequential read speed but stops being a
+  correctness condition.
 - The read-free path (`sd-read-jitter-2026-09-13.md` §6) remains the way to remove the 0.6–1.5 ms read and the card
   from the loop entirely; it is no longer required to reach the 10 ms bound.
 - fw #54: close the "card housekeeping" mitigation thread with this result; the card-comparison protocol becomes
@@ -110,33 +120,35 @@ read-free path becomes the priority again and the card comparison matters. Arm 3
 morning's upload moved something) ⇒ characterise afresh with `sd_stall_test.py` before any conclusion.
 
 
-## 7. Extended validation campaign (multi-hour, later) — patterns × modes × speeds
-
-Purpose: after the causal test, establish the **operating envelope** of the fast-path build with the per-trial
-quality verdicts as the acceptance metric (target 5 ms, worst case 10 ms, ≥ 30 ms invalidates), not just "no wedge".
-Each cell below is one soak protocol (Studio, `?soak=1`, behavior_v2 logging, telemetry on) analysed with
-`scripts/telemetry-report.py`; the firmware stays fixed for the whole campaign.
-
-| axis | levels | why |
-|---|---|---|
-| pattern size / geometry | grating 20 f (81 KB) · bar 200 f (813 KB) · looming 75 f (305 KB) · a 2,000-frame sine (8 MB, GS16) · a GS2 200-frame pattern (213 KB) | FAT-chain length (1 → 2 → 16 FAT sectors), file span, frame size (1 vs 4 KB reads) |
-| mode | **3** (host-stepped, sim random walk + jumps) · **2** (controller-timed open loop at the pattern's frame rate) · 3 with a *sequential* index sweep | Mode 2 is the sequential-read control (no seeks at all, should be stall-free at any size); Mode 3 random is the stress; sequential Mode 3 separates seek cost from command load |
-| speed | Mode 3: 100 / 200 / 286 Hz commands; Mode 2: 50 / 100 / 200 fps | read rate (stall recurrence is count-based), tick starvation (300 Hz refresh), USB load |
-| duration | ≥ 1 h per cell (≈ 3 iterations); the bar-pattern cells ≥ 3 h (≈ 40 baseline stall cycles) | zero clusters in 1 h ⇒ 95 % upper bound ≈ 3 clusters/h; the long cells are the "still clean after N× the old period" evidence |
-| card | current card (baseline, never reformatted) first; candidates later via `sd_stall_test.py` screens | keep the card fixed while the firmware envelope is measured |
-
-**Predictions under H-FAT (fast path):** no stall in any cell; per-read cost 0.62 ms sequential / 1.2–1.5 ms random
-for every size (the 8 MB sine included); `req_age_us` max < 5 ms at 100–200 Hz, some frames over 5 ms at 286 Hz
-(tick coalescing, not SD); Mode 2 `superseded` ≈ 0. **Fail signatures to watch:** any `sd_slow` in the 8 MB or
-GS2 cells (a data-region disturb with size/geometry dependence), phase `body` with error bits (driver), `unknown`
-trials (coverage — drain budget at 286 Hz).
-
-**Order:** bar 200 f, Mode 3, 200 Hz, 3 h (continuation of today's evidence) → 8 MB sine Mode 3 200 Hz 1 h →
-Mode 2 controls (bar 100 fps, sine 100 fps) 1 h each → 286 Hz Mode 3 bar 1 h → 100 Hz Mode 3 bar 1 h (course
-rate) → GS2 + looming 1 h each. Roughly one bench day. Report per cell: the `telemetry-report.py` tables +
-`trial_quality` counts, into `sd-read-jitter-2026-09-13.md` §7.
-
-Things the campaign will need that do not exist yet: the 2,000-frame sine and GS2 200-frame patterns on the card
-(upload via the Studio, contiguous — check `sd_layout` bit0), a Mode-2 soak protocol (trialParams mode 2 with
-`frame_rate`, no FicTrac plugin), and the frame-count-from-0x88 fix (#201) so the `__framesRepatch` hook is not
-needed for new patterns.
+## 7. Multi-hour campaign (later) — stress first, controls second
+
+**Design principle (Michael, 13:30 ET): test the worst case, not the grid.** Under H-FAT the per-read cost is
+independent of file size once the file is contiguous, and a bigger file at a higher command rate can only make a
+hidden problem MORE visible (longer chain, wider seeks, more reads per hour). So the campaign is two overnight
+soaks plus one short control, all judged by the per-trial `trial_quality` verdicts (target 5 ms, worst case 10 ms,
+≥ 30 ms invalidates) and `scripts/telemetry-report.py` — not a patterns × modes × speeds matrix.
+
+| # | protocol (repo) | what | why it is the stress | duration |
+|---|---|---|---|---|
+| S1 | `protocols/soak_mode3_stress.yaml` | **8 MB sine (2000 × 4 KB frames, GS16) alternating with the 813 KB bar**, Mode 3, simulator at **286 Hz** with 90° jumps, gain 18 on the sine (one revolution sweeps the whole file; a jump = 2 MB seek) | longest FAT chain (16 sectors), widest seeks, highest read rate, the bar keeps continuity with the file that stalled | overnight (≥ 6 h ≈ 17 iterations ≈ 6 M commands ≈ 100× the old stall period) |
+| S2 | same, simulator at **200 Hz** | the course/lab rate on the same files | separates "286 Hz saturates the 300 Hz refresh" (expected: some `req_age` > 5 ms, no SD stall) from SD effects | one evening (≥ 3 h) |
+| C1 | `protocols/soak_mode2_open_loop.yaml` | Mode 2, controller-timed **200 fps**, same two files, no host stepping | the sequential-read control: no seeks at all. H-FAT ⇒ clean at any size; a per-read counter (H-count) ⇒ stalls recur at the same read spacing | 1 h (≈ 3 iterations) |
+
+Dropped from the earlier grid (implied by S1/S2 under H-FAT, or low information): 100 Hz Mode 3 (slower than S2),
+looming/GS2 cells (a smaller read is not a harder case; the GS2 bar generated by `make-stress-patterns.js` stays
+available as a 1 KB-read probe if S1 shows a size dependence), sequential Mode-3 sweeps (C1 covers sequential reads).
+
+**Predictions.** H-FAT / fast path: **zero `sd_slow` in S1, S2, C1**; per-read 0.62 ms sequential, 1.2–1.5 ms random,
+for the 8 MB file too; `req_age_us` max < 5 ms at 200 Hz, some frames 5–10 ms at 286 Hz (refresh-tick coalescing —
+a controller-throughput finding, not an SD one); Mode 2 `superseded` ≈ 0. **Fail signatures:** any `sd_slow` in the
+8 MB cells with phase `body` (a data-region disturb that scales with file span — would re-open the card question);
+`sd_layout` bit0 = 0 for either file (fragmented upload — re-upload before drawing conclusions); `unknown` trials
+(drain coverage at 286 Hz — raise the drain budget, not the verdict).
+
+**Prerequisites (all in the repo now):** the two patterns from `pixi run node scripts/make-stress-patterns.js`
+(`soak-patterns/sine_2000f_gs16.pat` 8.1 MB, `bar_200f_gs2.pat` 213 KB; upload through the Studio Console so each
+is written in one pass), the Studio soak driver's open-loop mode (v0.77, protocols without a FicTrac plugin skip the
+simulator-frames gate), the Studio's frame-count resolution from the uploaded bytes (no `__framesRepatch` needed when
+the upload happens in the same Studio session; otherwise #201's 0x88 frame count). Order: S1 overnight first — if it
+is clean, S2 and C1 are confirmation; if it is not, the `sd_slow` phase byte and the file it lands on decide what
+comes next.
diff --git a/protocols/soak_mode2_open_loop.yaml b/protocols/soak_mode2_open_loop.yaml
new file mode 100644
index 00000000..55b8de97
--- /dev/null
+++ b/protocols/soak_mode2_open_loop.yaml
@@ -0,0 +1,94 @@
+version: 3
+
+# ============================================================================
+# Mode-2 OPEN-LOOP soak — the sequential-read CONTROL for the SD-card stall
+# campaign (docs/development/sd-stall-causal-test-plan-2026-09-13.md §7). The
+# controller steps the pattern itself at frame_rate fps (no host 0x70s, no
+# seeks: every read is the next frame), on the same two files as the stress
+# soak. If stalls are seek-/FAT-induced this runs clean at any size; if they
+# are per-read count maintenance they recur here at the same read spacing.
+# One iteration ≈ 21 min. No FicTrac plugin: the soak driver skips the
+# simulator-frames check for protocols without one (Studio v0.77).
+#
+# Bench recipe:
+#   pixi run bridge -- --log-dir soak-logs        # still the run logger
+#   Studio ?advanced=1&soak=1 → open this protocol → File ▾ → Soak…
+# ============================================================================
+
+experiment_info:
+  name: "Mode-2 open-loop soak (SD sequential control)"
+  author: "webDisplayTools"
+
+rig: "./configs/rigs/cshl_g6_2x10_ball.yaml"
+
+variables:
+  ol_dur: &ol_dur 60
+  iti_dur: &iti_dur 2
+  fps: &fps 200
+
+experiment:
+  - "soak_setup"
+  - block: "open_loop_block"
+    trials:
+      - "ol_sine_2000f"
+      - "ol_bar_200f"
+    repetitions: 10
+    randomize: false
+    intertrial: "soak_iti"
+  - "soak_shutdown"
+
+conditions:
+  - name: "soak_setup"
+    commands:
+      - type: "plugin"
+        plugin_name: "log"
+        command_name: "log"
+        params:
+          message: "SD open-loop control soak iteration starting (Mode-2, 200 fps)"
+          level: "INFO"
+
+  - name: "ol_sine_2000f"
+    commands:
+      - type: "controller"
+        command_name: "trialParams"
+        pattern: "sine_2000f_gs16"
+        pattern_ID: 0
+        duration: *ol_dur
+        mode: 2
+        frame_index: 0
+        frame_rate: *fps
+        gain: 0
+      - type: "wait"
+        duration: *ol_dur
+
+  - name: "ol_bar_200f"
+    commands:
+      - type: "controller"
+        command_name: "trialParams"
+        pattern: "frame2_h_ccw_200f"
+        pattern_ID: 4
+        duration: *ol_dur
+        mode: 2
+        frame_index: 0
+        frame_rate: *fps
+        gain: 0
+      - type: "wait"
+        duration: *ol_dur
+
+  - name: "soak_iti"
+    commands:
+      - type: "controller"
+        command_name: "allOff"
+      - type: "wait"
+        duration: *iti_dur
+
+  - name: "soak_shutdown"
+    commands:
+      - type: "controller"
+        command_name: "stopDisplay"
+      - type: "plugin"
+        plugin_name: "log"
+        command_name: "log"
+        params:
+          message: "SD open-loop control soak iteration finished"
+          level: "INFO"
diff --git a/protocols/soak_mode3_stress.yaml b/protocols/soak_mode3_stress.yaml
new file mode 100644
index 00000000..82d17708
--- /dev/null
+++ b/protocols/soak_mode3_stress.yaml
@@ -0,0 +1,137 @@
+version: 3
+
+# ============================================================================
+# Mode-3 STRESS soak — the SD-card stall campaign's worst case on purpose
+# (docs/development/sd-stall-causal-test-plan-2026-09-13.md §7): the LARGEST
+# pattern we can make (sine_2000f_gs16, ≈ 8 MB, 2000 × 4 KB frames) alternating
+# with the 813 KB bar that produced every stall on the bench card, driven by the
+# FicTrac SIMULATOR at the HIGHEST command rate (286 Hz) with 90° jumps. One
+# iteration ≈ 21 min (twenty 60 s trials + 2 s ITIs); the soak driver repeats it
+# for hours. Verdicts: per-trial `trial_quality` (pass / flagged / unknown) and
+# `scripts/telemetry-report.py`.
+#
+# Gains: the bridge maps heading → frame index modulo the trial's frame count.
+#   18  = 2000 / 360 → one revolution sweeps the WHOLE 8 MB file (a 90° jump =
+#         500 frames = 2 MB seek); 1.8 = 200 / 360 for the bar (as in the
+#         standard soak). Both files must be contiguous on the card (sd_layout
+#         bit0 = 1); make them with scripts/make-stress-patterns.js and upload
+#         through the Studio Console.
+#
+# Bench recipe:
+#   pixi run sim -- --count 0 --rate 286 --seed 1 --jump-every 100 --jump-deg 90
+#   pixi run bridge -- --log-dir soak-logs
+#   Studio ?advanced=1&soak=1 → open this protocol → File ▾ → Soak…
+#   after: pixi run python scripts/telemetry-report.py soak-logs/arena-log-*.jsonl
+# ============================================================================
+
+experiment_info:
+  name: "Mode-3 STRESS soak (SD stalls, 8 MB + 286 Hz)"
+  author: "webDisplayTools"
+
+rig: "./configs/rigs/cshl_g6_2x10_ball.yaml"
+
+plugins:
+  - name: "fictrac"
+    type: "class"
+    matlab:
+      class: "FicTracPlugin"
+    config:
+      bridge_url: "ws://localhost:8765"
+      fictrac_port: 60000
+      proto: "udp"
+      gain: 18
+      offset: 0
+
+variables:
+  cl_dur: &cl_dur 60
+  iti_dur: &iti_dur 2
+
+experiment:
+  - "soak_setup"
+  - block: "stress_block"
+    trials:
+      - "cl_sine_2000f"
+      - "cl_bar_200f"
+    repetitions: 10
+    randomize: false
+    intertrial: "soak_iti"
+  - "soak_shutdown"
+
+conditions:
+  - name: "soak_setup"
+    commands:
+      - type: "plugin"
+        plugin_name: "fictrac"
+        command_name: "connect"
+      - type: "plugin"
+        plugin_name: "log"
+        command_name: "log"
+        params:
+          message: "SD stress soak iteration starting (Mode-3, sim-driven, 8 MB sine + 813 KB bar)"
+          level: "INFO"
+
+  # 8 MB, 2000 frames, GS16 (4 KB frames): the longest FAT chain / widest seeks we can produce.
+  # pattern_ID is a fallback only — the Studio resolves the name against the card's listing.
+  - name: "cl_sine_2000f"
+    commands:
+      - type: "controller"
+        command_name: "trialParams"
+        pattern: "sine_2000f_gs16"
+        pattern_ID: 0
+        duration: *cl_dur
+        mode: 3
+        frame_index: 0
+        frame_rate: 0
+        gain: 0
+      - type: "plugin"
+        plugin_name: "fictrac"
+        command_name: "startClosedLoop"
+        params:
+          gain: 18
+      - type: "wait"
+        duration: *cl_dur
+      - type: "plugin"
+        plugin_name: "fictrac"
+        command_name: "stopClosedLoop"
+
+  # The file every bench stall happened on (813 KB, 200 frames) — continuity with the evidence.
+  - name: "cl_bar_200f"
+    commands:
+      - type: "controller"
+        command_name: "trialParams"
+        pattern: "frame2_h_ccw_200f"
+        pattern_ID: 4
+        duration: *cl_dur
+        mode: 3
+        frame_index: 0
+        frame_rate: 0
+        gain: 0
+      - type: "plugin"
+        plugin_name: "fictrac"
+        command_name: "startClosedLoop"
+        params:
+          gain: 1.8
+      - type: "wait"
+        duration: *cl_dur
+      - type: "plugin"
+        plugin_name: "fictrac"
+        command_name: "stopClosedLoop"
+
+  - name: "soak_iti"
+    commands:
+      - type: "controller"
+        command_name: "allOff"
+      - type: "wait"
+        duration: *iti_dur
+
+  # No fictrac.disconnect (the bridge is the run's logger; see soak_mode3_closed_loop.yaml).
+  - name: "soak_shutdown"
+    commands:
+      - type: "controller"
+        command_name: "stopDisplay"
+      - type: "plugin"
+        plugin_name: "log"
+        command_name: "log"
+        params:
+          message: "SD stress soak iteration finished"
+          level: "INFO"
diff --git a/scripts/make-stress-patterns.js b/scripts/make-stress-patterns.js
new file mode 100644
index 00000000..10ff5679
--- /dev/null
+++ b/scripts/make-stress-patterns.js
@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/**
+ * make-stress-patterns.js — generate the LARGE G6 2×10 patterns the SD-stall soak campaign needs
+ * (docs/development/sd-stall-causal-test-plan-2026-09-13.md §7). Pure Node (pixi run node), uses
+ * js/pat-encoder.js, verifies each file by re-parsing it with js/pat-parser.js.
+ *
+ *   pixi run node scripts/make-stress-patterns.js [--out DIR] [--frames N] [--only sine|bar]
+ *
+ * Writes (default DIR = ./soak-patterns, git-ignored):
+ *   sine_<N>f_gs16.pat   N frames (default 2000 → ≈ 8 MB), GS16, 40-px sine grating rolling +1 px/frame
+ *                        (a 200-px roll period: 2000 frames = 10 full turns; every frame is a distinct read).
+ *   bar_<N>f_gs2.pat     N frames (default 200 → ≈ 213 KB), GS2, one 8-px bright bar rolling +1 px/frame
+ *                        (1 KB frames: the small-read control; only made when N ≤ 200 or --only bar).
+ *
+ * Upload through the Studio Console (SD upload) so the file is written in one pass (contiguous — the
+ * firmware's sd_layout record must say bit0 = 1 for the trial to be comparable). The Studio registers the
+ * uploaded bytes for the preview, which is where the closed-loop resolver reads the frame count.
+ */
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const PatEncoder = require('../js/pat-encoder.js');
+const PatParserMod = require('../js/pat-parser.js');
+const PatParser = PatParserMod.default || PatParserMod; // ES default export under Node's require(esm)
+
+const args = process.argv.slice(2);
+const opt = (name, dflt) => {
+    const i = args.indexOf(name);
+    return i >= 0 && i + 1 < args.length ? args[i + 1] : dflt;
+};
+const outDir = opt('--out', './soak-patterns');
+const frames = parseInt(opt('--frames', ''), 10);
+const only = opt('--only', '');
+
+const ARENA = { rowCount: 2, colCount: 10, pixelRows: 40, pixelCols: 200, arena_id: 1 }; // G6_2x10 (registry id 1)
+
+function makePattern({ name, numFrames, gs, pixelFn }) {
+    const { pixelRows, pixelCols } = ARENA;
+    const out = [];
+    for (let f = 0; f < numFrames; f++) {
+        const frame = new Uint8Array(pixelRows * pixelCols);
+        for (let r = 0; r < pixelRows; r++)
+            for (let c = 0; c < pixelCols; c++) frame[r * pixelCols + c] = pixelFn(f, r, c);
+        out.push(frame);
+    }
+    const patternData = {
+        generation: 'G6',
+        gs_val: gs,
+        numFrames,
+        rowCount: ARENA.rowCount,
+        colCount: ARENA.colCount,
+        pixelRows,
+        pixelCols,
+        frames: out,
+        stretchValues: [],
+        arena_id: ARENA.arena_id,
+        observer_id: 0
+    };
+    const buf = Buffer.from(PatEncoder.encode(patternData));
+    const parsed = PatParser.parsePatFile(
+        buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength)
+    );
+    if (parsed.numFrames !== numFrames || parsed.generation !== 'G6')
+        throw new Error(
+            `${name}: re-parse mismatch (${parsed.numFrames} frames, ${parsed.generation})`
+        );
+    const file = path.join(outDir, `${name}.pat`);
+    fs.writeFileSync(file, buf);
+    const perFrame = (buf.length - 18) / numFrames;
+    console.log(
+        `${file}: ${numFrames} frames, GS${gs}, ${(buf.length / 1024).toFixed(0)} KB (${perFrame.toFixed(0)} B/frame), re-parse OK`
+    );
+    return file;
+}
+
+fs.mkdirSync(outDir, { recursive: true });
+const wl = 40; // px
+if (!only || only === 'sine') {
+    const n = Number.isFinite(frames) && frames > 0 ? frames : 2000;
+    makePattern({
+        name: `sine_${n}f_gs16`,
+        numFrames: n,
+        gs: 16,
+        pixelFn: (f, r, c) => Math.round(7.5 + 7.5 * Math.sin((2 * Math.PI * (c + f)) / wl))
+    });
+}
+if (!only || only === 'bar') {
+    const n = Number.isFinite(frames) && frames > 0 ? Math.min(frames, 200) : 200;
+    makePattern({
+        name: `bar_${n}f_gs2`,
+        numFrames: n,
+        gs: 2,
+        pixelFn: (f, r, c) => ((((c - f) % 200) + 200) % 200 < 8 ? 1 : 0)
+    });
+}

From c961c8a7bf82bf5646b11fc80b9e8b0ace0426bd Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 13:53:04 -0400
Subject: [PATCH 19/67] docs: overnight soak hand-off run sheet (consolidated
 build, three runs, pass criteria, merge order); 2 h stress + overnight
 consolidated run in the plan; bench log

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/development/mode3-wedge-soak-plan.md     | 10 ++++
 .../sd-stall-causal-test-plan-2026-09-13.md   |  8 ++--
 docs/development/soak-handoff-2026-09-14.md   | 46 +++++++++++++++++++
 3 files changed, 60 insertions(+), 4 deletions(-)
 create mode 100644 docs/development/soak-handoff-2026-09-14.md

diff --git a/docs/development/mode3-wedge-soak-plan.md b/docs/development/mode3-wedge-soak-plan.md
index a6b313e6..251e9500 100644
--- a/docs/development/mode3-wedge-soak-plan.md
+++ b/docs/development/mode3-wedge-soak-plan.md
@@ -442,6 +442,16 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   `bar_200f_gs2`, verified by re-parse), Studio soak driver accepts open-loop protocols (v0.77, 13:58 ET). Michael's
   design question answered in plan §5: cache the cluster chain per pattern open (extent table) → no contiguity
   precondition; to implement after the causal test.
+- **2026-09-13 14:30–14:55 ET — hand-off shape (Michael: 2 h stress, not overnight; then ONE consolidated build
+  soaked overnight, clean and mergeable for the lab tomorrow).** Finding: the consolidated build already exists —
+  firmware `feat/sd-fastpath-2x10` `75405ee` is a linear stack of health → ring → watchdog → free-running timer (fw #50
+  fix) → SD fast path on top of `arena-2x10-local` (fast-forward, 31 commits; conflicts with `main` only because #48
+  moved main to per-board `-DARENA_HW_*` headers — the main port is a later PR, superseding #53). Web: PR #202 opened
+  (`claude/mode3-perf-sd` → `claude/mode3-wedge-soak`, stacked on #198; both merge cleanly onto main, #198 CI green,
+  `pixi run test` green). One-page run sheet `docs/development/soak-handoff-2026-09-14.md` (flash, serve, card,
+  three runs, pass criteria, merge order). Firmware branch still LOCAL — push + PR against `arena-2x10-local`
+  awaits Michael's go. RAM-cached FAT chain (extent table): deferred — decide on the 70-min causal result
+  (§5 of the causal plan).
 
 ## 11. T4 as built (2026-09-12) — soak with ring-buffer logging
 
diff --git a/docs/development/sd-stall-causal-test-plan-2026-09-13.md b/docs/development/sd-stall-causal-test-plan-2026-09-13.md
index 84aaa265..0acb5365 100644
--- a/docs/development/sd-stall-causal-test-plan-2026-09-13.md
+++ b/docs/development/sd-stall-causal-test-plan-2026-09-13.md
@@ -130,9 +130,9 @@ soaks plus one short control, all judged by the per-trial `trial_quality` verdic
 
 | # | protocol (repo) | what | why it is the stress | duration |
 |---|---|---|---|---|
-| S1 | `protocols/soak_mode3_stress.yaml` | **8 MB sine (2000 × 4 KB frames, GS16) alternating with the 813 KB bar**, Mode 3, simulator at **286 Hz** with 90° jumps, gain 18 on the sine (one revolution sweeps the whole file; a jump = 2 MB seek) | longest FAT chain (16 sectors), widest seeks, highest read rate, the bar keeps continuity with the file that stalled | overnight (≥ 6 h ≈ 17 iterations ≈ 6 M commands ≈ 100× the old stall period) |
-| S2 | same, simulator at **200 Hz** | the course/lab rate on the same files | separates "286 Hz saturates the 300 Hz refresh" (expected: some `req_age` > 5 ms, no SD stall) from SD effects | one evening (≥ 3 h) |
-| C1 | `protocols/soak_mode2_open_loop.yaml` | Mode 2, controller-timed **200 fps**, same two files, no host stepping | the sequential-read control: no seeks at all. H-FAT ⇒ clean at any size; a per-read counter (H-count) ⇒ stalls recur at the same read spacing | 1 h (≈ 3 iterations) |
+| S1 | `protocols/soak_mode3_stress.yaml` | **8 MB sine (2000 × 4 KB frames, GS16) alternating with the 813 KB bar**, Mode 3, simulator at **286 Hz** with 90° jumps, gain 18 on the sine (one revolution sweeps the whole file; a jump = 2 MB seek) | longest FAT chain (16 sectors), widest seeks, highest read rate, the bar keeps continuity with the file that stalled | **2 h** (Michael 14:30: overnight is overkill here — ≈ 6 iterations ≈ 2 M commands ≈ 30× the old stall period) |
+| S2 | same protocol, simulator at **200 Hz** — **the overnight run on the consolidated build** (`docs/development/soak-handoff-2026-09-14.md`) | the course/lab rate on the same files, with the fault detector, post-mortem and watchdog all armed: one run exercises the telemetry ring, the free-running refresh timer (ISR guard), the watchdog and the SD fast path together | separates "286 Hz saturates the 300 Hz refresh" (expected: some `req_age` > 5 ms, no SD stall) from SD effects; the hand-off evidence for the lab | overnight |
+| C1 | `protocols/soak_mode2_open_loop.yaml` | Mode 2, controller-timed **200 fps**, same two files, no host stepping | the sequential-read control: no seeks at all. H-FAT ⇒ clean at any size; a per-read counter (H-count) ⇒ stalls recur at the same read spacing | 1 h (≈ 3 iterations), when convenient |
 
 Dropped from the earlier grid (implied by S1/S2 under H-FAT, or low information): 100 Hz Mode 3 (slower than S2),
 looming/GS2 cells (a smaller read is not a harder case; the GS2 bar generated by `make-stress-patterns.js` stays
@@ -151,4 +151,4 @@ is written in one pass), the Studio soak driver's open-loop mode (v0.77, protoco
 simulator-frames gate), the Studio's frame-count resolution from the uploaded bytes (no `__framesRepatch` needed when
 the upload happens in the same Studio session; otherwise #201's 0x88 frame count). Order: S1 overnight first — if it
 is clean, S2 and C1 are confirmation; if it is not, the `sd_slow` phase byte and the file it lands on decide what
-comes next.
+comes next. **Sequence for the next bench session:** causal arms (70 min) → S1 (2 h) → S2 overnight on the same build.
diff --git a/docs/development/soak-handoff-2026-09-14.md b/docs/development/soak-handoff-2026-09-14.md
new file mode 100644
index 00000000..4be0d810
--- /dev/null
+++ b/docs/development/soak-handoff-2026-09-14.md
@@ -0,0 +1,46 @@
+# Overnight soak hand-off — consolidated Mode-3 build (2026-09-14)
+
+One page. Everything built since Friday 2026-09-11 is under test at once: controller health (0xCA/0xCB), the
+telemetry ring, the hardware watchdog, the free-running refresh timer (the fw #50 "ISR guard"), and the SD fast
+path. If the overnight run is clean, these are the branches to merge.
+
+## What to flash / serve
+
+| piece | where | identity |
+|---|---|---|
+| firmware | `reiserlab/LED-Display_G6_Firmware_Arena` branch `feat/sd-fastpath-2x10`, commit **`75405ee`** (2×10 bench branch; fast-forwards `arena-2x10-local`) | `pio run -e teensy41-performance` → `.pio/build/teensy41-performance/firmware.hex`, sha256 starts `5d912915dd0982d9`; Studio shows the label `75405ee 2x10 … freerun sdfast` |
+| Studio | `reiserlab/webDisplayTools` PR #198 (v0.76) + PR #202 (v0.77, branch `claude/mode3-perf-sd`) | serve the branch locally: `python3 -m http.server 8092` in the checkout, open `http://localhost:8092/arena_studio.html?advanced=1&soak=1` |
+| bridge + simulator | same checkout | `pixi run bridge -- --log-dir soak-logs` · `pixi run sim -- --count 0 --rate 200 --seed 1 --jump-every 100 --jump-deg 90` |
+
+Flash only with the Studio disconnected (port free): `scripts/flash_bootloader_route.sh` in the firmware repo.
+After connecting, the Studio's firmware label must end in `freerun sdfast`; **never power-cycle the controller
+after a fault before the post-mortem has finished** (it drains the ring and the crash report — that is the evidence).
+
+## Card contents (once)
+
+Upload `soak-patterns/sine_2000f_gs16.pat` (8.1 MB, from `pixi run node scripts/make-stress-patterns.js`) through
+the Studio Console in the same Studio session that will run the soak; `frame2_h_ccw_200f` (813 KB) must already be
+on the card. `pixi run python scripts/telemetry-report.py <log>` must show `layout: contiguous` for both files.
+
+## Runs, in order
+
+1. **Causal arms** (~70 min, Michael/Claude): `docs/development/sd-stall-causal-test-plan-2026-09-13.md` §3.
+2. **2 h stress**: simulator at `--rate 286`, protocol `protocols/soak_mode3_stress.yaml`, File ▾ → Soak… with
+   `hours: 2`, first fault `halt`, then `reset-continue`.
+3. **Overnight**: simulator at `--rate 200`, same protocol, `hours: 10`, same fault policy.
+
+## What "clean" means
+
+- `pixi run python scripts/wedge-scan.py soak-logs/` → **0 controller faults, 0 resets** (the watchdog never fired,
+  no `timer_fail`), every iteration `completed`.
+- `pixi run python scripts/telemetry-report.py soak-logs/arena-log-*.jsonl` → **0 SD reads > 10 ms**, every trial
+  `pass`; `req_age_us` max < 10 ms at 200 Hz (5 ms is the target; a few 5–10 ms frames at 286 Hz are expected and
+  are a refresh-coalescing finding, not an SD one). `unknown` trials mean telemetry coverage dropped — report it,
+  do not count it as a failure.
+- Anything else: keep the logs, note the ET time, post to firmware #54 (SD) or webDisplayTools #197 (wedge) with the
+  `telemetry-report.py` output. Do not post to firmware #50 or PJRC (Michael owns those threads).
+
+## After a clean night
+
+Merge order: web #198 → #202. Firmware: `feat/sd-fastpath-2x10` fast-forwards `arena-2x10-local` (the branch the
+CSHL controllers run); the port to `main` (per-board `-DARENA_HW_*` layout) is a separate PR that supersedes #53.

From d22b7203d7a2126404ee7cec753c07d898543352 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 15:12:27 -0400
Subject: [PATCH 20/67] =?UTF-8?q?docs:=20causal=20test=20result=20?=
 =?UTF-8?q?=E2=80=94=20H-FAT=20confirmed=20(4=20arms=20on=2075405ee:=20FAT?=
 =?UTF-8?q?=20access=20causes=20the=20stalls,=20same-index=20skip=20irrele?=
 =?UTF-8?q?vant);=20bench=20log=2014:46=E2=80=9315:12=20ET?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/development/mode3-wedge-soak-plan.md     | 35 +++++++++++++++++++
 docs/development/sd-read-jitter-2026-09-13.md |  6 ++++
 .../sd-stall-causal-test-plan-2026-09-13.md   | 15 ++++++--
 3 files changed, 54 insertions(+), 2 deletions(-)

diff --git a/docs/development/mode3-wedge-soak-plan.md b/docs/development/mode3-wedge-soak-plan.md
index 251e9500..6cb9e7e2 100644
--- a/docs/development/mode3-wedge-soak-plan.md
+++ b/docs/development/mode3-wedge-soak-plan.md
@@ -452,6 +452,41 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   three runs, pass criteria, merge order). Firmware branch still LOCAL — push + PR against `arena-2x10-local`
   awaits Michael's go. RAM-cached FAT chain (extent table): deferred — decide on the 70-min causal result
   (§5 of the causal plan).
+- **2026-09-13 14:46 ET — Michael at the bench (35–40 min).** Flashed `75405ee` (bootloader route, 6 s; label
+  `75405ee6 2x10 2026-09-13 feat/sd-fastpath-2x10 freerun sdfast`). Causal test shortened: bar-only, 6 min per arm,
+  driven by `scripts/sd_stall_test.py --sd-diag N` (first hardware use). **14:46:22 smoke, arm 3, 15 s:** 2,936
+  commands, reads/cmd 1.00 (skip off), `sd_layout` legacy+no-skip, contiguous = 0 → **one cluster after ~600 reads:
+  32.5 / 41.3 / 95.4 ms, all phase `body`, sd_slow_ctx 0/0** (card held the bus, no driver error). Phase body is
+  consistent with H-FAT (SdFat `fatGet` at cluster crossings inside `read`, verified in `FatFile.cpp`); the plan's
+  "phase = seek" fingerprint corrected. 14:47 arms started in order 3 → 2 → 1 → 0, 6 min each (logs
+  `soak-logs/sdstall-*-armN.jsonl` in the ring worktree).
+- **2026-09-13 15:04 ET — arms 3 and 2 done (each 6 min, 200 Hz, bar id 36 only, capture valid, no reboot, cmds
+  reconciled).** **Arm 3** (legacy seek, no skip): 71,882 commands = 71,882 reads → **2 clusters**, spacing **23,275
+  commands** (= the baseline 24.5k period): one of 16 stalls of 12–19 ms (a sub-20 ms signature never visible under the
+  old 20 ms threshold) at 309 s and one classic 21.6 / 41.4 / 48.2 / **90.8 ms** at 426 s; phases body (one seek);
+  bar −1 step 2.0 ms p50. **Arm 2** (contiguous seek, no skip): 71,992 commands = 71,992 reads — the SAME read count —
+  → **0 reads over 10 ms, 0 slow reads at all, worst read 1.8 ms, req_age max 3.0 ms**; bar −1 step 1.46 ms.
+  ⇒ **H-count and H-data rejected, H-FAT confirmed:** identical data-read exposure, the only difference is whether the
+  FAT is touched. The same-index skip (B) is not what removed the stalls. Arms 1 and 0 running (1 = legacy seek with
+  skip on → clusters expected, closes the "B did it" loophole from the other side; 0 = production on `75405ee`).
+- **2026-09-13 15:08 ET — arm 1 done** (legacy seek, skip ON): 71,959 commands, 54,885 reads (0.763 reads/cmd) →
+  **1 cluster of 6 stalls (21.4 / 19.5 / 22.9 / 48.0 / 19.1 / 70.2 ms)**, capture valid. Stalls persist with 24 % fewer
+  data reads and the FAT still touched ⇒ the same-index skip is irrelevant to the stalls (as arm 2 vs 3 already showed).
+  Arm 0 (production) running until ~15:12.
+- **2026-09-13 15:11 ET — arm 0 done, causal test COMPLETE (4 × 6 min, all captures valid, 0 reboots).**
+
+  | arm | FAT touched | reads/cmd | reads | stalls > 10 ms | clusters | worst read | req_age max |
+  |---|---|---|---|---|---|---|---|
+  | 3 legacy seek, no skip | yes | 1.00 | 71,882 | 20 | 2 (spacing 23,275 cmds) | 90.8 ms | 76.7 ms |
+  | 2 contiguous, no skip | no | 1.00 | 71,992 | **0** | 0 | 1.8 ms | 3.0 ms |
+  | 1 legacy seek, skip | yes | 0.76 | 54,885 | 6 | 1 | 70.2 ms | — |
+  | 0 production | no | 0.76 | 54,900 | **0** | 0 | 1.8 ms | 2.9 ms |
+
+  **Conclusion: H-FAT confirmed, H-count and H-data rejected.** The stalls were induced by the firmware's FAT access
+  (SdFat chain walk on backward seeks + `fatGet` at cluster crossings inside `read`) hammering the card's FAT block;
+  the contiguous-seek fix removes them at identical data-read exposure; the same-index skip is irrelevant to them.
+  Production build `75405ee`: bar −1 step 1.46 ms p50 / 1.8 ms max, req_age p50 1.7 ms / max 2.9 ms at 200 Hz.
+  15:12 started the 2 h production run at 286 Hz on the bar (`--label prod-286hz-2h`), unattended.
 
 ## 11. T4 as built (2026-09-12) — soak with ring-buffer logging
 
diff --git a/docs/development/sd-read-jitter-2026-09-13.md b/docs/development/sd-read-jitter-2026-09-13.md
index fafcbc15..2b735513 100644
--- a/docs/development/sd-read-jitter-2026-09-13.md
+++ b/docs/development/sd-read-jitter-2026-09-13.md
@@ -150,6 +150,12 @@ grouping; hot vs quiet window), (5) maintenance-capability probe and flash-regio
 
 ## 7. Bench results (filled in as they arrive)
 
+**Causal result (2026-09-13 15:11 ET, firmware `75405ee`, `SET_SD_DIAG` arms, 6 min each at 200 Hz on the bar):**
+legacy seek + no skip → 2 stall clusters (spacing 23,275 commands, worst 91 ms); contiguous seek + no skip → 0 slow
+reads at the same 72k reads; legacy seek + skip → 1 cluster; production → 0. **The FAT access was the cause** (the
+`fatGet` at cluster crossings inside `FatFile::read` puts the FAT read in the body phase, not the seek phase as §8
+assumed); the same-index skip does not affect the stalls. Details: `mode3-wedge-soak-plan.md` §10.
+
 Iteration 2 (12:27 ET) repeated iteration 1 to the decimal: 1281 s, 242k accepted 0x70s, 0 reads > 10 ms, 20/20 pass,
 req_age max 4.8 ms. **Two iterations, 482k commands, 2554 s, zero stalls** where the baseline rate predicts ≈ 6
 clusters (P(0) ≈ 0.003).
diff --git a/docs/development/sd-stall-causal-test-plan-2026-09-13.md b/docs/development/sd-stall-causal-test-plan-2026-09-13.md
index 0acb5365..ed2b45b8 100644
--- a/docs/development/sd-stall-causal-test-plan-2026-09-13.md
+++ b/docs/development/sd-stall-causal-test-plan-2026-09-13.md
@@ -1,5 +1,10 @@
 # Causal test plan — did the contiguous-seek fix remove the SD-card stalls? (bench, ~70 min)
 
+**RESULT 2026-09-13 15:11 ET — H-FAT CONFIRMED.** Four 6-minute bar-only arms on `75405ee` at 200 Hz (table in
+`mode3-wedge-soak-plan.md` §10): arm 3 = 2 clusters at the baseline spacing (worst 91 ms), arm 2 = 0 slow reads with
+the identical read count, arm 1 = 1 cluster with the skip on, arm 0 = 0. The FAT access was the cause; the skip is
+irrelevant to the stalls.
+
 **Written:** 2026-09-13 12:45 ET; updated 14:15 ET. **Status:** code ready and **reviewed** (firmware
 `feat/sd-fastpath-2x10` tip `75405ee`: `SET_SD_DIAG` 0xCE, Codex rounds 3 + 4 reconciled in the ring worktree's
 `.codex-review/report-20260913-fw-round4.md`; Studio v0.77 `Studio.setSdDiag`), **bench test pending**.
@@ -43,8 +48,14 @@ plain luck (P ≈ 0.003).
 | 2 — the control for B | 2 | **on** | off | **0 clusters** | clusters every ~24.5k | clusters every ~24.5k |
 | 0 — production | 0 | on | on | 0 | clusters every ~32k | clusters every ~32k |
 
-Arm 0 is already measured (0 in 2 iterations). The **phase byte** is the fingerprint: under H-FAT the stall lands
-inside the seek (FAT-sector read), under H-data inside the body read — visible in arm 3 with a single stall.
+Arm 0 is already measured (0 in 2 iterations). **Correction (bench 14:47 ET):** the phase byte is NOT the H-FAT
+fingerprint. For a non-contiguous file SdFat's `FatFile::read` calls `fatGet` at every cluster crossing (a 4 KB frame
+almost always straddles two 4 KB clusters), so the FAT-sector read happens inside the **body** phase; `seekSet` only
+walks the chain on backward seeks. The 15 s arm-3 smoke run on `75405ee` reproduced a cluster (32.5 / 41.3 / 95.4 ms,
+all phase `body`, `sd_slow_ctx` = no driver error) after ~600 reads. Under H-FAT arms 3 and 1 stall (phase body),
+**arm 2 is the decisive arm**: contiguous flag on, skip off → no FAT access at all → 0 clusters; H-count/H-data
+predict clusters at the baseline spacing. The arms were shortened to 6 min each (bar-only, ~70k reads ≈ 3 baseline
+periods) via `scripts/sd_stall_test.py --sd-diag N --minutes 6` (browser-free).
 
 **Exposure and stopping rule.** One soak iteration ≈ 1250 s ≈ 120k bar-pattern commands ≈ 4–5 baseline cycles.
 - Arm 3 (20 min): must reproduce ≥ 2 clusters — if it does not, the card's behaviour has changed since last night

From 031d13bffe10ac6fa1a0607ea8b3189cd9a586a1 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 15:29:28 -0400
Subject: [PATCH 21/67] docs: consolidation plan draft for the
 production-candidate hand-off (review gates, decisions, small changes,
 overnight run)

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../consolidation-plan-2026-09-13.md          | 53 +++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 docs/development/consolidation-plan-2026-09-13.md

diff --git a/docs/development/consolidation-plan-2026-09-13.md b/docs/development/consolidation-plan-2026-09-13.md
new file mode 100644
index 00000000..39a14005
--- /dev/null
+++ b/docs/development/consolidation-plan-2026-09-13.md
@@ -0,0 +1,53 @@
+# Consolidation plan — production candidate for the lab hand-off (draft 2026-09-13 15:40 ET, for Michael's review)
+
+Goal: by tomorrow morning, ONE firmware build and ONE Studio version that the lab can flash, run and review, with
+overnight benchmark data taken on exactly that build. Small changes only; every change re-reviewed; nothing rewritten.
+
+## 1. What the candidate is
+
+| piece | today | candidate |
+|---|---|---|
+| firmware | `feat/sd-fastpath-2x10` @ `75405ee` (31 commits on `arena-2x10-local`: health → ring → watchdog → free-running timer → SD fast path) | same branch + the small changes below, rebuilt, flashed for the overnight run |
+| Studio | PR #198 (v0.76) + PR #202 (v0.77) | same PRs + small changes below (v0.78 if any HTML edit) |
+| tools | `scripts/sd_stall_test.py`, `sd_upload_pat.py`, `sd_soak_campaign.sh` (firmware repo); `telemetry-report.py`, `wedge-scan.py`, `make-stress-patterns.js` (web) | committed, documented in the run sheet |
+
+## 2. Review gates before the overnight flash (this evening)
+
+1. Whole-stack Codex adversarial reviews, running now: firmware `arena-2x10-local..HEAD`, web `main..claude/mode3-perf-sd`.
+   Reconcile → fix only blocking/significant items → one more Codex diff review of the fix delta → rebuild.
+2. HIL on the rebuilt hex, port free: `pytest --transport=serial --port … tests/test_firmware_version.py
+   tests/test_health.py tests/test_telemetry.py tests/test_lab79_sd.py --pat soak-patterns/bar_200f_gs2.pat`.
+3. `pixi run test` + `format-check` (web). Studio smoke on the bench origin: connect, label `freerun sdfast`, one 60 s
+   Mode-3 trial with the trial-quality banner (the v0.77 verdict path has not yet seen a real trial).
+
+## 3. Decisions for Michael
+
+- **Keep `SET_SD_DIAG` 0xCE in production?** Recommend **keep** (gated on flag bit 6, off at boot, restored by the
+  harness) but add a Studio banner when the readback is non-zero at connect (S-1 below). Alternative: compile it out
+  (`fw_sd_diag = false`) for the release build — loses the lab's ability to reproduce the stall on demand.
+- **Merge target for firmware:** PR against `arena-2x10-local` now (fast-forward, what the CSHL controllers run);
+  port to `main` (per-board `-DARENA_HW_*` after #48) as a follow-up PR that supersedes #53. Needs your go to push.
+- **Web:** merge #198 then #202 as they are (stack), or squash into one PR? Recommend as they are — the commit history
+  is the review trail; release notes v0.76/v0.77 are the reading guide.
+
+## 4. Small changes proposed (only these unless the reviews find more)
+
+| id | repo | change | why |
+|---|---|---|---|
+| F-1 | fw | `SET_SD_DIAG` bit0 refused (status 1) when the volume is exFAT | the arm is a silent no-op there (Codex rounds 3/4) |
+| F-2 | fw | README: causal result + "production = flags 0"; `scripts/` section lists the three bench tools | hand-off |
+| S-1 | web | Studio: banner "SD diagnostic switches are ON (arm N)" when `GET_SD_INFO` byte 29 ≠ 0 at connect / run start | a stray arm would silently degrade every trial |
+| S-2 | web | run sheet: browser-free campaign path (upload + `sd_soak_campaign.sh`) as the default overnight tool; Studio path as the alternative | it is what ran tonight |
+| S-3 | web | CLAUDE.md: one line on `sd_soak_campaign` / `sd_upload_pat` and on "stalls were FAT access — never re-introduce chain-walking seeks" | institutional memory |
+
+## 5. Overnight run (on the candidate)
+
+`scripts/sd_soak_campaign.sh PORT "<sine idx> 36" 200 <until 08:00>` — 10-min alternating segments of the 8 MB sine and
+the 813 KB bar at 200 Hz, Mode 3 random walk + 90° jumps, from ~21:00 to 08:00 (~66 segments, ~8 M commands). Morning:
+`telemetry-report.py soak-logs/sdstall-*-camp-200-*.jsonl` + `campaign-*.log`. Pass = 0 reads > 10 ms, 0 reboots,
+req_age max < 10 ms; per-file read cost tables are the benchmark numbers for the hand-off.
+
+## 6. Documentation to update before hand-off
+
+firmware README (F-2), web release notes (S-1), `soak-handoff-2026-09-14.md` (S-2, morning results), CLAUDE.md (S-3),
+`sd-read-jitter-2026-09-13.md` §7 result (done), fw #54 / web #201 closing comments, memory.

From 2e7b54d673e1b5a0e8218d19ff26e295f042e1cc Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 15:32:12 -0400
Subject: [PATCH 22/67] =?UTF-8?q?docs:=20the=20one=20hand-off=20document?=
 =?UTF-8?q?=20=E2=80=94=20Mode-3=20reliability,=20firmware=20+=20Studio=20?=
 =?UTF-8?q?changes=202026-09-11=20=E2=86=92=2009-14=20(problems,=20diagnos?=
 =?UTF-8?q?is=20path,=20layers,=20invariants,=20tests,=20evidence,=20open?=
 =?UTF-8?q?=20items);=20consolidation=20plan:=20Michael's=20three=20review?=
 =?UTF-8?q?=20criteria?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../consolidation-plan-2026-09-13.md          |  10 ++
 .../mode3-reliability-handoff-2026-09-14.md   | 170 ++++++++++++++++++
 2 files changed, 180 insertions(+)
 create mode 100644 docs/development/mode3-reliability-handoff-2026-09-14.md

diff --git a/docs/development/consolidation-plan-2026-09-13.md b/docs/development/consolidation-plan-2026-09-13.md
index 39a14005..df054b77 100644
--- a/docs/development/consolidation-plan-2026-09-13.md
+++ b/docs/development/consolidation-plan-2026-09-13.md
@@ -13,6 +13,13 @@ overnight benchmark data taken on exactly that build. Small changes only; every
 
 ## 2. Review gates before the overnight flash (this evening)
 
+**Michael's three criteria (15:35 ET), applied to every diff and to the reconciliation of the Codex passes:**
+(a) **minimal complexity** — the simplest diff that does the job; overlapping instrumentation or dead paths get
+removed, not documented around; (b) **good comments** — every non-obvious line says *why*, in the code, not in a
+review report; (c) **one detailed hand-off document** explaining all the changes since 2026-09-11 together
+(`docs/development/mode3-reliability-handoff-2026-09-14.md`, both repos, one narrative), not a trail across builds.
+
+
 1. Whole-stack Codex adversarial reviews, running now: firmware `arena-2x10-local..HEAD`, web `main..claude/mode3-perf-sd`.
    Reconcile → fix only blocking/significant items → one more Codex diff review of the fix delta → rebuild.
 2. HIL on the rebuilt hex, port free: `pytest --transport=serial --port … tests/test_firmware_version.py
@@ -49,5 +56,8 @@ req_age max < 10 ms; per-file read cost tables are the benchmark numbers for the
 
 ## 6. Documentation to update before hand-off
 
+**The one hand-off document** (`mode3-reliability-handoff-2026-09-14.md`): the problem (wedge + stalls), the diagnosis
+path and evidence, every firmware change by layer with its wire contract and flag bit, every Studio change, how to
+test (HIL, offline, bench), the overnight benchmark, known limits, and where each thing lives. Then the smaller ones:
 firmware README (F-2), web release notes (S-1), `soak-handoff-2026-09-14.md` (S-2, morning results), CLAUDE.md (S-3),
 `sd-read-jitter-2026-09-13.md` §7 result (done), fw #54 / web #201 closing comments, memory.
diff --git a/docs/development/mode3-reliability-handoff-2026-09-14.md b/docs/development/mode3-reliability-handoff-2026-09-14.md
new file mode 100644
index 00000000..1029e079
--- /dev/null
+++ b/docs/development/mode3-reliability-handoff-2026-09-14.md
@@ -0,0 +1,170 @@
+# Mode-3 reliability — the one hand-off document (firmware + Studio, 2026-09-11 → 09-14)
+
+**Read this first.** Two problems made closed-loop (Mode-3) trials on the G6 arena unreliable. Both are now explained
+and fixed on one firmware build and one Studio version, with instrumentation that shows, per trial, whether the display
+did what the host asked. This document explains every change since Friday 2026-09-11 in one place: what, why, the wire
+contract, how to test it, the evidence, and what is still open. Byte-level tables live in the firmware README (section
+numbers given); this is the narrative and the map.
+
+| | problem | cause | fix | evidence |
+|---|---|---|---|---|
+| A | **controller wedge**: ~1 in 10 Mode-3 runs the controller went 100–500 ms per command, power cycle only (fw #50) | a race in `IntervalTimer::end()`: SET_FRAME_POSITION disarmed/re-armed the refresh timer per command; a PIT interrupt landing between the two left the PIT firing with a null callback (an ISR storm) | **free-running refresh timer** — 0x70 never touches the PIT; plus an atomic `end()`; plus a hardware watchdog that resets and records the PC if anything like it ever recurs | 24 soak iterations, 5.15 M commands, 0 wedges (was 1 in 10 runs) |
+| B | **display freezes of 30–90 ms** every ~24.5k frame reads of a large pattern (fw #54) | firmware FAT access: SdFat re-walked the file's cluster chain on backward seeks and looked up the next cluster inside every read that crossed a 4 KB cluster boundary; those FAT-sector reads hammered one physical block of the card until its read-disturb maintenance paused the card | **contiguous O(1) seeks** (`FsFile` + `contiguousRange()`): the FAT is read once at pattern open and never during a trial | 4-arm causal test 2026-09-13: FAT touched → stalls at the old spacing; FAT untouched, same read count → 0; production: 0 in 482k + 72k commands + 1 h at 286 Hz |
+
+**Candidate build:** firmware `feat/sd-fastpath-2x10` @ `75405ee` (label `… freerun sdfast`, 0xCB flags `0x7C`);
+Studio v0.77 (PRs #198 + #202). **Run sheet for the bench:** `soak-handoff-2026-09-14.md`.
+
+---
+
+## 1. How we got here (so the layers make sense)
+
+1. **Fri 09-11 — see the wedge.** `GET_HEALTH` 0xCA (counters, loop timing, a reset-surviving *breadcrumb* of the last
+   operation) and `GET_FIRMWARE_VERSION` 0xCB (build identity in every run log). Studio v0.76: the fault detector, the
+   post-mortem probe sequence, the soak driver, `wedge-scan.py`. Result: the wedge reproduced, the breadcrumb pointed at
+   the 0x70 handler but could not say what led up to it.
+2. **Sat 09-12 — record the lead-up.** The **telemetry ring** (0xA8/0xA9): every command, every displayed frame change,
+   every state change, in a 64 KiB RAM ring that survives a soft reset and is drained live over USB with an ack cursor.
+   Then the **watchdog** (RTWDOG) with pre-reset PC capture and `GET_CRASHREPORT` 0xCC, because a wedged controller
+   that resets itself in 2 s is better than one that needs a power cycle, and the captured PC is evidence. The ring +
+   ISR breadcrumbs showed the wedge was the PIT: `IntervalTimer::end()` racing its own interrupt. Fix: **free-running
+   refresh timer** (0x70 no longer disarms/re-arms it; the frame buffer is swapped under the running timer) and an
+   atomic `end()`. A stand-alone reproducer (`tools/pit-race-repro`) demonstrates the storm on a bare Teensy.
+3. **Sat night → Sun 09-13 — the stalls.** With the wedge gone, the ring's `sd_slow` records exposed problem B: 716 slow
+   reads in 197 clusters over 9.9 M commands, count-triggered, only on the 813 KB pattern. The **SD fast path** build
+   added attribution (which phase of the read stalled, driver error bits, per-pattern layout, read counts), the O(1)
+   seek, a same-index read skip, `GET_SD_INFO` 0xCD (card identity) and, for the causal test, `SET_SD_DIAG` 0xCE
+   (bench switches). Studio v0.77 added per-trial **pass / flagged / unknown** verdicts and the card identity in the
+   run metadata. The causal test on Sunday afternoon settled the cause (§6).
+
+## 2. Firmware changes, by layer (all on `arena-2x10-local`, 31 commits, fast-forward)
+
+| layer | commits | opcodes / records | 0xCB flag | README § | HIL tests |
+|---|---|---|---|---|---|
+| Health + build identity | `06a6f25`, `506339a`, `22b756d` | `GET_HEALTH` 0xCA (ver 5, 89 B), `GET_FIRMWARE_VERSION` 0xCB (46 B) | capability bit 7 `health` gates both | Health + breadcrumb; Build identity | `test_health.py`, `test_firmware_version.py` |
+| Telemetry ring | `280ecc2`..`64167f8` | `SET_TELEMETRY` 0xA8, `GET_TELEMETRY_BLOCK` 0xA9 (18 B header + records; CMD / FRAME / STATE) | bit 2 | Telemetry ring | `test_telemetry.py`, offline `test_telemetry_codec.py` |
+| Watchdog + crash report | `fb11681`..`4860fef` | RTWDOG (~2 s, calibrated), `GET_CRASHREPORT` 0xCC (128 B), HEALTH v2 fields (prev ISR, captured PC, wdog flags), 0x70 sub-op breadcrumbs 6–9 | bit 3 | Watchdog, sub-op / ISR breadcrumbs | `test_health.py` (v2 fields), `test_crashreport_*` |
+| Free-running refresh timer (fix A) | `eca07f6`, `394dee4` (+ `tools/pit-race-repro`, hygiene `8968fb7`) | none new; `STATE(timer_fail)` kind 10 if the timer cannot start | bit 4 | Free-running refresh timer | `test_health.py` timing checks |
+| SD fast path (fix B) + attribution | `200fada`..`75405ee` | `GET_SD_INFO` 0xCD (30 B), `SET_SD_DIAG` 0xCE, FRAME 26 B (ring v2), STATE kinds 11–14, `sd_slow` phase byte | bit 5 (0xCD, FRAME v2, kinds 11–13), bit 6 (0xCE, kind 14) | SD fast path; SD card identity; A/B switches | `test_firmware_version.py` (0xCD/0xCE), `test_telemetry.py`, offline `test_sd_stall_stats.py` |
+
+### 2.1 Design notes a maintainer needs
+
+- **Gating rule.** Every new opcode is gated on a `GET_FIRMWARE_VERSION` flag bit, never on the 0xC2 capability byte
+  (it is full) and never blind: this firmware answers an unknown opcode with `CE_UNKNOWN_CMD` and an error glyph on the
+  arena. Bits: 2 telemetry, 3 crash report, 4 free-run, 5 SD fast path, 6 SD diag. `GET_HEALTH`'s `ver` byte is the
+  health layout version and is not bumped for unrelated features.
+- **Ring at a fixed OCRAM address** (`0x2026F000`, 64 KiB, below PJRC's CrashReport, in no linker section) so it
+  survives SYSTEM_RESET and the bootloader reboot. Full ring = overwrite oldest (it is a crash recorder first).
+  Records are freed only when the host's next request acknowledges their sequence number. A heap collision disables
+  the ring and says so (`ring_overrun` code) rather than corrupting either. Ring `kVersion` 2 = 26 B FRAME; a version
+  change re-initialises the ring once.
+- **Watchdog semantics.** RTWDOG armed after boot, kicked from the main loop; long legitimate operations (uploads,
+  ISP, SD format) kick inside their loops with a 30 s long-op window. Before it fires it captures PC/LR into the
+  health record; the next boot reports `prev reset was watchdog` and the PC. The Studio treats a dropped link after a
+  fault as the self-reset path.
+- **Free-running timer invariant.** The refresh ISR runs at `refresh_rate_hz` (300 Hz default) regardless of command
+  traffic; SET_FRAME_POSITION only swaps the frame buffer and the ISR pushes whatever is current. Rate changes go
+  through `IntervalTimer::update()`; disarm preserves NVIC state. A frame requested twice inside one tick is
+  *superseded* (counted in the FRAME record), not lost by the controller.
+- **SD fast path invariants.** At pattern open: `FsFile` handle, `contiguousRange()` marks a contiguous file so
+  `seekSet` is arithmetic; a fragmented file falls back to the chain walk and the trial's `sd_layout` record says so
+  (bit 0 = 0). During a trial the FAT is never touched for a contiguous file. `frame_buf_is_frame_` (the buffer holds
+  frame N of the open pattern) and `sd_cache_ok_` (its derived outputs are current) gate the same-index skip; every
+  writer of the frame buffer clears the first, AO mode/LUT changes clear the second. **Never re-introduce a per-seek
+  chain walk**: that is what caused problem B.
+- **Bench switches** (`SET_SD_DIAG` 0xCE, flag bit 6): bit 0 = legacy chain-walking seek at the next open, bit 1 = no
+  same-index skip; both off at boot; readback in `GET_SD_INFO` byte 29 (bit 2 = applied to the open file); every
+  `sd_layout` record carries the arm. The harness restores the previous flags on exit. No-op on exFAT.
+
+## 3. Studio changes (webDisplayTools, v0.76 → v0.77)
+
+| area | module | what it does |
+|---|---|---|
+| Fault lifecycle (v0.76) | `js/fictrac-bridge-client.js` (`_recordApply`), `js/arena-session.js`, `js/arena-runner-g6.js`, `js/studio-postmortem.js` | ≥ 3 failed applies in the last 10 → latched fault → runner `fault()` → outcome `CONTROLLER_FAULT` auto-committed → post-mortem: quiet, confirm 0xC2, typed probes, policy `halt` / `reset-continue`; a dropped link takes the self-reset path (reconnect, MAC check, health, ring dump, crash report) |
+| Soak driver (v0.76) | `arena_studio.html` `Studio.startSoak` (File ▾ → Soak…, `?soak=1`, advanced) | repeats a protocol; exposure-based iteration outcomes; halts on first fault by default; **v0.77: accepts open-loop protocols** (no FicTrac plugin) |
+| Telemetry drain (v0.76/77) | `js/arena-telemetry.js` | decodes 0xA9 blocks; ack-cursor drainer (ack = stored by the bridge); 10 Hz poller gated on flag bit 2; rows `["cc"|"cf"|"cs", …]` into the run log; FRAME extras and STATE kinds 11–14; budget 200 chunks/poll |
+| Build + card identity | `js/arena-wire-g6.js` | `decodeFirmwareVersion` (label, flag bits), `decodeHealth` (v2 fields), `decodeCrashReport`, `decodeSdInfo` (maker/product/serial/date/capacity/FAT/cluster) → `run_metadata.firmware`, `.sd_card` |
+| Trial quality (v0.77) | `js/trial-quality.js` | per-trial **pass / flagged / unknown** from ring records in seq order: any SD read or request→display age > 10 ms flags (5 ms target); coverage gaps → unknown, never pass; `display_gap` + `trial_quality` run-log events; banner. Flag, never exclude |
+| Bench switch (v0.77) | `Studio.setSdDiag(flags)` | console helper for the causal test; arm recorded in `run_metadata.sd_card.sd_diag` |
+| Analysis | `scripts/wedge-scan.py`, `scripts/telemetry-report.py` | faults/resets per iteration; SD read cost by step class, stall clusters + phases, request ages, per-trial verdicts (reads Studio and harness logs) |
+| Protocols + patterns | `protocols/soak_mode3_closed_loop.yaml`, `soak_mode3_stress.yaml`, `soak_mode2_open_loop.yaml`, `scripts/make-stress-patterns.js` | the wedge soak; the 8 MB + bar stress; the Mode-2 control; the pattern generator |
+
+Run-log contract (unchanged for readers of `behavior_v2`): string-tagged array rows are streams, only `"a"` rows are
+behaviour samples; `cf` rows have 8 or 11 fields; readers go through `js/runlog-format.js`.
+
+## 4. Bench tools (firmware repo, browser-free)
+
+| tool | use |
+|---|---|
+| `scripts/soak_mode3.py` | Mode-3 soak/repro with the Studio's fault lifecycle (problem A) |
+| `scripts/sd_stall_test.py` | SD stall / card comparison driver: one pattern, random walk + jumps, telemetry drained into its own log, exact stall statistics, `--sd-diag N` arms, exit 4 unless the measurement is complete (problem B) |
+| `scripts/sd_upload_pat.py` | upload a `.pat` to the card and print its index + frame count |
+| `scripts/sd_soak_campaign.sh` | alternate patterns in 10-min segments, stress rate then course rate until a stop time; survives reboots and failed segments |
+| `scripts/flash_bootloader_route.sh` | flash a hex through HalfKay with the port free (6 s) |
+| `tools/pit-race-repro` | stand-alone reproducer of the PIT storm (problem A's root cause) |
+
+## 5. How to test
+
+- **Offline:** firmware `pytest tests/test_telemetry_codec.py tests/test_sd_stall_stats.py`; web `pixi run test` +
+  `pixi run format-check`.
+- **HIL (port free, controller connected):** `pytest --transport=serial --port /dev/cu.usbmodemXXXX
+  tests/test_firmware_version.py tests/test_health.py tests/test_telemetry.py tests/test_lab79_sd.py --pat <a .pat>`
+  (the `--pat` file is uploaded as `conftest.pat`; delete it afterwards via 0x86). Known pre-existing flakes:
+  `test_crashreport_passthrough` after a HalfKay reflash (junk RAM), `test_overfill_evicts_oldest…` (timing).
+- **Bench smoke (Studio):** connect → label ends `freerun sdfast` → one 60 s Mode-3 trial with the simulator → the
+  run log has `cc`/`cf`/`cs` rows, `run_metadata.firmware` + `.sd_card`, and a `trial_quality` event.
+- **Soak:** `soak-handoff-2026-09-14.md` (2 h stress, overnight benchmark, pass criteria).
+
+## 6. Evidence
+
+**Problem A (wedge):** before — 6 occurrences incl. rig 2 (2026-07-11), ~1 in 10 Mode-3 runs on 2026-09-11/12 soaks.
+After the free-running timer (`394dee4`, 09-12 night → 09-13): 24 iterations, 5.15 M commands, 0 wedges, 0 watchdog
+resets. Root cause demonstrated stand-alone: stock `IntervalTimer::end()` dies in < 0.5 s under the reproducer,
+PIT-masked variant runs 5.9 M cycles.
+
+**Problem B (stalls) — the causal test, 2026-09-13 14:47–15:11 ET, `75405ee`, bar pattern (813 KB) only, 200 Hz,
+6 min per arm, every capture complete:**
+
+| arm | FAT touched | reads | stalls > 10 ms | clusters | worst read | request age max |
+|---|---|---|---|---|---|---|
+| 3 legacy seek, no skip | yes | 71,882 | 20 | 2 (spacing 23,275 commands = the old period) | 90.8 ms | 76.7 ms |
+| 2 contiguous seek, no skip | no | 71,992 | **0** | 0 | 1.8 ms | 3.0 ms |
+| 1 legacy seek, skip on | yes | 54,885 | 6 | 1 | 70.2 ms | — |
+| 0 production | no | 54,900 | **0** | 0 | 1.8 ms | 2.9 ms |
+
+Arms 2 and 3 have identical data-read exposure and differ only in FAT access → the FAT access was the cause; the
+same-index skip does not affect the stalls (it saves 24 % of reads). Arm 3 also showed sixteen 12–19 ms stalls the old
+20 ms threshold had hidden. Earlier: 482k commands / 40 of 40 trials pass on `3c71953`; 1 h at 286 Hz on `75405ee`
+(see the bench log for the numbers). **Per-read cost on the production build:** +1 step 0.62 ms; random/backward
+1.39–1.46 ms median, 1.8 ms max; request→display age 1.7 ms median, 2.9 ms max at 200 Hz.
+
+**Overnight benchmark (candidate build):** *to be filled in the morning from `telemetry-report.py` over the campaign
+segments — stalls, clusters, per-file read cost, request ages, reboots.*
+
+## 7. Known limits and open items
+
+- **Contiguity is a precondition** for O(1) seeks. Files written in one pass are contiguous; `sd_layout` bit 0 reports
+  it per trial. A per-open cluster-chain (extent) table would remove the precondition entirely (~8 KB RAM worst case,
+  built during the open-time chain walk the code already does); deferred, decide after the benchmark.
+- **286 Hz** commands against a 300 Hz refresh: some request ages of 5–10 ms from tick coalescing are expected; that is
+  a throughput property, not an SD problem. 200 Hz is clean.
+- **Studio trial-quality banner** has not yet seen a real stall (the causal test ran through the harness); the path is
+  unit-tested (22 tests). One bench trial with arm 3 set would exercise it.
+- **AO mode / LUT change between two frame loads**: superseded accounting covered by code review, not by a HIL test.
+- **Firmware `main` port**: `main` moved to per-board `-DARENA_HW_*` headers (#48); this stack is on the 2×10 branch
+  and must be ported (supersedes fw #53).
+- **Cards**: the comparison protocol (`sd_stall_test.py` on a candidate card) is optional now; never reformat the
+  bench card, it is the baseline.
+- **Sub-threshold stalls** (12–19 ms) exist on the legacy path; the 10 ms threshold and the 5 ms target are Michael's
+  acceptance numbers, recorded in `trial-quality.js` defaults.
+
+## 8. Where things live
+
+- Firmware: `src/Health.*`, `src/Telemetry.*`, `src/Watchdog*`/`Health` v2 fields, `src/SpiManager.*` (timer),
+  `src/SdManager.*` (fast path), `src/CommandProcessor.*` (handlers), `src/Version.h` (flag bits), `README.md`
+  (byte tables), `tests/telemetry_codec.py` (decoder), `scripts/` (bench tools).
+- Web: `js/arena-wire-g6.js`, `js/arena-telemetry.js`, `js/trial-quality.js`, `js/studio-postmortem.js`,
+  `js/fictrac-bridge-client.js`, `arena_studio.html` (soak driver, sinks), `scripts/telemetry-report.py`,
+  `scripts/wedge-scan.py`, `docs/development/` (this file, `soak-handoff-2026-09-14.md`, `mode3-wedge-soak-plan.md`
+  §10 bench log, `sd-read-jitter-2026-09-13.md` §8 diagrams, `sd-stall-causal-test-plan-2026-09-13.md`,
+  `consolidation-plan-2026-09-13.md`, `telemetry-review-handoff-2026-09-13.md`).
+- Issues: firmware #50 (wedge, Michael's thread), #54 (SD stalls), web #197, #200, #201.

From 0101cefa7429c243ff6c1a9705c5c0c9d59f2806 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 15:34:56 -0400
Subject: [PATCH 23/67] =?UTF-8?q?docs:=20run-log=20format=20review=20?=
 =?UTF-8?q?=E2=80=94=20row=20types=20with=20examples,=20measured=20MB/h=20?=
 =?UTF-8?q?(=E2=89=88133=20raw=20/=2035=E2=80=9340=20gz=20at=20200=20Hz),?=
 =?UTF-8?q?=20weak=20points=20(rx=20=3D=20drain=20time,=20a=E2=86=94cc=20o?=
 =?UTF-8?q?rder=20join,=20hex),=20recommendations=20R1=20stream-gzip=20?=
 =?UTF-8?q?=E2=86=92=20R2=20schema=20v3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../mode3-reliability-handoff-2026-09-14.md   |  1 +
 .../runlog-format-review-2026-09-13.md        | 89 +++++++++++++++++++
 2 files changed, 90 insertions(+)
 create mode 100644 docs/development/runlog-format-review-2026-09-13.md

diff --git a/docs/development/mode3-reliability-handoff-2026-09-14.md b/docs/development/mode3-reliability-handoff-2026-09-14.md
index 1029e079..5679e2fe 100644
--- a/docs/development/mode3-reliability-handoff-2026-09-14.md
+++ b/docs/development/mode3-reliability-handoff-2026-09-14.md
@@ -88,6 +88,7 @@ Studio v0.77 (PRs #198 + #202). **Run sheet for the bench:** `soak-handoff-2026-
 | Analysis | `scripts/wedge-scan.py`, `scripts/telemetry-report.py` | faults/resets per iteration; SD read cost by step class, stall clusters + phases, request ages, per-trial verdicts (reads Studio and harness logs) |
 | Protocols + patterns | `protocols/soak_mode3_closed_loop.yaml`, `soak_mode3_stress.yaml`, `soak_mode2_open_loop.yaml`, `scripts/make-stress-patterns.js` | the wedge soak; the 8 MB + bar stress; the Mode-2 control; the pattern generator |
 
+Run-log format review (row types, bytes per hour, compaction plan): `runlog-format-review-2026-09-13.md`.
 Run-log contract (unchanged for readers of `behavior_v2`): string-tagged array rows are streams, only `"a"` rows are
 behaviour samples; `cf` rows have 8 or 11 fields; readers go through `js/runlog-format.js`.
 
diff --git a/docs/development/runlog-format-review-2026-09-13.md b/docs/development/runlog-format-review-2026-09-13.md
new file mode 100644
index 00000000..00d78e39
--- /dev/null
+++ b/docs/development/runlog-format-review-2026-09-13.md
@@ -0,0 +1,89 @@
+# Run-log format review — does `behavior_v2` + the controller streams make sense, and is it compact? (2026-09-13)
+
+Measured on real files from this weekend (Studio + bridge iteration `arena-log-20260913-093316`, harness
+`sdstall-…-arm3` at 200 Hz, harness `prod-286hz` at 286 Hz). Numbers are per hour of ACTIVE Mode-3 running.
+
+## 1. Answer first
+
+- **Does it make sense?** Yes. Every fact needed for round-trip latency is in the file, each row is positional and
+  self-describing through one schema line per file, and readers already treat any string-tagged array as a stream.
+  Two things are under-documented (fixed below in §4): `rx` on controller rows is the *drain* time of the whole
+  block, not the command's time; and the host `a` row and the controller `cc` row are joined by order, not by a key.
+- **Is it compact?** Raw, no: **≈ 135 MB per active hour at 200 Hz** in the Studio path (≈ 110 MB in the harness),
+  ≈ 160 MB at 286 Hz. Gzipped, yes: 3.3–4.4× → **30–40 MB/h**, and the Studio already commits `.jsonl.gz`. The bridge
+  writes the raw file during the run, so a night is ~1.5 GB on disk before commit.
+- **Recommendation, in order of payoff:** (1) stream-gzip in the bridge (level 1, 2.9×, no reader change) → a night
+  fits in ~500 MB on disk and ~35 MB/h; (2) a schema-v3 pass later (t0-relative `rx`, integer index instead of hex,
+  a host command counter on `a`) for another ~25 % and an exact `a`↔`cc` join. Nothing needs to change for the
+  hand-off; (1) is a 10-line bridge change worth doing before the overnight if time allows.
+
+## 2. What is in the file (one example line per row type)
+
+| row | source | example | fields | bytes/row |
+|---|---|---|---|---|
+| FicTrac frame | bridge, every FicTrac/simulator frame (200 Hz) | `[4,7167479,12,0.0,-16.1773,580.57226,4.14543]` | `ms` (t0-relative), `fc`, `idx` (applied frame), `ft` (FicTrac col-22, relative), `x`, `y`, `hd` | 55 |
+| `a` | browser, one per command sent (0x70 at 200 Hz) | `["a",312.652,2.285,"03 70 02 00",0,314.953]` | `t_off` (t0-relative ms), `dt` (round-trip ms), `hex` (request bytes), `status`, `rx_off`(, `error`) | 34 (Studio) / 49 (harness, longer hex) |
+| `cc` | controller ring via the drainer, one per dispatched command | `["cc",1789325242813.438,28600458,5203,112,0,"b800"]` | `rx` (host epoch ms **of the drain block**), `t_us` (controller µs at dispatch), `seq`, `cmd`, `status`, `req` (params hex) | 54 |
+| `cf` | controller ring, one per displayed frame change | `["cf",1789325242917.999,73238920,5229,2,36,1956,776,3029,1,1]` | `rx`, `t_us` (SPI start), `seq`, `idx`, `pattern`, `sd_load_us`, `spi_us`(, `req_age_us`, `superseded`, `flags`) | 55–66 |
+| `cs` | controller ring, state/error events | `["cs",1789325242813.438,28611677,5205,2,0,36]` | `rx`, `t_us`, `seq`, `kind`, `code`, `arg` | 48 |
+| objects | bridge/browser events | `{"type":"log","event":"runner",…}` | `run_metadata`, `runner`, `config`, `log_control`, `stream_schema`, `frame_schema`, `trial_quality`, `display_gap`, `soak`, `arena_command` (non-0x70 commands, full object) | 100–1200, rare |
+
+Schema lines: `frame_schema` names the FicTrac columns and `arena_cols` for `a`; `stream_schema` names the `cc`/`cf`/
+`cs` columns and the `cs` kind table. Readers: `js/runlog-format.js` (normalizer, gzip-aware), `js/runlog-replay.js`,
+dashboard `analysis-core.js` (vendored copy, test-enforced), `scripts/wedge-scan.py`, `scripts/telemetry-report.py`.
+
+## 3. Where the bytes go (per active hour, Mode 3, 200 Hz, Studio + bridge path)
+
+| stream | rows/h | B/row | MB/h | share |
+|---|---|---|---|---|
+| FicTrac frames (200 Hz) | 720k | 55 | 39 | 29 % |
+| `cc` (one per command) | 720k | 54 | 39 | 29 % |
+| `cf` (one per frame change, ~0.76 per command) | 550k | 55 | 30 | 22 % |
+| `a` (one per command) | 720k | 34 | 25 | 18 % |
+| `cs` + objects | ~100 | — | < 0.1 | 0 % |
+| **total raw** | | | **≈ 133** | |
+| gzip −6 (commit path) | | | ≈ 35–40 (3.3–3.8×) | |
+
+Harness (`sd_stall_test.py`, no FicTrac rows, longer `a` hex): 110 MB/h at 200 Hz, 157 MB/h at 286 Hz; gzip 4.3× →
+25–36 MB/h. At 100 Hz (the course rate for most rigs) everything halves except the FicTrac rows.
+
+So the controller telemetry costs about as much as the behaviour stream it explains (2.5× the FicTrac rows), and
+half of the controller bytes are the `rx` epoch stamps and the hex strings, which is where the compaction is.
+
+## 4. Does the design make sense — the review
+
+**Three clocks, all present.** FicTrac time (`ft`, from the tracker), host time (`ms`/`t_off`/`rx`, browser or
+bridge epoch), controller time (`t_us`, free-running µs, wraps every 71.6 min, `seq` disambiguates). Round trip of one
+frame command = `a.t_off` (host send) → `cc.t_us` (controller dispatch) → `cf.t_us` (SPI start; `req_age_us` = the
+difference measured on the controller, so no clock fit needed for the part that matters) → `a.rx_off` (host reply).
+The host↔controller offset comes from pairing `a` and `cc` (drift-free within a run; a linear fit over the run is the
+analysis step the telemetry review session owns).
+
+**Verdicts are derivable offline** (`telemetry-report.py` reproduces the Studio's per-trial pass/flagged/unknown from
+the same rows), which is the property that matters for a data pipeline: the log is the truth, the banner is a view.
+
+**Weak points, honestly:**
+1. `rx` on `cc`/`cf`/`cs` is the host time the *block* was drained, so it is up to 100 ms late and identical for all
+   records of a block. It is documented in the module header but readers keep mistaking it for the command's time;
+   `t_us` is the controller-side time. → Rename in the schema-v3 pass (`drain_ms`) and make it t0-relative.
+2. The `a` row has no key to its `cc` row; the join is by command order (both are complete sequences, and
+   `telemetry-report.py` reconciles the counts). A host command counter on `a` (one small int) would make it exact and
+   robust to a lost reply. → schema v3.
+3. Hex strings: `"03 70 02 00"` (13 B) on every `a` and `"b800"` (6 B) on every `cc` when the value is a u16 frame
+   index. → integer `idx` for 0x70 rows in schema v3 (keep hex for other opcodes).
+4. Duplication by design: `a` (host view) and `cc` (controller view) both exist per command; that is the point (the
+   two clocks), not waste — but with schema v3 the pair costs ~55 B instead of ~90 B.
+5. The FicTrac stream is logged whenever logging is on, including between runs (the 131-min file above held 21 min of
+   trials). Cheap (39 MB/h) but worth a `log_control` pause outside runs in the soak driver.
+
+## 5. Recommendations
+
+| # | change | where | saving | reader impact | when |
+|---|---|---|---|---|---|
+| R1 | **stream-gzip the live file** (`gzip.open(…, 'wt', compresslevel=1)`, flush per drain), name it `.jsonl.gz` from the start | `fictrac-bridge/bridge.py` `_open`/`write` | 2.9× on disk during the run; commit path unchanged | none (all readers inflate on the magic) | before the overnight if the review window allows; else next |
+| R2 | schema v3: `rx` → t0-relative ms with 1 decimal (`drain_ms`), `a` gets a host command counter, 0x70 `hex`/`req` → integer index | `js/arena-telemetry.js` `toRows`, `js/arena-session.js` `a` row, `stream_schema`/`frame_schema` version, readers | ≈ 25 % of the controller bytes; exact `a`↔`cc` join | all readers (normalizer, dashboard copy, wedge-scan, telemetry-report) + tests | after the hand-off, one PR |
+| R3 | pause the FicTrac stream between runs in the soak driver | `Studio.startSoak` (`bridge.setLogging`) | ~39 MB per idle hour | none | with R2 |
+| R4 | document `rx` semantics and the order-join in the header comment of `js/arena-telemetry.js` and in `runlog-behavior-v2-plan.md` | docs | — | — | now (done in this doc; header comment in R2) |
+
+Target after R1+R2: **≈ 25 MB per active hour gzipped at 200 Hz, ≈ 100 MB raw** — "1 h well under 100 MB" holds for the
+committed artefact today (35–40 MB) and for the on-disk file after R1.

From 9cb940f4264a847605f85410224148f7ef684f99 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 15:42:56 -0400
Subject: [PATCH 24/67] =?UTF-8?q?fix(studio):=20whole-stack=20review=20?=
 =?UTF-8?q?=E2=80=94=20verdict=20+=20final=20drain=20before=20the=20run-lo?=
 =?UTF-8?q?g=20export=20(normal=20and=20fault=20runs),=20drain=20errors/re?=
 =?UTF-8?q?fused=20rows/seq=20gaps=20=E2=86=92=20trial=20'unknown',=20brid?=
 =?UTF-8?q?ge=20send=20failure=20not=20acked,=20FRAME=20sd=5Fload=5Fus=20c?=
 =?UTF-8?q?ounted=20in=20verdicts=20(JS=20+=20report),=20link-drop=20class?=
 =?UTF-8?q?ified=20as=20CONTROLLER=5FFAULT=20before=20the=20outcome=20is?=
 =?UTF-8?q?=20derived,=20stress-protocol=20gain=200.18,=20wire-comment=20f?=
 =?UTF-8?q?ixes=20=E2=80=94=20Studio=20v0.78?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 arena_studio.html                             | 94 ++++++++++++++-----
 .../development/arena-studio-release-notes.md | 18 ++++
 js/arena-telemetry.js                         | 17 +++-
 js/arena-wire-g6.js                           |  4 +-
 js/fictrac-bridge-client.js                   |  9 +-
 js/trial-quality.js                           | 24 +++++
 protocols/soak_mode3_stress.yaml              | 13 +--
 scripts/telemetry-report.py                   | 11 +++
 8 files changed, 153 insertions(+), 37 deletions(-)

diff --git a/arena_studio.html b/arena_studio.html
index 7500253f..b98fa1e7 100644
--- a/arena_studio.html
+++ b/arena_studio.html
@@ -2959,7 +2959,7 @@ <h2 id="modalTitle">Import error</h2>
 </div>
 
 <footer id="footer">
-  <span class="foot-left">Arena Studio v0.77 | 2026-09-13 13:58 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.78 | 2026-09-13 15:42 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)">
@@ -3195,6 +3195,16 @@ <h2 id="modalTitle">Import error</h2>
         if (window.Scope && window.Scope.onRunStatus) window.Scope.onRunStatus(s);
         // feed the recorded-run accumulator
         if (Studio.activeRunLog) {
+            // A run that ended because the LINK DROPPED (watchdog self-reset re-enumerates the
+            // controller) and not because the user pressed STOP is a controller fault. Decide it
+            // HERE, before the adapter derives the terminal outcome — deciding it afterwards (as
+            // runSteps also does, as a fallback) left the stored outcome ABORTED_BY_USER and
+            // skipped the auto-commit (whole-stack review, 2026-09-13).
+            const sm = s && s.summary;
+            if (sm && !sm.fault && sm.aborted && Studio._linkDropped && !Studio._userStopRequested) {
+                sm.fault = 'link_dropped';
+                sm.faultDetail = { kind: 'link_dropped', note: 'controller re-enumerated mid-run (watchdog self-reset?)' };
+            }
             const r = Adapter.feedRunStatus(Studio.activeRunLog, s);
             if (r.event) renderRunEvent(r.event);
             if (r.terminal) onRunFinished(r.summary);
@@ -3331,11 +3341,18 @@ <h2 id="modalTitle">Import error</h2>
         // Controller fault (fw #50): the export closes the bridge's log file, so it
         // must wait for the post-mortem (STOP result, probes, ring crash dump) —
         // Studio.handleControllerFault runs the deferred commit in its finally.
+        // The export closes the bridge's log file, so the final telemetry drain and the
+        // per-trial `trial_quality` verdict must be written FIRST (whole-stack review,
+        // 2026-09-13: they used to land after the export and were lost from committed logs).
+        const finalizeThenCommit = async () => {
+            try { if (Studio.finalizeTrialQuality) await Studio.finalizeTrialQuality(); } catch (_) { /* best effort */ }
+            await maybeCommitRunLog(log, summary);
+        };
         if (summary && summary.outcome === 'CONTROLLER_FAULT' && Studio.handleControllerFault) {
-            Studio._pendingCommit = () => maybeCommitRunLog(log, summary);
+            Studio._pendingCommit = finalizeThenCommit;
             rawLine('run log commit deferred until the controller post-mortem finishes', 'warn');
         } else {
-            maybeCommitRunLog(log, summary); // course pipeline — async, best-effort
+            finalizeThenCommit(); // course pipeline — async, best-effort
         }
     }
 
@@ -8162,6 +8179,47 @@ <h2 id="modalTitle">Import error</h2>
     await Studio.startSoak(parseSoakSpec(spec));
 };
 
+// Stimulus quality (SD-card stalls, 2026-09-13): the run's final ring records must land in
+// THIS log file and the per-trial pass / flagged / unknown verdict must be written before the
+// export closes the file. Called from onRunFinished (before the commit) and from runSteps (a
+// fallback); runs once per run — later callers await the first. Flag only — excluding or
+// repeating a trial is the experimenter's decision (selection-bias caveat, Codex review).
+Studio.finalizeTrialQuality = function () {
+    if (Studio._tqFinal) return Studio._tqFinal;
+    Studio._tqFinal = (async () => {
+        if (!Studio.trialQuality) return null;
+        const tel = Studio.telemetry;
+        const bridge = Studio.session.bridge;
+        if (tel && Studio.telemetryAvailable && Studio.session.connected && !Studio._activePostmortem) {
+            const st = tel.drainer.stats;
+            const before = { errors: st.errors, notStored: st.notStored, gaps: st.gaps };
+            try {
+                await tel.drainer.idle();       // a poll in flight would make drainOnce() a no-op
+                await tel.drainer.drainOnce();  // the trailing sd_reads / state_change records
+            } catch (_) { /* accounted below */ }
+            // An incomplete final drain means the tail (where the last stall would be) may be
+            // missing: the open trial cannot be 'pass' (whole-stack review, 2026-09-13).
+            if (st.errors > before.errors || st.notStored > before.notStored || st.gaps > before.gaps) {
+                Studio.trialQuality.noteCoverage('final_drain_incomplete', { errors: st.errors - before.errors, not_stored: st.notStored - before.notStored, gaps: st.gaps - before.gaps });
+            }
+        } else if (tel && Studio.telemetryAvailable && Studio.activeRunLog) {
+            Studio.trialQuality.noteCoverage('final_drain_skipped', { connected: !!Studio.session.connected, postmortem: !!Studio._activePostmortem });
+        }
+        const tq = Studio.trialQuality.finish();
+        Studio.lastTrialQuality = tq;
+        if (tq.trials.length) {
+            if (bridge && bridge.connected && bridge.logging) bridge.log(Object.assign({ event: 'trial_quality' }, tq));
+            const thr = tq.threshold_us / 1000;
+            const msg = 'stimulus quality: ' + (tq.counts.pass || 0) + ' pass · ' + (tq.counts.fail || 0) + ' flagged · ' + (tq.counts.unknown || 0) + ' unknown'
+                + (tq.flagged_trials.length ? ' — display gap > ' + thr + ' ms in trial' + (tq.flagged_trials.length > 1 ? 's ' : ' ') + tq.flagged_trials.join(', ') + ' (worst ' + Math.round(tq.worst_gap_us / 100) / 10 + ' ms)' : '');
+            Studio.rawLog(msg, tq.counts.fail ? 'warn' : 'info');
+            if (tq.counts.fail && !Studio.soak) Studio.showBanner('⚠ ' + msg);
+        }
+        return tq;
+    })();
+    return Studio._tqFinal;
+};
+
 Studio.startSoak = async function (cfg) {
     if (Studio.soak) return;
     if (!Studio.advanced) { Studio.showBanner('Soak is an advanced-mode feature.'); return; }
@@ -8348,6 +8406,11 @@ <h2 id="modalTitle">Import error</h2>
             session: Studio.session,
             wire: Wire,
             maxBytes: 178, // firmware reply budget: 3 + payload < 200 ⇒ 196 − 18 B header
+            // A drain error, a refused batch or a sequence gap while a run is recorded means
+            // the open trial may be missing records: 'unknown', never 'pass'.
+            onCoverage: (kind, detail) => {
+                if (Studio.trialQuality && Studio.activeRunLog) Studio.trialQuality.noteCoverage(kind, detail);
+            },
             onRecords: (block, rows) => {
                 // Per-trial stimulus quality (js/trial-quality.js): fed BEFORE the sink
                 // decides, in ring order; the module dedups re-delivered records by seq.
@@ -8628,6 +8691,7 @@ <h2 id="modalTitle">Import error</h2>
     Studio._userStopRequested = false;
     Studio._linkDropped = false;
     if (Studio.trialQuality) Studio.trialQuality.reset(); // per-trial stimulus-quality verdicts start fresh
+    Studio._tqFinal = null; // finalizeTrialQuality() runs once per run (first caller wins, others await it)
     try {
         // NOTE: do NOT pass onProgress — the session broadcasts 'runstatus' which
         // Studio.onRunStatus (subscribed once) consumes, so the log/highlight stay
@@ -8659,27 +8723,9 @@ <h2 id="modalTitle">Import error</h2>
         if (summary && summary.fault) {
             Studio._lastPostmortem = await Studio.handleControllerFault(summary);
         }
-        // Stimulus quality (SD-card stalls, 2026-09-13): one last drain so the run's final ring
-        // records land in THIS log file, then the per-trial pass / flagged / unknown verdict →
-        // `trial_quality` event + a banner. Flag only — excluding or repeating a trial is the
-        // experimenter's decision (selection-bias caveat, Codex review).
-        if (Studio.trialQuality) {
-            try {
-                if (Studio.telemetry && Studio.telemetryAvailable && Studio.session.connected && !Studio._activePostmortem) {
-                    await Studio.telemetry.drainer.drainOnce();
-                }
-            } catch (_) { /* best effort */ }
-            const tq = Studio.trialQuality.finish();
-            Studio.lastTrialQuality = tq;
-            if (tq.trials.length) {
-                if (bridge.connected && bridge.logging) bridge.log(Object.assign({ event: 'trial_quality' }, tq));
-                const thr = tq.threshold_us / 1000;
-                const msg = 'stimulus quality: ' + (tq.counts.pass || 0) + ' pass · ' + (tq.counts.fail || 0) + ' flagged · ' + (tq.counts.unknown || 0) + ' unknown'
-                    + (tq.flagged_trials.length ? ' — display gap > ' + thr + ' ms in trial' + (tq.flagged_trials.length > 1 ? 's ' : ' ') + tq.flagged_trials.join(', ') + ' (worst ' + Math.round(tq.worst_gap_us / 100) / 10 + ' ms)' : '');
-                Studio.rawLog(msg, tq.counts.fail ? 'warn' : 'info');
-                if (tq.counts.fail && !Studio.soak) Studio.showBanner('⚠ ' + msg);
-            }
-        }
+        // Stimulus quality: normally already finalized by onRunFinished (before the export);
+        // this is the fallback for runs without a run log (Test runs).
+        await Studio.finalizeTrialQuality();
     } catch (e) {
         Studio.rawLog('run error: ' + (e && e.message ? e.message : e), 'err');
         if (Studio.activeRunLog && !Studio.activeRunLog.summary) {
diff --git a/docs/development/arena-studio-release-notes.md b/docs/development/arena-studio-release-notes.md
index a6f1ea3a..3612d78a 100644
--- a/docs/development/arena-studio-release-notes.md
+++ b/docs/development/arena-studio-release-notes.md
@@ -4,6 +4,24 @@ 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.78 (2026-09-13) · Whole-stack review fixes: the verdict lands in the log
+
+- **The stimulus-quality verdict is written before the run log is exported.** The final telemetry
+  drain and the `trial_quality` event used to run after the export had closed the bridge's file, so
+  committed logs lost the run's last records and the verdict. Both now run first, on normal runs and on
+  controller-fault runs (after the post-mortem, before the deferred commit).
+- **Missing telemetry can no longer produce a `pass`.** A drain error, a refused batch, a sequence gap
+  or an incomplete final drain marks the open trial `unknown`; a batch the bridge socket failed to send
+  is no longer acknowledged (the controller keeps those records for the next poll).
+- **Slow reads visible only in a FRAME record count.** A read over 10 ms flags the trial even without
+  an `sd_slow` event (ring-v1 firmware only emits those above 20 ms); counted once per read. Same rule
+  in `scripts/telemetry-report.py`.
+- **A watchdog self-reset mid-run is recorded as a controller fault** (outcome `CONTROLLER_FAULT`,
+  auto-committed) instead of `ABORTED_BY_USER`.
+- Stress protocol gain corrected to 0.18 °/frame for the 2000-frame sine (the bridge divides heading
+  by gain; 18 moved 5 frames per 90° jump instead of 500). Wire-comment fixes (crash report gate = flag
+  bit 3, SD diag gate = bit 6, FRAME `sd_load_us` is u32).
+
 ## v0.77 (2026-09-13) · SD-card stall visibility: per-trial stimulus quality, card identity, request→display latency
 
 - **Display freezes are now flagged per trial.** The controller's SD card stalls for 30–90 ms every
diff --git a/js/arena-telemetry.js b/js/arena-telemetry.js
index e2dad8d7..052d495f 100644
--- a/js/arena-telemetry.js
+++ b/js/arena-telemetry.js
@@ -17,7 +17,7 @@
  *                  reboot) · boot_count u16   = 18 B header, then records
  *   record: len u8 (total) · type u8 · seq u32 · t_us u32 · payload
  *     1 CMD   : cmd u8 · status u8 · plen u8 · payload[plen ≤ 8]   (request bytes)
- *     2 FRAME : idx u16 · pattern u16 · sd_load_us u16 · spi_us u16
+ *     2 FRAME : idx u16 · pattern u16 · sd_load_us u32 · spi_us u32   (20 B; 26 B in ring v2, see below)
  *     3 STATE : kind u8 · code u8 · arg u16
  *               kind 8 wdog_context (boot after a watchdog reset, fw eca07f6 follow-up): code = the
  *               watchdog handler's EXC_RETURN low byte (0xF9 preempted thread mode, 0xF1 a handler),
@@ -283,6 +283,10 @@
         const maxChunks = d.maxChunks || 200;
         const now = d.now || (() => Date.now());
         const onRecords = d.onRecords || (() => {});
+        // Coverage events for the per-trial verdict (whole-stack review, 2026-09-13): a
+        // drain error, a refused batch or a sequence gap means records may be missing
+        // from the log — the trial open at that moment can be 'unknown' but never 'pass'.
+        const onCoverage = d.onCoverage || (() => {});
         const st = {
             ackSeq: NO_ACK, // nothing acked yet
             lastSeq: null, // highest seq seen
@@ -324,12 +328,14 @@
                     } catch (e) {
                         st.errors++;
                         st.lastError = (e && e.message) || String(e);
+                        onCoverage('drain_error', { error: st.lastError });
                         break;
                     }
                     const block = parseBlock(resp, W);
                     if (!block) {
                         st.errors++;
                         st.lastError = 'unparseable telemetry block';
+                        onCoverage('drain_error', { error: st.lastError });
                         break;
                     }
                     const rx = now();
@@ -365,11 +371,18 @@
                         const accepted = onRecords(block, toRows(block, rx), rx) !== false;
                         if (!accepted) {
                             st.notStored++;
+                            onCoverage('rows_not_stored', {
+                                seq: block.records[0].seq,
+                                n: block.records.length
+                            });
                             blocks.push(block);
                             break;
                         }
                         for (const r of block.records) {
-                            if (st.lastSeq != null && r.seq !== (st.lastSeq + 1) >>> 0) st.gaps++;
+                            if (st.lastSeq != null && r.seq !== (st.lastSeq + 1) >>> 0) {
+                                st.gaps++;
+                                onCoverage('seq_gap', { from: st.lastSeq, to: r.seq });
+                            }
                             st.lastSeq = r.seq;
                             st.records++;
                         }
diff --git a/js/arena-wire-g6.js b/js/arena-wire-g6.js
index acc3da73..d67b95eb 100644
--- a/js/arena-wire-g6.js
+++ b/js/arena-wire-g6.js
@@ -67,10 +67,10 @@ const ArenaWireG6 = (function () {
         SET_DIAG_OUTPUT: 0xc3, // [len=2,0xC3,on] mute/unmute DEBUG_SERIAL diagnostics
         GET_DIAG_OUTPUT: 0xc4, // returns current g_dbg_on state (0/1)
         GET_HEALTH: 0xca, // [01 CA] controller health counters + previous-boot breadcrumb (fw #50)
-        GET_CRASHREPORT: 0xcc, // [01 CC] raw 128 B at OCRAM 0x2027FF80: PJRC arm_fault_info_struct + breadcrumbs (ring fw; gate on 0xCB flags bit 2)
+        GET_CRASHREPORT: 0xcc, // [01 CC] raw 128 B at OCRAM 0x2027FF80: PJRC arm_fault_info_struct + breadcrumbs (gate on 0xCB flags bit 3 = crash report)
         GET_FIRMWARE_VERSION: 0xcb, // [01 CB] build identity: git SHA, branch, date, arena rows×cols (gate on cap bit 7)
         GET_SD_INFO: 0xcd, // SD card identity + volume geometry (fw sd_fastpath; gate on 0xCB flags bit 5)
-        SET_SD_DIAG: 0xce, // [02 CE flags] bench A/B: bit0 legacy FAT-chain seek (next open), bit1 no same-index skip (gate on 0xCB bit 5)
+        SET_SD_DIAG: 0xce, // [02 CE flags] bench A/B: bit0 legacy FAT-chain seek (next open), bit1 no same-index skip (gate on 0xCB bit 6 = sdDiag)
         SET_TELEMETRY: 0xa8, // [04 A8 flags rate_lo rate_hi] telemetry ring: bit0 events on/off (fw feat/telemetry-ring)
         GET_TELEMETRY_BLOCK: 0xa9, // [08 A9 ack_seq u32 max_bytes u16 flags] ack-cursor drain of the ring (js/arena-telemetry.js decodes)
         SET_AO_VOLTAGE: 0xa0, // [03 A0 mv_lo mv_hi] set analog output (BNC J27) 0–5000 mV
diff --git a/js/fictrac-bridge-client.js b/js/fictrac-bridge-client.js
index 1df3930a..4700c45e 100644
--- a/js/fictrac-bridge-client.js
+++ b/js/fictrac-bridge-client.js
@@ -507,8 +507,9 @@
         logRows(rows) {
             if (!Array.isArray(rows) || !rows.length) return true;
             if (!(this._logging && this.connected)) return false; // not stored — caller keeps them
-            this._send({ type: 'rows', rows });
-            return true;
+            // A send on a closing socket throws inside _send: that batch was NOT stored,
+            // so report false and the drainer withholds its ack (whole-stack review, 2026-09-13).
+            return this._send({ type: 'rows', rows });
         }
 
         /**
@@ -654,10 +655,12 @@
             if (ws && ws.readyState === 1 /* OPEN */) {
                 try {
                     ws.send(JSON.stringify(obj));
+                    return true;
                 } catch (_) {
-                    /* a closing socket can throw on send — ignore */
+                    return false; // a closing socket can throw on send — the caller decides
                 }
             }
+            return false;
         }
         _startRateTimer() {
             if (this._rateTimer || typeof setInterval === 'undefined') return;
diff --git a/js/trial-quality.js b/js/trial-quality.js
index f8db7697..10c99f4c 100644
--- a/js/trial-quality.js
+++ b/js/trial-quality.js
@@ -69,6 +69,8 @@
                 ageGaps: [], // over-threshold FRAME req_age_us
                 overTarget: 0, // FRAME req_age_us over the target (5 ms) but under the threshold
                 maxReadUs: 0,
+                lastSlowSeq: null, // seq of the last sd_slow (dedup with the FRAME read that follows it)
+                lastFrameSeq: null,
                 maxAgeUs: 0,
                 superseded: 0,
                 coverage: pendingCoverage.splice(0)
@@ -149,6 +151,7 @@
                             if (!current) break;
                             const us = (r.readUs != null ? r.readUs : r.arg * 100) >>> 0;
                             current.slowReads++;
+                            current.lastSlowSeq = r.seq;
                             if (us > current.maxReadUs) current.maxReadUs = us;
                             if (us > gapUs) {
                                 const ev = gapEvent('sd_slow', r, us, {
@@ -184,6 +187,27 @@
                     current.frames++;
                     if (current.lastIdx == null) current.lastIdx = r.idx; // the trial's initial frame: a 0x70 for it is not an index change
                     if (typeof r.superseded === 'number') current.superseded += r.superseded;
+                    // The read that produced this frame: its duration is in the FRAME record
+                    // even when no sd_slow STATE was emitted (ring-v1 firmware only flags
+                    // reads > 20 ms; the verdict threshold is 10 ms). An sd_slow for the same
+                    // read precedes its FRAME, so count the read once: only when no sd_slow
+                    // arrived since the previous frame (whole-stack review, 2026-09-13).
+                    if (typeof r.sdLoadUs === 'number') {
+                        if (r.sdLoadUs > current.maxReadUs) current.maxReadUs = r.sdLoadUs;
+                        const slowSeenForThisRead =
+                            current.lastSlowSeq != null &&
+                            current.lastSlowSeq > (current.lastFrameSeq || 0);
+                        if (r.sdLoadUs > gapUs && !slowSeenForThisRead) {
+                            gapEvent('frame_read', r, r.sdLoadUs, { idx: r.idx });
+                            current.stalls.push({
+                                seq: r.seq,
+                                tUs: r.tUs,
+                                us: r.sdLoadUs,
+                                phase: 'unknown'
+                            });
+                        }
+                        current.lastFrameSeq = r.seq;
+                    }
                     if (typeof r.reqAgeUs === 'number') {
                         if (r.reqAgeUs > current.maxAgeUs) current.maxAgeUs = r.reqAgeUs;
                         if (r.reqAgeUs > gapUs) {
diff --git a/protocols/soak_mode3_stress.yaml b/protocols/soak_mode3_stress.yaml
index 82d17708..0a403fdc 100644
--- a/protocols/soak_mode3_stress.yaml
+++ b/protocols/soak_mode3_stress.yaml
@@ -10,10 +10,11 @@ version: 3
 # for hours. Verdicts: per-trial `trial_quality` (pass / flagged / unknown) and
 # `scripts/telemetry-report.py`.
 #
-# Gains: the bridge maps heading → frame index modulo the trial's frame count.
-#   18  = 2000 / 360 → one revolution sweeps the WHOLE 8 MB file (a 90° jump =
-#         500 frames = 2 MB seek); 1.8 = 200 / 360 for the bar (as in the
-#         standard soak). Both files must be contiguous on the card (sd_layout
+# Gains are DEGREES OF HEADING PER FRAME (the bridge computes round(deg / gain)):
+#   0.18 = 360 / 2000 → one revolution sweeps the WHOLE 8 MB file (a 90° jump =
+#          500 frames = 2 MB seek); 1.8 = 360 / 200 for the bar (as in the
+#          standard soak). (An earlier draft said 18 — that was 100× too small a
+#          step: 5 frames per 90° jump. Whole-stack review, 2026-09-13.) Both files must be contiguous on the card (sd_layout
 #         bit0 = 1); make them with scripts/make-stress-patterns.js and upload
 #         through the Studio Console.
 #
@@ -39,7 +40,7 @@ plugins:
       bridge_url: "ws://localhost:8765"
       fictrac_port: 60000
       proto: "udp"
-      gain: 18
+      gain: 0.18
       offset: 0
 
 variables:
@@ -87,7 +88,7 @@ conditions:
         plugin_name: "fictrac"
         command_name: "startClosedLoop"
         params:
-          gain: 18
+          gain: 0.18
       - type: "wait"
         duration: *cl_dur
       - type: "plugin"
diff --git a/scripts/telemetry-report.py b/scripts/telemetry-report.py
index f1ce75c4..84646b6d 100644
--- a/scripts/telemetry-report.py
+++ b/scripts/telemetry-report.py
@@ -125,6 +125,8 @@ def __init__(self, index, pattern, rx, t_us):
         self.over_target = 0
         self.max_read_ms = 0.0
         self.max_age_ms = 0.0
+        self.last_slow_seq = None   # dedup: an sd_slow precedes the FRAME of the same read
+        self.last_frame_seq = None
         self.superseded = 0
         self.coverage = []
         self.layout = None
@@ -243,6 +245,7 @@ def analyze_file(path: str, gap_ms: float = 10.0, target_ms: float = 5.0) -> dic
                     err = bool(isinstance(code, int) and code & 0x80)
                     slow_all += 1
                     if cur is not None:
+                        cur.last_slow_seq = arr[3] if isinstance(arr[3], int) else cur.last_slow_seq
                         cur.slow_reads += 1
                         cur.max_read_ms = max(cur.max_read_ms, ms)
                     if ms * 1000.0 > gap_us:
@@ -295,6 +298,14 @@ def analyze_file(path: str, gap_ms: float = 10.0, target_ms: float = 5.0) -> dic
                     cur.frames += 1
                     if cur.last_idx is None:
                         cur.last_idx = idx   # the trial's initial frame: a 0x70 for it is not an index change
+                    # The read behind this frame counts even without an sd_slow STATE (ring v1 only flags
+                    # > 20 ms); counted once — skip it when an sd_slow for the same read preceded the FRAME.
+                    seq = arr[3] if isinstance(arr[3], int) else None
+                    cur.max_read_ms = max(cur.max_read_ms, sd_us / 1000.0)
+                    slow_for_this_read = cur.last_slow_seq is not None and cur.last_slow_seq > (cur.last_frame_seq or 0)
+                    if sd_us > gap_us and not slow_for_this_read:
+                        cur.stalls.append((sd_us / 1000.0, "frame"))
+                    cur.last_frame_seq = seq
                 if pattern in pending_first:
                     cls = "first-after-open"
                     pending_first.discard(pattern)

From 9f06e5e903a5d654cc64e2701f45106f16d32636 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 15:47:17 -0400
Subject: [PATCH 25/67] test(trial-quality): FRAME-only slow read flags the
 trial; sd_slow + its FRAME count once (25 checks)

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 tests/test-trial-quality.js | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/tests/test-trial-quality.js b/tests/test-trial-quality.js
index 8668fe95..9c7cc6b1 100644
--- a/tests/test-trial-quality.js
+++ b/tests/test-trial-quality.js
@@ -175,5 +175,21 @@ console.log('\n=== reset() clears everything ===');
     check('threshold default', q.thresholdUs, 10000);
 }
 
+// ---- whole-stack review 2026-09-13: a slow read visible only in the FRAME record counts once ----
+{
+    const q = TQ.createTrialQuality({ gapUs: 10000, targetUs: 5000 });
+    seq = 1000;
+    q.feed([S(7, 0, 36, 1000)]); // sd_open ok → trial 1
+    // ring-v1 style: a 15 ms read with NO sd_slow event (v1 only flags > 20 ms)
+    q.feed([Object.assign(F(3, 2000, 1500, 0), { sdLoadUs: 15000 })]);
+    // ring-v2 style: sd_slow (33 ms) FOLLOWED by the FRAME of the same read → one stall, not two
+    q.feed([S(4, 2, 330, 3000, { readUs: 33000, phase: 'body' })]);
+    q.feed([Object.assign(F(4, 3100, 1500, 0), { sdLoadUs: 33000 })]);
+    const t = q.finish().trials[0];
+    check('frame-only slow read flags the trial', t.status, 'fail');
+    check('frame-only + sd_slow-covered read = 2 stalls (not 3)', t.stalls, 2);
+    check('max_read_ms from the FRAME reads', t.max_read_ms, 33);
+}
+
 console.log(`\n${total - failures} / ${total} checks passed`);
 process.exit(failures ? 1 : 0);

From 71fb11943e4733d0e17b7fe6beacdb2fe5cce611 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 15:48:17 -0400
Subject: [PATCH 26/67] docs: whole-stack review reconciliation (web) +
 applied/deferred lists in the consolidation plan and the hand-off document

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/development/consolidation-plan-2026-09-13.md      |  8 ++++++++
 .../mode3-reliability-handoff-2026-09-14.md            | 10 ++++++++++
 2 files changed, 18 insertions(+)

diff --git a/docs/development/consolidation-plan-2026-09-13.md b/docs/development/consolidation-plan-2026-09-13.md
index df054b77..cdf36728 100644
--- a/docs/development/consolidation-plan-2026-09-13.md
+++ b/docs/development/consolidation-plan-2026-09-13.md
@@ -47,6 +47,14 @@ review report; (c) **one detailed hand-off document** explaining all the changes
 | S-2 | web | run sheet: browser-free campaign path (upload + `sd_soak_campaign.sh`) as the default overnight tool; Studio path as the alternative | it is what ran tonight |
 | S-3 | web | CLAUDE.md: one line on `sd_soak_campaign` / `sd_upload_pat` and on "stalls were FAT access — never re-introduce chain-walking seeks" | institutional memory |
 
+### 4.1 Applied after the whole-stack reviews (15:30–16:00 ET) — see `.codex-review/report-20260913-*-fullstack.md`
+Firmware (commit after `75405ee`): panels blanked at boot (a watchdog/software reset left the last frame lit),
+watchdog kicked inside the ISP loops, same-index skip only after a successful DAC/LUT update, `SET_SD_DIAG` bit 0
+refused on exFAT (F-1 done), harness drains the backlog to completion, script deadline/verification fixes.
+Studio v0.78: verdict + final drain before the export (normal and fault runs), drain problems → `unknown`, bridge
+send failure not acked, FRAME read time in verdicts, link-drop = controller fault, stress gain 0.18, comment fixes.
+Deferred items are listed in the hand-off document §7.
+
 ## 5. Overnight run (on the candidate)
 
 `scripts/sd_soak_campaign.sh PORT "<sine idx> 36" 200 <until 08:00>` — 10-min alternating segments of the 8 MB sine and
diff --git a/docs/development/mode3-reliability-handoff-2026-09-14.md b/docs/development/mode3-reliability-handoff-2026-09-14.md
index 5679e2fe..535ac9a4 100644
--- a/docs/development/mode3-reliability-handoff-2026-09-14.md
+++ b/docs/development/mode3-reliability-handoff-2026-09-14.md
@@ -158,6 +158,16 @@ segments — stalls, clusters, per-file read cost, request ages, reboots.*
 - **Sub-threshold stalls** (12–19 ms) exist on the legacy path; the 10 ms threshold and the 5 ms target are Michael's
   acceptance numbers, recorded in `trial-quality.js` defaults.
 
+### 7.1 Deferred from the whole-stack reviews (2026-09-13, both repos)
+Firmware: ring `seq` u32 rollover (~6 days continuous) and an incarnation id for the ack cursor; single ring header;
+ISR breadcrumb cost with telemetry off; a lean "timer fix only" release if ever wanted; HIL tests for DAC-failure
+retry, watchdog recovery and faster-than-refresh request storms; `soak_mode3.py` explicit unsynchronised state.
+Studio: a session-owned run-finalization state machine; trial identity from runner ids rather than observed opens;
+shared verdict conformance fixtures (JS ↔ Python); `SET_TELEMETRY(0)` for the "telemetry off" toggle; soak exposure
+per interval; report truncation → unknown and bounded accumulators; controller-time clustering in the report;
+`arena-link` write-timeout race; bridge rows-capability negotiation. None affects tonight's benchmark; all are
+recorded so the next session starts from the list, not from a re-review.
+
 ## 8. Where things live
 
 - Firmware: `src/Health.*`, `src/Telemetry.*`, `src/Watchdog*`/`Health` v2 fields, `src/SpiManager.*` (timer),

From 4c532ee881d74dc0004bb47acfe71118ce1bff74 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 15:49:31 -0400
Subject: [PATCH 27/67] docs(run sheet): candidate e59767e, Studio v0.78,
 browser-free upload + campaign path, index renumbering warning

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/development/soak-handoff-2026-09-14.md | 23 ++++++++++++++++-----
 1 file changed, 18 insertions(+), 5 deletions(-)

diff --git a/docs/development/soak-handoff-2026-09-14.md b/docs/development/soak-handoff-2026-09-14.md
index 4be0d810..f52808a5 100644
--- a/docs/development/soak-handoff-2026-09-14.md
+++ b/docs/development/soak-handoff-2026-09-14.md
@@ -8,8 +8,8 @@ path. If the overnight run is clean, these are the branches to merge.
 
 | piece | where | identity |
 |---|---|---|
-| firmware | `reiserlab/LED-Display_G6_Firmware_Arena` branch `feat/sd-fastpath-2x10`, commit **`75405ee`** (2×10 bench branch; fast-forwards `arena-2x10-local`) | `pio run -e teensy41-performance` → `.pio/build/teensy41-performance/firmware.hex`, sha256 starts `5d912915dd0982d9`; Studio shows the label `75405ee 2x10 … freerun sdfast` |
-| Studio | `reiserlab/webDisplayTools` PR #198 (v0.76) + PR #202 (v0.77, branch `claude/mode3-perf-sd`) | serve the branch locally: `python3 -m http.server 8092` in the checkout, open `http://localhost:8092/arena_studio.html?advanced=1&soak=1` |
+| firmware | `reiserlab/LED-Display_G6_Firmware_Arena` branch `feat/sd-fastpath-2x10`, commit **`e59767e`** (2×10 bench branch; fast-forwards `arena-2x10-local`; = `75405ee` + the whole-stack review fixes) | `pio run -e teensy41-performance` → `.pio/build/teensy41-performance/firmware.hex`; Studio shows the label `e59767e5 2x10 … freerun sdfast` |
+| Studio | `reiserlab/webDisplayTools` PR #198 (v0.76) + PR #202 (v0.78, branch `claude/mode3-perf-sd`) | serve the branch locally: `python3 -m http.server 8092` in the checkout, open `http://localhost:8092/arena_studio.html?advanced=1&soak=1` |
 | bridge + simulator | same checkout | `pixi run bridge -- --log-dir soak-logs` · `pixi run sim -- --count 0 --rate 200 --seed 1 --jump-every 100 --jump-deg 90` |
 
 Flash only with the Studio disconnected (port free): `scripts/flash_bootloader_route.sh` in the firmware repo.
@@ -18,9 +18,22 @@ after a fault before the post-mortem has finished** (it drains the ring and the
 
 ## Card contents (once)
 
-Upload `soak-patterns/sine_2000f_gs16.pat` (8.1 MB, from `pixi run node scripts/make-stress-patterns.js`) through
-the Studio Console in the same Studio session that will run the soak; `frame2_h_ccw_200f` (813 KB) must already be
-on the card. `pixi run python scripts/telemetry-report.py <log>` must show `layout: contiguous` for both files.
+Upload `soak-patterns/sine_2000f_gs16.pat` (8.1 MB, from `pixi run node scripts/make-stress-patterns.js`) — either
+browser-free, `python3 scripts/sd_upload_pat.py --port … --file … --name sine_2000f_gs16.pat` in the firmware repo
+(prints the index and frame count), or through the Studio Console. `frame2_h_ccw_200f` (813 KB, index 36 on the
+bench card) must already be on the card. Patterns are numbered by sorted filename: after ANY upload re-check the
+indices you use (`GET_PATTERN_INFO` frame counts: 200 for the bar, 2000 for the sine). The first segment's report
+must show `layout: contiguous` for both files.
+
+## Two ways to run the soak
+
+- **Browser-free (what ran on 2026-09-13, recommended for unattended nights):** in the firmware repo
+  `scripts/sd_soak_campaign.sh PORT "<sine idx> 36" 286 1815 200 0800 10` — 10-min Mode-3 segments alternating the
+  two patterns with a random walk + 90° jumps, 286 Hz until 18:15 then 200 Hz until 08:00; per-segment logs
+  `soak-logs/sdstall-*-camp-*.jsonl`, one line per segment in `soak-logs/campaign-*.log`. Survives a controller
+  reboot; needs no bridge, simulator or browser. Report: `telemetry-report.py soak-logs/sdstall-*-camp-*.jsonl`.
+- **Studio path (produces run logs with per-trial verdicts, the format the course pipeline commits):** the runs
+  below.
 
 ## Runs, in order
 

From 4b0fdda3696bdccb3dbeff5196c1e4a30e4a9b74 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 15:49:50 -0400
Subject: [PATCH 28/67] =?UTF-8?q?docs(bench=20log):=2015:20=E2=80=9315:50?=
 =?UTF-8?q?=20ET=20reviews,=20fixes,=20candidate=20e59767e,=20v0.78,=2016:?=
 =?UTF-8?q?12=20switch=20plan?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/development/mode3-wedge-soak-plan.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/docs/development/mode3-wedge-soak-plan.md b/docs/development/mode3-wedge-soak-plan.md
index 6cb9e7e2..55cd0c8d 100644
--- a/docs/development/mode3-wedge-soak-plan.md
+++ b/docs/development/mode3-wedge-soak-plan.md
@@ -487,6 +487,18 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   the contiguous-seek fix removes them at identical data-read exposure; the same-index skip is irrelevant to them.
   Production build `75405ee`: bar −1 step 1.46 ms p50 / 1.8 ms max, req_age p50 1.7 ms / max 2.9 ms at 200 Hz.
   15:12 started the 2 h production run at 286 Hz on the bar (`--label prod-286hz-2h`), unattended.
+- **2026-09-13 15:20–15:50 ET — whole-stack Codex reviews + fixes (Michael: laptop stays; review, adversarial pass,
+  one hand-off document; 2 h stress then the candidate overnight).** Firmware `arena-2x10-local..75405ee` and web
+  `main..claude/mode3-perf-sd` reviewed whole (`.codex-review/report-20260913-fw-fullstack.md`, `…-web-fullstack.md`).
+  Fixed and re-reviewed (fw round 5): **firmware `e59767e`** (panels blanked at boot after a watchdog/software reset,
+  watchdog kicked inside the ISP loops, same-index skip only after a successful DAC/LUT update, exFAT refusal for the
+  legacy arm, harness backlog drain, campaign/upload script fixes; built, hex sha `578cc29e…`, NOT yet flashed) and
+  **Studio v0.78** (verdict + final drain before the export, drain problems → unknown, bridge send failure not acked,
+  FRAME read time in verdicts, link-drop = CONTROLLER_FAULT, stress gain 0.18; PR #202 updated, `pixi run test`
+  green). New docs: `mode3-reliability-handoff-2026-09-14.md` (the one hand-off document),
+  `runlog-format-review-2026-09-13.md` (≈133 MB/h raw, 35–40 gz at 200 Hz; R1 stream-gzip, R2 schema v3),
+  `consolidation-plan-2026-09-13.md`. Plan for 16:12: stop the 286 Hz run (1 h), flash `e59767e`, HIL subset, upload
+  the 8 MB sine browser-free, verify indices, start the alternating campaign (286 Hz → 18:15, 200 Hz → 21:00).
 
 ## 11. T4 as built (2026-09-12) — soak with ring-buffer logging
 

From 484621ec8bc77dbda53758fdf973cc4c640c59e3 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 16:01:19 -0400
Subject: [PATCH 29/67] =?UTF-8?q?docs:=20overnight=20soak=20test=20plan=20?=
 =?UTF-8?q?=E2=80=94=20timing,=20log=20completeness,=20recovery=20(with=20?=
 =?UTF-8?q?a=20pre-overnight=20recovery=20drill),=20untested-today=20list,?=
 =?UTF-8?q?=20morning=20report?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../overnight-soak-test-plan-2026-09-13.md    | 79 +++++++++++++++++++
 1 file changed, 79 insertions(+)
 create mode 100644 docs/development/overnight-soak-test-plan-2026-09-13.md

diff --git a/docs/development/overnight-soak-test-plan-2026-09-13.md b/docs/development/overnight-soak-test-plan-2026-09-13.md
new file mode 100644
index 00000000..6ff3a4fc
--- /dev/null
+++ b/docs/development/overnight-soak-test-plan-2026-09-13.md
@@ -0,0 +1,79 @@
+# Overnight soak — what exactly we are testing for (2026-09-13, candidate firmware `e59767e` + Studio v0.78)
+
+Three questions, each with the metric, where it comes from in the log, the pass line, and the command that checks it.
+The overnight run goes through the **Studio** (soak driver + bridge + simulator), not the browser-free harness:
+only the Studio path exercises the run-log export ordering, the per-trial verdicts, the fault detector and the
+post-mortem, which are most of what changed today. The browser-free campaign this afternoon is the pre-check.
+
+**Run:** `protocols/soak_mode3_stress.yaml` (8 MB sine + 813 KB bar alternating, 60 s trials), simulator
+`--rate 200 --seed 1 --jump-every 100 --jump-deg 90`, Studio `?advanced=1&soak=1`, File ▾ → Soak… with
+`hours: 10, gapS: 10, firstFault: halt, policy: reset-continue, maxResets: 3` — one iteration ≈ 21 min, ≈ 28
+iterations, ≈ 560 trials, ≈ 6 M frame commands.
+
+## 1. Timing is perfect
+
+| # | claim (what today's changes are supposed to guarantee) | metric | source | pass | check |
+|---|---|---|---|---|---|
+| T1 | **No controller wedge** (fw #50 fix: free-running refresh timer) | controller faults, resets, command timeouts | soak `iteration-end` events; `a` rows with `status null` | 0 faults, 0 resets, 0 timeouts | `wedge-scan.py soak-logs/` |
+| T2 | **No display freeze** (SD fast path) | SD reads > 10 ms; per-trial verdicts | `cs` kind 4 (`sd_slow`), `cf` `sd_load_us`, `trial_quality` | 0 reads > 10 ms; every trial `pass`, 0 `unknown` | `telemetry-report.py` (stalls table + per-trial table) |
+| T3 | **Request→display latency** (host 0x70 dispatch → SPI start, measured on the controller) | `req_age_us` p50 / p99 / max per file and per hour | `cf` field 9 | p99 < 5 ms, max < 10 ms at 200 Hz; no drift across the night (p50 within ±0.3 ms hour to hour) | `telemetry-report.py` per iteration file |
+| T4 | **Round trip host-side** | `a`-row `dt` p50 / p99 | `a` rows | p99 ≤ 11 ms (Codex-agreed bound from #198), no upward trend | `wedge-scan.py` RTT columns |
+| T5 | **Refresh cadence holds under load** | presented frames per second; `superseded` share; `timer_fail` | `cf` count / trial duration; `cf` field 10; `cs` kind 10 | ≈ commands with an index change; superseded < 2 % at 200 Hz; 0 `timer_fail` | `telemetry-report.py` (presentation section) |
+| T6 | **Per-read cost, both files** (no size dependence) | SD read µs by step class (+1 / −1 / small / jump), sine vs bar | `cf` `sd_load_us` | +1 ≈ 0.62 ms; random ≤ 1.5 ms p50, ≤ 1.8 ms max, sine ≈ bar | `telemetry-report.py` step-class table |
+| T7 | **Watchdog never fires** | boot count, `boot` STATE records, HEALTH `wdogFlags` "previous reset was watchdog" | ring header `boot_count` (soak `telemetry` stats), `cs` kind 1, morning `GET_HEALTH` | boot_count unchanged all night; 0 boot records; flag clear | soak events + Console health read in the morning |
+
+## 2. The log files are complete
+
+| # | claim | metric | source | pass | check |
+|---|---|---|---|---|---|
+| L1 | **Every iteration produced one committed run log** with the tail (v0.78 ordering fix) | per file: `run_metadata` (firmware label `e59767e5 … freerun sdfast`, `sd_card`, `sd_diag` 0), `stream_schema`, `trial_quality` event present, and it comes AFTER the last `cc`/`cf`/`cs` row | run-log `.jsonl(.gz)` | 28 of 28 files; `trial_quality` last among controller rows in every file | `runlog-check.py` (below) |
+| L2 | **Nothing lost in the drain** | drainer stats at iteration end: `dropped`, `gaps`, `notStored`, `errors`; `cc` accepted 0x70 count vs `a` accepted count | soak `iteration-end.telemetry`; row counts | all four 0; counts equal ±1 per file | `runlog-check.py` |
+| L3 | **Sequence continuity** across the night | ring `seq` of `cc`/`cf`/`cs` monotonic, no gap between files except at the ring's version/incarnation boundary (none expected) | rows field 3 | 0 gaps | `wedge-scan.py` `seq gaps` |
+| L4 | **Per-trial read accounting closes** | `sd_reads` (kind 13) present for every trial and ≈ index changes + 1 | `cs` kind 13, `cc` rows | every trial has it; |reads − (index changes + 1)| ≤ 2 | `telemetry-report.py` per-trial table (`reads_fw`) |
+| L5 | **Behaviour stream continuous** | FicTrac rows per trial ≈ 200 × 60 | numeric rows | ≥ 11,500 per trial | `runlog-check.py` |
+| L6 | **Size and disk** | raw MB per iteration, gz MB after commit; free disk on the bridge machine | file sizes | ≈ 45 MB raw / ≈ 12 MB gz per iteration; ≥ 5 GB free before start (2.2 TB free today) | `ls -la`, `df -h` |
+| L7 | **Verdict provenance** | `display_gap` events (if any) reference a trial and pattern that exist; `trial_quality.counts` add up to the trial count | events | consistent | `runlog-check.py` |
+
+## 3. If a showstopper happens, we recover correctly
+
+Nothing here is expected to trigger. Each row says what the log MUST show if it does, so a "recovered" night is
+judged by evidence, not by the soak still running in the morning.
+
+| # | event | expected chain | evidence that must exist | fail = |
+|---|---|---|---|---|
+| R1 | **Controller wedge** (commands time out) | fault detector trips (≥ 3 failed applies in 10) → run outcome `CONTROLLER_FAULT` → post-mortem: quiet, confirm 0xC2, typed probes, ring dump, crash report → `reset-continue`: 0x01 → reconnect → MAC verified → identity → soak continues | `iteration-end.outcome = fault`, `postmortem = recovered`; events `probe`, `telemetry_dump`, `crash_report`; the deferred commit contains `trial_quality` and the ring tail; next iteration starts within 2 min | any missing event; a second fault within `maxResets`; the soak halted with `postmortem = halt/error` |
+| R2 | **Watchdog self-reset** (link drops mid-run) | outcome `CONTROLLER_FAULT` with `fault = link_dropped` (v0.78: decided before the outcome is derived) → self-reset path → HEALTH shows previous reset = watchdog + captured PC → ring `boot` record with the pre-reset tail intact → **panels dark after the reset** (boot blank) → soak continues, `resets` += 1 | `iteration-end.postmortem = self-reset`, `crash_report` event, `cs` kind 1 (`boot`) and kind 8 (`wdog_context`), `wedge-scan` counts one reset; morning HEALTH `prevWdogPcHex` valid | outcome stored as `ABORTED_BY_USER`; no `boot` record; the arena still lit after the reset (someone must look — it is why the drill below exists) |
+| R3 | **SD stall recurs** (a read > 10 ms) | not a fault: the trial is `fail` (flagged), `display_gap` event with phase and read µs, the run and the soak continue | `display_gap`, `trial_quality.flagged_trials`, banner text in the Studio log | the trial `pass`; or the soak halting on it |
+| R4 | **Simulator or bridge hiccup** | no FicTrac frames → soak `paused` (`no-frames`), waits up to 10 min, resumes; a bridge socket failure → `rows_not_stored` coverage → trials `unknown`, never `pass` | `soak.paused` / resume events; `unknown` counts explain themselves | trials `pass` through a bridge outage |
+| R5 | **Drain falls behind** (background tab) | controller `dropped` > 0 → `seq_gap` coverage → affected trials `unknown` | `iteration-end.telemetry.dropped`, `unknown` trials with reason `seq_gap` | dropped > 0 with all trials `pass` |
+
+### Recovery drill BEFORE the overnight (≈ 15 min, on the candidate build, Studio path) — exercises R2 and R3 on purpose
+
+1. **Injected stall (R3 + the never-yet-seen Studio banner):** `await Studio.setSdDiag(3)`; run one 60 s bar trial
+   (`Studio.runOnce(false)` on the standard soak protocol); expect ≥ 1 `display_gap`, the trial `fail`, the banner
+   "⚠ stimulus quality: … flagged", `sd_layout` legacy+no-skip in the log; then `await Studio.setSdDiag(0)` and
+   confirm `Studio.sdCard.sdDiag === 0` after a reconnect (persistence check).
+2. **Injected watchdog reset (R2):** during a trial send `SET_TELEMETRY` with flags `0x31` (events on + watchdog bits
+   present + starve): the controller stops kicking and resets in ~2 s → the link drops → expect outcome
+   `CONTROLLER_FAULT` (`link_dropped`), post-mortem `self-reset`, `crash_report`, HEALTH previous-reset-was-watchdog,
+   **and the panels dark** (look at the arena) — then the Studio reconnects and the next trial runs.
+3. **Simulator kill (R4):** stop `pixi run sim` for 30 s during the soak gap; expect `paused no-frames` then resume.
+
+If any drill step fails, the overnight does not start until it is understood.
+
+## 4. Things changed today that the overnight does NOT test (flag, do not forget)
+
+- Watchdog kicks inside panel firmware (ISP) updates — needs one real panel flash with the candidate build.
+- Same-index skip after a DAC/LUT failure — needs an AO-mode trial with a disconnected DAC (bench).
+- exFAT refusal of the legacy arm — needs an exFAT card.
+- Firmware `main` port; log-format R1/R2; the deferred lists in the hand-off document §7.1.
+
+## 5. Morning report (one pass, ~10 min)
+
+```bash
+pixi run python scripts/wedge-scan.py soak-logs/                       # T1, T4, L3, R1/R2 counts
+pixi run python scripts/telemetry-report.py soak-logs/arena-log-*.jsonl*  # T2, T3, T5, T6, L4
+pixi run python scripts/runlog-check.py soak-logs/arena-log-*.jsonl*      # L1, L2, L5, L7 (to be written: ordering, counts, provenance)
+```
+Fill the tables above with numbers, then §6 of `mode3-reliability-handoff-2026-09-14.md` ("Overnight benchmark").
+Anything red → the log excerpt goes into the bench log with its ET time before anyone touches the controller.

From 646fd1ee4ae52c5d099d522aefdc45574d92a18b Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 16:02:03 -0400
Subject: [PATCH 30/67] =?UTF-8?q?scripts:=20runlog-check.py=20=E2=80=94=20?=
 =?UTF-8?q?run-log=20completeness=20checks=20for=20the=20overnight=20test?=
 =?UTF-8?q?=20plan=20(metadata,=20schema,=20trial=5Fquality=20ordering,=20?=
 =?UTF-8?q?cc=20vs=20a=20counts,=20drainer=20stats,=20FicTrac=20coverage,?=
 =?UTF-8?q?=20gap=20provenance)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 scripts/runlog-check.py | 106 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 106 insertions(+)
 create mode 100644 scripts/runlog-check.py

diff --git a/scripts/runlog-check.py b/scripts/runlog-check.py
new file mode 100644
index 00000000..a8a29782
--- /dev/null
+++ b/scripts/runlog-check.py
@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""runlog-check.py — completeness checks for Studio run logs (overnight test plan §2: L1, L2, L5, L7).
+
+    pixi run python scripts/runlog-check.py soak-logs/arena-log-*.jsonl*  [--json]
+
+Per file: run_metadata (firmware label, sd_card, sd_diag), stream_schema, trial_quality present and AFTER the last
+controller row (v0.78 export ordering), controller-accepted 0x70 count vs host-accepted `a` rows, drainer stats from
+the soak iteration-end event (dropped / gaps / notStored / errors), FicTrac rows per trial-second, display_gap ↔
+trial_quality provenance. Exit 1 when any file fails a check. Standalone (no pytest), gzip-aware.
+"""
+import gzip, json, sys
+
+def read(path):
+    op = gzip.open if path.endswith(".gz") else open
+    with op(path, "rt", encoding="utf-8") as f:
+        for n, line in enumerate(f, 1):
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                yield n, json.loads(line)
+            except Exception:
+                yield n, None
+
+def check_file(path):
+    c = {"file": path, "problems": []}
+    meta = schema = tq = None; tq_line = 0; last_ctl_line = 0
+    cc70 = a_ok = fictrac = malformed = 0
+    trials_planned = 0; iter_end = None; gaps = []; trial_secs = 0.0
+    for n, o in read(path):
+        if o is None:
+            malformed += 1; continue
+        if isinstance(o, list):
+            k = o[0]
+            if isinstance(k, (int, float)):
+                fictrac += 1
+            elif k == "a":
+                if o[4] == 0: a_ok += 1
+            elif k in ("cc", "cf", "cs"):
+                last_ctl_line = n
+                if k == "cc" and len(o) > 5 and o[4] == 0x70 and o[5] == 0: cc70 += 1
+            continue
+        ev = o.get("event") or o.get("type")
+        if ev == "run_metadata": meta = o
+        elif ev == "stream_schema": schema = o
+        elif ev == "trial_quality": tq = o; tq_line = n
+        elif ev == "display_gap": gaps.append(o)
+        elif ev == "soak" and o.get("phase") == "iteration-end": iter_end = o
+        elif ev == "runner" and o.get("phase") in ("trial_start", "condition-start"):
+            trials_planned += 1
+        elif ev == "arena_command" and isinstance(o.get("head"), str) and " 03 " in o["head"][:12]:
+            pass
+    p = c["problems"]
+    if not meta: p.append("no run_metadata")
+    else:
+        fw = (meta.get("firmware") or {}) if isinstance(meta.get("firmware"), dict) else {"label": meta.get("firmware")}
+        c["firmware"] = fw.get("label") if isinstance(fw, dict) else fw
+        c["sd_card"] = (meta.get("sd_card") or {}).get("label") if isinstance(meta.get("sd_card"), dict) else meta.get("sd_card")
+        sdd = (meta.get("sd_card") or {}).get("sd_diag") if isinstance(meta.get("sd_card"), dict) else None
+        if sdd not in (None, 0): p.append(f"sd_diag arm {sdd} recorded in run_metadata (production must be 0)")
+    if not schema: p.append("no stream_schema")
+    if not tq: p.append("no trial_quality event (export ordering / finalize did not run)")
+    else:
+        if tq_line < last_ctl_line: p.append(f"trial_quality at line {tq_line} BEFORE the last controller row at {last_ctl_line} (tail lost to the export)")
+        counts = tq.get("counts") or {}
+        c["verdicts"] = counts
+        if counts.get("unknown"): p.append(f"{counts['unknown']} trial(s) unknown (coverage) — see reasons in the event")
+        if counts.get("fail"): p.append(f"{counts['fail']} trial(s) flagged — display gaps")
+        flagged = set(tq.get("flagged_trials") or [])
+        for g in gaps:
+            if g.get("trial") not in flagged: p.append(f"display_gap for trial {g.get('trial')} but that trial is not flagged")
+    c["cc_0x70_ok"] = cc70; c["a_ok"] = a_ok
+    if cc70 and a_ok and abs(cc70 - a_ok) > 2: p.append(f"controller-accepted 0x70 {cc70} vs host-accepted {a_ok}: drain lost records")
+    if iter_end and isinstance(iter_end.get("telemetry"), dict):
+        t = iter_end["telemetry"]; c["drainer"] = {k: t.get(k) for k in ("dropped", "gaps", "notStored", "errors", "records")}
+        for k in ("dropped", "gaps", "notStored", "errors"):
+            if t.get(k): p.append(f"drainer {k} = {t[k]}")
+    c["fictrac_rows"] = fictrac; c["malformed_lines"] = malformed
+    if malformed: p.append(f"{malformed} malformed line(s)")
+    if fictrac and cc70:
+        # ≈ 200 Hz FicTrac vs 200 Hz commands during trials: the ratio should be near 1 (lower = FicTrac gaps)
+        c["fictrac_per_cmd"] = round(fictrac / cc70, 2)
+        if fictrac / cc70 < 0.8: p.append(f"FicTrac rows / commands = {fictrac / cc70:.2f} (< 0.8: behaviour stream gaps)")
+    c["ok"] = not p
+    return c
+
+def main(argv):
+    as_json = "--json" in argv
+    files = [a for a in argv if not a.startswith("--")]
+    if not files:
+        print(__doc__); return 2
+    out = [check_file(f) for f in files]
+    if as_json:
+        print(json.dumps(out, indent=1))
+    else:
+        for c in out:
+            print(("OK   " if c["ok"] else "FAIL ") + c["file"])
+            for k in ("firmware", "sd_card", "verdicts", "cc_0x70_ok", "a_ok", "drainer", "fictrac_per_cmd"):
+                if k in c: print(f"      {k}: {c[k]}")
+            for pr in c["problems"]: print("      ! " + pr)
+        n_ok = sum(1 for c in out if c["ok"])
+        print(f"\n{n_ok} / {len(out)} files complete")
+    return 0 if all(c["ok"] for c in out) else 1
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

From 3400d45831232d26fd148432c77372ab999ae0ad Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 16:02:56 -0400
Subject: [PATCH 31/67] docs+scripts: runlog-check reports ring drops as info
 (verdicts decide); test plan baseline from this morning's v0.77 log; bench
 log

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/development/mode3-wedge-soak-plan.md               | 5 +++++
 docs/development/overnight-soak-test-plan-2026-09-13.md | 8 +++++++-
 scripts/runlog-check.py                                 | 7 ++++++-
 3 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/docs/development/mode3-wedge-soak-plan.md b/docs/development/mode3-wedge-soak-plan.md
index 55cd0c8d..934370a6 100644
--- a/docs/development/mode3-wedge-soak-plan.md
+++ b/docs/development/mode3-wedge-soak-plan.md
@@ -499,6 +499,11 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   `runlog-format-review-2026-09-13.md` (≈133 MB/h raw, 35–40 gz at 200 Hz; R1 stream-gzip, R2 schema v3),
   `consolidation-plan-2026-09-13.md`. Plan for 16:12: stop the 286 Hz run (1 h), flash `e59767e`, HIL subset, upload
   the 8 MB sine browser-free, verify indices, start the alternating campaign (286 Hz → 18:15, 200 Hz → 21:00).
+- **2026-09-13 16:02 ET — overnight test plan written (`overnight-soak-test-plan-2026-09-13.md`: timing T1–T7, log
+  completeness L1–L7, recovery R1–R5 + a pre-overnight drill: injected stall via 0xCE, injected watchdog reset via
+  0xA8 flags 0x31, simulator kill). New `scripts/runlog-check.py`; on this morning's v0.77 log it FAILS as predicted:
+  `trial_quality` 359 lines before the last controller row, 22 command records lost to the export, ring dropped
+  1,157 between runs — the v0.78 fix is what the overnight must prove.**
 
 ## 11. T4 as built (2026-09-12) — soak with ring-buffer logging
 
diff --git a/docs/development/overnight-soak-test-plan-2026-09-13.md b/docs/development/overnight-soak-test-plan-2026-09-13.md
index 6ff3a4fc..f65c6eca 100644
--- a/docs/development/overnight-soak-test-plan-2026-09-13.md
+++ b/docs/development/overnight-soak-test-plan-2026-09-13.md
@@ -34,6 +34,12 @@ iterations, ≈ 560 trials, ≈ 6 M frame commands.
 | L6 | **Size and disk** | raw MB per iteration, gz MB after commit; free disk on the bridge machine | file sizes | ≈ 45 MB raw / ≈ 12 MB gz per iteration; ≥ 5 GB free before start (2.2 TB free today) | `ls -la`, `df -h` |
 | L7 | **Verdict provenance** | `display_gap` events (if any) reference a trial and pattern that exist; `trial_quality.counts` add up to the trial count | events | consistent | `runlog-check.py` |
 
+**Baseline for L1/L2 (why these checks exist):** `runlog-check.py` on this morning's v0.77 iteration
+(`arena-log-20260913-120611-713.jsonl`, firmware `3c71953`) fails it: `trial_quality` at line 923,845, last
+controller row at 924,204 (the tail was written after the export), controller-accepted 0x70 = 242,178 vs
+host-accepted 242,200 (22 records lost to that ordering), ring `dropped` 1,157 (between runs, log closed). All 20
+trials still read `pass`. The overnight on v0.78 must read `OK` on every file — that is the test of today's fix.
+
 ## 3. If a showstopper happens, we recover correctly
 
 Nothing here is expected to trigger. Each row says what the log MUST show if it does, so a "recovered" night is
@@ -73,7 +79,7 @@ If any drill step fails, the overnight does not start until it is understood.
 ```bash
 pixi run python scripts/wedge-scan.py soak-logs/                       # T1, T4, L3, R1/R2 counts
 pixi run python scripts/telemetry-report.py soak-logs/arena-log-*.jsonl*  # T2, T3, T5, T6, L4
-pixi run python scripts/runlog-check.py soak-logs/arena-log-*.jsonl*      # L1, L2, L5, L7 (to be written: ordering, counts, provenance)
+pixi run python scripts/runlog-check.py soak-logs/arena-log-*.jsonl*      # L1, L2, L5, L7 (ordering, counts, provenance)
 ```
 Fill the tables above with numbers, then §6 of `mode3-reliability-handoff-2026-09-14.md` ("Overnight benchmark").
 Anything red → the log excerpt goes into the bench log with its ET time before anyone touches the controller.
diff --git a/scripts/runlog-check.py b/scripts/runlog-check.py
index a8a29782..9be39b3c 100644
--- a/scripts/runlog-check.py
+++ b/scripts/runlog-check.py
@@ -73,8 +73,13 @@ def check_file(path):
     if cc70 and a_ok and abs(cc70 - a_ok) > 2: p.append(f"controller-accepted 0x70 {cc70} vs host-accepted {a_ok}: drain lost records")
     if iter_end and isinstance(iter_end.get("telemetry"), dict):
         t = iter_end["telemetry"]; c["drainer"] = {k: t.get(k) for k in ("dropped", "gaps", "notStored", "errors", "records")}
-        for k in ("dropped", "gaps", "notStored", "errors"):
+        # `dropped` is the controller's CUMULATIVE ring-overrun counter: records evicted while nobody drained —
+        # normally the gap between runs (log closed → poller paused → 64 KiB ring full in ~8 s). It is a
+        # problem only when it happens inside a trial, which trial-quality records as a `ring_overrun`
+        # coverage gap (→ unknown). So: info here, verdicts decide.
+        for k in ("gaps", "notStored", "errors"):
             if t.get(k): p.append(f"drainer {k} = {t[k]}")
+        if t.get("dropped"): c["note"] = f"ring dropped {t['dropped']} records during the file (between runs unless a trial is unknown)"
     c["fictrac_rows"] = fictrac; c["malformed_lines"] = malformed
     if malformed: p.append(f"{malformed} malformed line(s)")
     if fictrac and cc70:

From 6fc19e8a8345ea3b26391ae20bee4a8386599e6b Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 16:14:14 -0400
Subject: [PATCH 32/67] =?UTF-8?q?docs(bench=20log):=2016:12=20switch=20?=
 =?UTF-8?q?=E2=80=94=201=20h/286=20Hz=20result=20(1.04=20M=20commands,=200?=
 =?UTF-8?q?=20stalls),=20e59767e=20flashed,=20HIL=20open=20item,=20sine=20?=
 =?UTF-8?q?uploaded=20as=20idx=2046=20(contiguous),=20campaign=20started?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/development/mode3-wedge-soak-plan.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/docs/development/mode3-wedge-soak-plan.md b/docs/development/mode3-wedge-soak-plan.md
index 934370a6..cd2910fb 100644
--- a/docs/development/mode3-wedge-soak-plan.md
+++ b/docs/development/mode3-wedge-soak-plan.md
@@ -504,6 +504,14 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   0xA8 flags 0x31, simulator kill). New `scripts/runlog-check.py`; on this morning's v0.77 log it FAILS as predicted:
   `trial_quality` 359 lines before the last controller row, 22 command records lost to the export, ring dropped
   1,157 between runs — the v0.78 fix is what the overnight must prove.**
+- **2026-09-13 16:12 ET — switch.** 1 h production run on `75405ee`, bar only, **286 Hz: 1,036,992 commands, 788,704
+  reads, 0 reads > 10 ms (worst 1.8 ms), req_age p50 1.7 / max 3.0 ms, 0.76 reads/cmd, capture valid, usable.**
+  Flashed **`e59767e`** (bootloader route, 7 s). HIL subset (`-x`, no `--pat`): `test_firmware_version` passed;
+  `test_health.py::test_loop_max_1s_window_is_populated` FAILED (`loop_max_1s_us == 0` at ~3 s uptime) — open item:
+  re-run at the drill, decide flake vs regression before the overnight. Uploaded `sine_2000f_gs16.pat` browser-free:
+  **index 46, 2000 frames, 8.1 MB in 1.4 s (5.7 MB/s)**; verified idx 36 = 200 frames, idx 46 = 2000. Campaign started
+  16:12:53 (`sd_soak_campaign.sh … "46 36" 286 1815 200 2100 10`, detached under caffeinate): segment 1 = sine at
+  286 Hz, `sd_layout` code 1 → **contiguous**, 8 sectors/cluster.
 
 ## 11. T4 as built (2026-09-12) — soak with ring-buffer logging
 

From c14ac61efad1d6b6c54fe538d236d7a21a627230 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 16:20:17 -0400
Subject: [PATCH 33/67] =?UTF-8?q?docs:=20lab=20test=20day=20on=20Windows?=
 =?UTF-8?q?=20(no=20Claude)=20=E2=80=94=20install,=20flash,=20card,=20smok?=
 =?UTF-8?q?e,=20five=20tests=20with=20what=20to=20look=20for,=20analysis,?=
 =?UTF-8?q?=20cross-machine=20timing=20benchmark=20table,=20browser-free?=
 =?UTF-8?q?=20fallback?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../lab-test-day-windows-2026-09-14.md        | 103 ++++++++++++++++++
 .../mode3-reliability-handoff-2026-09-14.md   |   2 +-
 docs/development/soak-handoff-2026-09-14.md   |   2 +
 3 files changed, 106 insertions(+), 1 deletion(-)
 create mode 100644 docs/development/lab-test-day-windows-2026-09-14.md

diff --git a/docs/development/lab-test-day-windows-2026-09-14.md b/docs/development/lab-test-day-windows-2026-09-14.md
new file mode 100644
index 00000000..3facdc23
--- /dev/null
+++ b/docs/development/lab-test-day-windows-2026-09-14.md
@@ -0,0 +1,103 @@
+# Lab test day (Windows PC, no Claude) — Mode-3 reliability candidate, 2026-09-14
+
+For whoever runs the bench tomorrow morning. Everything below is a command to type or a thing to look at, in order.
+Budget: ~2.5 h including a 1 h soak. Background and the full pass criteria: `overnight-soak-test-plan-2026-09-13.md`;
+what changed and why: `mode3-reliability-handoff-2026-09-14.md`.
+
+## 0. Before you start (Michael)
+
+- [ ] Firmware branch `feat/sd-fastpath-2x10` pushed to GitHub (it is still local on Michael's machine) — the lab
+      builds the SAME identity from it (`e59767e5` is compiled in from git).
+- [ ] The CSHL 2×10 controller + its bench card (patterns 36 = bar, 46 = sine already on it) travel to the lab PC,
+      or plan 10 extra minutes to upload the two patterns (step 3).
+- [ ] Overnight results from the Mac pasted into §6 of the hand-off document (the reference numbers for §5 below).
+
+## 1. Install (once, ~15 min)
+
+```powershell
+git clone https://github.com/reiserlab/webDisplayTools.git; cd webDisplayTools; git checkout claude/mode3-perf-sd
+pixi install                              # Node + Python + websockets (needs pixi: https://pixi.sh)
+cd ..; git clone https://github.com/reiserlab/LED-Display_G6_Firmware_Arena.git; cd LED-Display_G6_Firmware_Arena
+git checkout feat/sd-fastpath-2x10
+pip install platformio pyserial          # or the PlatformIO VS Code extension; Teensy Loader comes with PlatformIO
+```
+Chrome or Edge (Web Serial). Use **PowerShell**, not Git Bash, for anything with times (Git Bash prints UTC labelled ET).
+
+## 2. Flash and identify (10 min)
+
+```powershell
+pio run -e teensy41-performance -t upload --upload-port COM5      # find COMx in Device Manager: "USB Serial Device"
+```
+Windows gotchas (fw PR #49 notes): the **first upload attempt often fails — run it again**; the arena must be powered;
+if the port vanishes, unplug/replug once. Then in Chrome: `pixi run python -m http.server 8092` in the webDisplayTools
+checkout → `http://localhost:8092/arena_studio.html?advanced=1&soak=1` → **Connect** → pick the Teensy port.
+**Look for**, in the Console log: `firmware e59767e5 2x10 2026-09-13 feat/sd-fastpath-2x10 freerun sdfast` and an
+`sd card: … SD8GB … FAT32 4 KiB clusters` line. If the label is not `e59767e5`, stop: wrong build.
+
+## 3. Card check (2 min, or 10 with uploads)
+
+Console → the SD listing must show `frame2_h_ccw_200f` (200 frames) and `sine_2000f_gs16` (2000 frames). If not:
+`pixi run node scripts/make-stress-patterns.js` writes both into `soak-patterns\`; upload them from the Console
+(SD upload) with the display stopped. Indices are by sorted filename; the protocol resolves names, so numbers don't matter.
+
+## 4. Bridge, simulator, one smoke run (10 min)
+
+Two PowerShell windows in the webDisplayTools checkout:
+```powershell
+pixi run bridge -- --log-dir soak-logs
+pixi run sim -- --count 0 --rate 200 --seed 1 --jump-every 100 --jump-deg 90
+```
+Studio: File ▾ → Open → `protocols/soak_mode3_stress.yaml`; rig `cshl_g6_2x10_ball`; Run (Test is fine).
+**Look for** during the 21 min: the Console log line `telemetry poller … running`; at the end the banner
+`stimulus quality: 20 pass · 0 flagged · 0 unknown`. Anything flagged or unknown → keep the log, note the time, go on.
+
+## 5. The tests (in order) and what each must show
+
+| # | do | look for (Studio log / files) | pass |
+|---|---|---|---|
+| A | **Soak, 3 iterations (~1 h):** File ▾ → Soak…, `iterations 3, gap 10 s, first fault halt, then reset-continue, max resets 3` | `soak ended (iterations) after 3 iteration(s), 0 fault(s), 0 reset(s)`; every iteration banner `… pass · 0 flagged · 0 unknown` | 0 faults, 0 resets, 60 of 60 trials pass |
+| B | **Injected stall** (checks the flagging path): in the browser console `await Studio.setSdDiag(3)`, run ONE Test run of the stress protocol, then `await Studio.setSdDiag(0)` | during the run: `display gap NN ms (sd_slow, body) in trial …` lines; at the end `⚠ stimulus quality: … flagged`; after `setSdDiag(0)`, Console identity shows `sd diag 0` | at least one trial flagged; the soak did NOT stop; switches back to 0 |
+| C | **Simulator kill:** during a Soak (start a 2-iteration soak), close the sim window for 30 s, restart it | `soak: no FicTrac frames — waiting for the simulator`, then the next iteration starts | soak resumes by itself; no fault counted |
+| D | **Link drop:** during a trial pull the controller's USB cable, wait 5 s, plug it back | `run ended by a link drop … treating as a controller event`; post-mortem lines (`confirm`, `probe`, `reconnect`); the run's outcome `CONTROLLER_FAULT`; the arena goes **dark** on replug and stays dark until the next trial | reconnects without a page reload; next iteration runs |
+| E | **Panel firmware update still works with the watchdog** (5 min, only if a spare panel/known-good image is at hand): Console → Firmware → program one panel | progress completes; no controller reboot mid-update (the Console would show a disconnect) | update completes |
+
+Never power-cycle the controller after something odd: the evidence is in RAM until the Studio's post-mortem has read it.
+
+## 6. Analysis (5 min) — all three must be clean
+
+```powershell
+pixi run python scripts/wedge-scan.py soak-logs\
+pixi run python scripts/runlog-check.py soak-logs\arena-log-*.jsonl*
+pixi run python scripts/telemetry-report.py soak-logs\arena-log-*.jsonl*
+```
+- `wedge-scan`: **0 faults, 0 resets**, RTT p99 ≤ 11 ms.
+- `runlog-check`: every file `OK` (metadata, `trial_quality` after the last controller row, command counts equal,
+  drainer gaps/notStored/errors 0). The test-B file is allowed `flagged`; test D's file must say `CONTROLLER_FAULT`.
+- `telemetry-report`: **0 SD reads > 10 ms** outside test B; `req_age_us` max < 10 ms; per-read cost ≈ 0.62 ms (+1) /
+  ≤ 1.8 ms (random) for BOTH patterns; every trial's `layout: contiguous`.
+
+Zip `soak-logs\` and post the three outputs (and anything red, with the local time) to webDisplayTools #201 (or #197
+for a wedge, firmware #54 for an SD stall). Do not post to firmware #50 or PJRC.
+
+## 7. Cross-machine timing benchmark (macOS bench vs lab PC) — small, but keep it
+
+Same controller, same card, same protocol, same simulator flags, three iterations on each machine. The controller-side
+numbers must NOT change with the host; the host-side ones may — that difference is the benchmark.
+
+| metric | source | macOS (2026-09-13 night) | Windows lab PC | expect |
+|---|---|---|---|---|
+| host round trip `a`-row dt p50 / p99 | `wedge-scan.py` | fill in from the overnight | | Windows USB-CDC often +1–3 ms; p99 must stay ≤ 11 ms |
+| request→display `req_age_us` p50 / p99 / max | `telemetry-report.py` | 1.7 / 2.6 / ~3 ms | | same on both (controller-side) |
+| SD read cost +1 / random (p50, max) | `telemetry-report.py` | 0.62 / 1.46 ms, max 1.8 | | same on both |
+| drainer dropped / gaps / notStored | `runlog-check.py` (`drainer:`) | | | 0 / 0 / 0; Chrome background-tab throttling is the usual culprit — keep the Studio tab visible |
+| FicTrac rows per command | `runlog-check.py` (`fictrac_per_cmd`) | ≈ 1.0 during trials | | ≈ 1.0 |
+| commands accepted per iteration | `runlog-check.py` (`a_ok`) | ≈ 240 k | | within 2 % |
+| trials pass / flagged / unknown | banner / `trial_quality` | 20 / 0 / 0 | | 20 / 0 / 0 |
+
+Write the Windows column into this file and commit it on the branch (no Prettier on HTML; this is Markdown).
+
+## 8. Optional browser-free path (if the Studio misbehaves on the PC)
+
+In the firmware checkout: `python scripts\sd_stall_test.py --port COM5 --pattern 46 --hz 200 --minutes 10 --sd-diag 0`
+(then `--pattern 36`). Same analysis with `telemetry-report.py` on `soak-logs\sdstall-*.jsonl`. This tests the
+controller and card, not the Studio.
diff --git a/docs/development/mode3-reliability-handoff-2026-09-14.md b/docs/development/mode3-reliability-handoff-2026-09-14.md
index 535ac9a4..b70c9325 100644
--- a/docs/development/mode3-reliability-handoff-2026-09-14.md
+++ b/docs/development/mode3-reliability-handoff-2026-09-14.md
@@ -12,7 +12,7 @@ numbers given); this is the narrative and the map.
 | B | **display freezes of 30–90 ms** every ~24.5k frame reads of a large pattern (fw #54) | firmware FAT access: SdFat re-walked the file's cluster chain on backward seeks and looked up the next cluster inside every read that crossed a 4 KB cluster boundary; those FAT-sector reads hammered one physical block of the card until its read-disturb maintenance paused the card | **contiguous O(1) seeks** (`FsFile` + `contiguousRange()`): the FAT is read once at pattern open and never during a trial | 4-arm causal test 2026-09-13: FAT touched → stalls at the old spacing; FAT untouched, same read count → 0; production: 0 in 482k + 72k commands + 1 h at 286 Hz |
 
 **Candidate build:** firmware `feat/sd-fastpath-2x10` @ `75405ee` (label `… freerun sdfast`, 0xCB flags `0x7C`);
-Studio v0.77 (PRs #198 + #202). **Run sheet for the bench:** `soak-handoff-2026-09-14.md`.
+Studio v0.77 (PRs #198 + #202). **Run sheet for the bench:** `soak-handoff-2026-09-14.md`; **lab test day on Windows (no Claude):** `lab-test-day-windows-2026-09-14.md`; **what the overnight tests:** `overnight-soak-test-plan-2026-09-13.md`.
 
 ---
 
diff --git a/docs/development/soak-handoff-2026-09-14.md b/docs/development/soak-handoff-2026-09-14.md
index f52808a5..68afd07e 100644
--- a/docs/development/soak-handoff-2026-09-14.md
+++ b/docs/development/soak-handoff-2026-09-14.md
@@ -1,5 +1,7 @@
 # Overnight soak hand-off — consolidated Mode-3 build (2026-09-14)
 
+Lab morning on a Windows PC, step by step, no Claude: `lab-test-day-windows-2026-09-14.md`.
+
 One page. Everything built since Friday 2026-09-11 is under test at once: controller health (0xCA/0xCB), the
 telemetry ring, the hardware watchdog, the free-running refresh timer (the fw #50 "ISR guard"), and the SD fast
 path. If the overnight run is clean, these are the branches to merge.

From d87452437d4399149f51734530c3acd8922e3476 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 16:23:21 -0400
Subject: [PATCH 34/67] =?UTF-8?q?docs(bench=20log):=20segment=201=20?=
 =?UTF-8?q?=E2=80=94=208=20MB=20sine=20at=20286=20Hz=20on=20e59767e:=200?=
 =?UTF-8?q?=20stalls,=20random=20read=201.39=20ms=20p50=20/=201.8=20ms=20m?=
 =?UTF-8?q?ax,=20no=20size=20dependence?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/development/mode3-wedge-soak-plan.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/development/mode3-wedge-soak-plan.md b/docs/development/mode3-wedge-soak-plan.md
index cd2910fb..a7dcbea9 100644
--- a/docs/development/mode3-wedge-soak-plan.md
+++ b/docs/development/mode3-wedge-soak-plan.md
@@ -512,6 +512,10 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   **index 46, 2000 frames, 8.1 MB in 1.4 s (5.7 MB/s)**; verified idx 36 = 200 frames, idx 46 = 2000. Campaign started
   16:12:53 (`sd_soak_campaign.sh … "46 36" 286 1815 200 2100 10`, detached under caffeinate): segment 1 = sine at
   286 Hz, `sd_layout` code 1 → **contiguous**, 8 sectors/cluster.
+- **2026-09-13 16:23 ET — campaign segment 1, 8 MB sine (idx 46) at 286 Hz on `e59767e`, 10 min: 171,482 commands,
+  130,758 reads, 0 reads > 10 ms (worst 1.8 ms), random-step read p50 1.39 ms — the same as the 813 KB bar —
+  req_age p50 1.67 / max 2.94 ms, contiguous, usable.** First evidence that the fast path has no size dependence
+  (2000-entry chain, 2 MB seeks). Segment 2 = bar at 286 Hz.
 
 ## 11. T4 as built (2026-09-12) — soak with ring-buffer logging
 

From 0c4cfeffe0474c94bdbe5089abe43a8e05f833e8 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 16:30:20 -0400
Subject: [PATCH 35/67] docs: course dashboard readiness, old course protocols
 on the candidate (p3 as lab test F), log-parsing rules for external readers

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../lab-test-day-windows-2026-09-14.md        |  1 +
 .../mode3-reliability-handoff-2026-09-14.md   | 39 +++++++++++++++++++
 2 files changed, 40 insertions(+)

diff --git a/docs/development/lab-test-day-windows-2026-09-14.md b/docs/development/lab-test-day-windows-2026-09-14.md
index 3facdc23..c62bc4a2 100644
--- a/docs/development/lab-test-day-windows-2026-09-14.md
+++ b/docs/development/lab-test-day-windows-2026-09-14.md
@@ -59,6 +59,7 @@ Studio: File ▾ → Open → `protocols/soak_mode3_stress.yaml`; rig `cshl_g6_2
 | B | **Injected stall** (checks the flagging path): in the browser console `await Studio.setSdDiag(3)`, run ONE Test run of the stress protocol, then `await Studio.setSdDiag(0)` | during the run: `display gap NN ms (sd_slow, body) in trial …` lines; at the end `⚠ stimulus quality: … flagged`; after `setSdDiag(0)`, Console identity shows `sd diag 0` | at least one trial flagged; the soak did NOT stop; switches back to 0 |
 | C | **Simulator kill:** during a Soak (start a 2-iteration soak), close the sim window for 30 s, restart it | `soak: no FicTrac frames — waiting for the simulator`, then the next iteration starts | soak resumes by itself; no fault counted |
 | D | **Link drop:** during a trial pull the controller's USB cable, wait 5 s, plug it back | `run ended by a link drop … treating as a controller event`; post-mortem lines (`confirm`, `probe`, `reconnect`); the run's outcome `CONTROLLER_FAULT`; the arena goes **dark** on replug and stays dark until the next trial | reconnects without a page reload; next iteration runs |
+| F | **An old course protocol runs unchanged:** sign in to the course repo (Settings), open rig1 `p3-heisenberg-ts-full.yaml`, run it once as a Test run (simulator running) | it runs to the end exactly as in July; banner `… pass`; the run log has `trial_quality` and `run_metadata.firmware` = `e59767e5 …` | completes, all trials pass |
 | E | **Panel firmware update still works with the watchdog** (5 min, only if a spare panel/known-good image is at hand): Console → Firmware → program one panel | progress completes; no controller reboot mid-update (the Console would show a disconnect) | update completes |
 
 Never power-cycle the controller after something odd: the evidence is in RAM until the Studio's post-mortem has read it.
diff --git a/docs/development/mode3-reliability-handoff-2026-09-14.md b/docs/development/mode3-reliability-handoff-2026-09-14.md
index b70c9325..6279b8fc 100644
--- a/docs/development/mode3-reliability-handoff-2026-09-14.md
+++ b/docs/development/mode3-reliability-handoff-2026-09-14.md
@@ -168,6 +168,45 @@ per interval; report truncation → unknown and bounded accumulators; controller
 `arena-link` write-timeout race; bridge rows-capability negotiation. None affects tonight's benchmark; all are
 recorded so the next session starts from the list, not from a re-review.
 
+## 7.2 Course dashboard, old course protocols, log parsing (Michael's questions, 2026-09-13 16:40 ET)
+
+**Course dashboard (`dashboard/data-browser`).** Nothing new is required for it to keep working: it already inflates
+`.jsonl.gz`, normalizes `behavior_v2` through the vendored `runlog-format.js`, and (on this branch, 3 lines in
+`analysis-core.js` + a test) skips every string-tagged array row, which is what the controller streams are. So it
+reads the new logs as soon as PR #198 merges; today's `main` build would try to parse `cc`/`cf`/`cs` rows as FicTrac
+frames and reject them (they fail the numeric-column check, so the run still loads, with warnings). What it does not
+yet DO with the new data — optional, one small PR: show `run_metadata.firmware` and `.sd_card` in the run table,
+the per-trial `trial_quality` counts as a badge, and `display_gap` markers on the trace. The run-log index builder
+(`scripts/build-runlog-index.py`, bookends only) is unaffected; adding `firmware` and the quality counts to
+`index.json` is the same small PR.
+
+**Old course protocols (p0–p3, `reiserlab/cshl-2026-course/protocols/`).** Expected to run unchanged on the candidate:
+every firmware change is additive and gated on new flag bits; TRIAL_PARAMS, Mode 2/3, `ledDrive`, `led_activation`,
+duty, the FicTrac plugin path and the run-log contract are untouched; the Studio's protocol handling did not change
+between v0.75 and v0.78 except for the soak driver and the verdicts. p3 (`p3-heisenberg-ts-full`: Mode 2 baseline,
+Mode 3 closed loop with gain −1.8, `ledDrive`, `led_activation`) exercises exactly the paths that changed underneath
+(0x70 under the free-running timer, SD reads on the fast path). What is different for them: (a) a large pattern now
+costs 1.4 ms per random read instead of 2 ms with no stall risk; (b) every trial gets a pass/flagged/unknown verdict
+in its log; (c) a wedge would now end the run as `CONTROLLER_FAULT` and auto-commit instead of hanging. Only
+precondition: pattern files contiguous on the card (uploads through the Studio are; `sd_layout` reports it).
+**Verification is one run of p3 on the candidate** — added as test F in `lab-test-day-windows-2026-09-14.md`.
+
+**Parsing the logs (anyone's reader, incl. MATLAB/Python course analysis).** Rules, cumulative since v0.72:
+1. A file may be gzip (`.jsonl.gz`); inflate on the 1f 8b magic.
+2. One JSON value per line: objects are events (`type`/`event`); **arrays are streams**. An array whose first element
+   is a **number** is a FicTrac behaviour sample `[ms, fc, idx, ft, x, y, hd]` (columns named once in `frame_schema`).
+   An array whose first element is a **string** is another stream: `"a"` = host arena-command echo
+   `[t_off, dt, hex, status, rx_off(, error)]`; `"cc"/"cf"/"cs"` = controller command / frame / state records
+   (columns in `stream_schema`; `cf` has 8 or 11 fields; `cs` kinds 1–14 named in the schema's `kinds`). Unknown
+   string tags: skip, never treat as behaviour.
+3. New events since v0.77/78 (all optional): `trial_quality` (per-trial verdicts, once per run, after the last
+   controller row), `display_gap` (one per gap), `sd_diag`, `telemetry_dump`, `crash_report`, `probe`; new
+   `run_metadata` keys `firmware`, `sd_card`, `sd_diag`, `gap_threshold_ms`.
+4. Reference implementations: `js/runlog-format.js` (`readRunlogText`, `createNormalizer`) for JS,
+   `scripts/telemetry-report.py` / `scripts/runlog-check.py` for Python. Layout and byte budget:
+   `runlog-format-review-2026-09-13.md`. A MATLAB reader in maDisplayTools, if one exists, needs rule 2 (string-tagged
+   arrays are not behaviour) — the only change that can break an old parser.
+
 ## 8. Where things live
 
 - Firmware: `src/Health.*`, `src/Telemetry.*`, `src/Watchdog*`/`Health` v2 fields, `src/SpiManager.*` (timer),

From 73e72c69974931ba89ca6bc3a6dd8a7beefa0aa9 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 18:02:48 -0400
Subject: [PATCH 36/67] =?UTF-8?q?docs:=20firmware=20pushed=20=E2=80=94=20P?=
 =?UTF-8?q?R=20#55=20is=20the=20merge=20candidate;=20Studio=20merge=20to?=
 =?UTF-8?q?=20main=20in=20the=20morning=20(Michael's=20decisions=2017:30?=
 =?UTF-8?q?=20ET)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/development/consolidation-plan-2026-09-13.md   | 10 ++++++----
 docs/development/lab-test-day-windows-2026-09-14.md |  7 +++++--
 docs/development/mode3-wedge-soak-plan.md           |  5 +++++
 3 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/docs/development/consolidation-plan-2026-09-13.md b/docs/development/consolidation-plan-2026-09-13.md
index cdf36728..93ba7e06 100644
--- a/docs/development/consolidation-plan-2026-09-13.md
+++ b/docs/development/consolidation-plan-2026-09-13.md
@@ -32,10 +32,12 @@ review report; (c) **one detailed hand-off document** explaining all the changes
 - **Keep `SET_SD_DIAG` 0xCE in production?** Recommend **keep** (gated on flag bit 6, off at boot, restored by the
   harness) but add a Studio banner when the readback is non-zero at connect (S-1 below). Alternative: compile it out
   (`fw_sd_diag = false`) for the release build — loses the lab's ability to reproduce the stall on demand.
-- **Merge target for firmware:** PR against `arena-2x10-local` now (fast-forward, what the CSHL controllers run);
-  port to `main` (per-board `-DARENA_HW_*` after #48) as a follow-up PR that supersedes #53. Needs your go to push.
-- **Web:** merge #198 then #202 as they are (stack), or squash into one PR? Recommend as they are — the commit history
-  is the review trail; release notes v0.76/v0.77 are the reading guide.
+- **Merge target for firmware — DECIDED (Michael 17:30 ET):** the branch IS the merge candidate; pushed, PR #55
+  against `arena-2x10-local` (fast-forward); the lab flashes from the branch; merge after the lab day; port to
+  `main` (per-board `-DARENA_HW_*` after #48) as a follow-up PR that supersedes #53.
+- **Web — DECIDED (Michael 17:30 ET):** merge #198 then #202 to `main` as they are, without a separate review, first
+  thing tomorrow morning after a clean overnight (the v0.78 export-ordering code's first bench exercise is the
+  night); the lab tests from main; revert is one command if anything is wrong.
 
 ## 4. Small changes proposed (only these unless the reviews find more)
 
diff --git a/docs/development/lab-test-day-windows-2026-09-14.md b/docs/development/lab-test-day-windows-2026-09-14.md
index c62bc4a2..632bb426 100644
--- a/docs/development/lab-test-day-windows-2026-09-14.md
+++ b/docs/development/lab-test-day-windows-2026-09-14.md
@@ -6,11 +6,14 @@ what changed and why: `mode3-reliability-handoff-2026-09-14.md`.
 
 ## 0. Before you start (Michael)
 
-- [ ] Firmware branch `feat/sd-fastpath-2x10` pushed to GitHub (it is still local on Michael's machine) — the lab
-      builds the SAME identity from it (`e59767e5` is compiled in from git).
+- [x] Firmware branch `feat/sd-fastpath-2x10` pushed (17:35 ET) — merge-candidate PR
+      [reiserlab/LED-Display_G6_Firmware_Arena#55](https://github.com/reiserlab/LED-Display_G6_Firmware_Arena/pull/55);
+      the lab builds the SAME identity from it (`e59767e5` is compiled in from git).
 - [ ] The CSHL 2×10 controller + its bench card (patterns 36 = bar, 46 = sine already on it) travel to the lab PC,
       or plan 10 extra minutes to upload the two patterns (step 3).
 - [ ] Overnight results from the Mac pasted into §6 of the hand-off document (the reference numbers for §5 below).
+- [ ] Studio: PRs #198 + #202 merged to `main` first thing in the morning if the night is clean (Michael 17:30 ET:
+      no separate review; the lab tests main; revert if anything is wrong). Until then the lab can serve the branch.
 
 ## 1. Install (once, ~15 min)
 
diff --git a/docs/development/mode3-wedge-soak-plan.md b/docs/development/mode3-wedge-soak-plan.md
index a7dcbea9..66f0b119 100644
--- a/docs/development/mode3-wedge-soak-plan.md
+++ b/docs/development/mode3-wedge-soak-plan.md
@@ -516,6 +516,11 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   130,758 reads, 0 reads > 10 ms (worst 1.8 ms), random-step read p50 1.39 ms — the same as the 813 KB bar —
   req_age p50 1.67 / max 2.94 ms, contiguous, usable.** First evidence that the fast path has no size dependence
   (2000-entry chain, 2 MB seeks). Segment 2 = bar at 286 Hz.
+- **2026-09-13 17:27 ET — segments 1–7 (286 Hz, sine/bar alternating) all clean:** ~171.5k commands each, 0 reads
+  > 10 ms, worst 1.8 ms, random read p50 1.39 (sine) / 1.46 (bar) ms, req_age max 2.9–3.0 ms, 0 reboots.
+- **2026-09-13 17:35 ET — hand-off paths decided (Michael):** firmware stays on `feat/sd-fastpath-2x10` as the merge
+  candidate — PUSHED, PR reiserlab/LED-Display_G6_Firmware_Arena#55 against `arena-2x10-local`; Studio #198 + #202
+  go to `main` tomorrow morning without a separate review once the night is clean (revert if needed).
 
 ## 11. T4 as built (2026-09-12) — soak with ring-buffer logging
 

From c34f8f170cf435c76a85b40039d591b73e13b620 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 18:17:31 -0400
Subject: [PATCH 37/67] =?UTF-8?q?docs(bench=20log):=20stress=20phase=20com?=
 =?UTF-8?q?plete;=20one=2019.4=20ms=20body-phase=20read=20on=20the=208=20M?=
 =?UTF-8?q?B=20sine=20(single=20event,=20no=20driver=20error)=20=E2=80=94?=
 =?UTF-8?q?=20the=20watch=20item?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/development/mode3-wedge-soak-plan.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/development/mode3-wedge-soak-plan.md b/docs/development/mode3-wedge-soak-plan.md
index 66f0b119..1104da41 100644
--- a/docs/development/mode3-wedge-soak-plan.md
+++ b/docs/development/mode3-wedge-soak-plan.md
@@ -521,6 +521,13 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
 - **2026-09-13 17:35 ET — hand-off paths decided (Michael):** firmware stays on `feat/sd-fastpath-2x10` as the merge
   candidate — PUSHED, PR reiserlab/LED-Display_G6_Firmware_Arena#55 against `arena-2x10-local`; Studio #198 + #202
   go to `main` tomorrow morning without a separate review once the night is clean (revert if needed).
+- **2026-09-13 18:16 ET — stress phase done (13 segments at 286 Hz, ~2.2 M commands, ~1.7 M reads); ONE slow read.**
+  Segment 9 (`sdstall-20260913-173259-camp-286-p46`, 8 MB sine), 472 s in: frame 47 → 44 (−3 step), **body phase,
+  19.4 ms, `sd_slow_ctx` 0/0 (no driver error), single event (no cluster), next read 0.62 ms; req_age max 19.6 ms.**
+  Not the FAT signature (contiguous file, no FAT access, not quantised 23/33/41…, not clustered) — the exact
+  "phase body on the 8 MB file" watch item from the campaign plan (a data-region event?). Rate so far: 1 in
+  ~2.5 M fast-path reads today; below Michael's 30 ms "detectable" line, above the 10 ms flag line → that trial would
+  be *flagged*. Night phase (200 Hz) started 18:16; watching for recurrence and whether it stays on the 8 MB file.
 
 ## 11. T4 as built (2026-09-12) — soak with ring-buffer logging
 

From 8263c12bd4af13fd29f317dc0722c42b39974b29 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 18:32:45 -0400
Subject: [PATCH 38/67] =?UTF-8?q?docs:=20archive=20the=20day's=20working?=
 =?UTF-8?q?=20documents=20under=20docs/development/archive/mode3-2026-09?=
 =?UTF-8?q?=20(living=20set:=20hand-off,=20lab=20test=20day,=20overnight?=
 =?UTF-8?q?=20test=20plan,=20log-format=20review,=20bench=20log);=20ship?=
 =?UTF-8?q?=20plan=20=C2=A77.3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 CLAUDE.md                                     |  2 +-
 .../archive/mode3-2026-09/README.md           |  9 +++++++
 .../consolidation-plan-2026-09-13.md          |  0
 .../mode3-perf-handover-2026-09-13.md         |  0
 .../sd-read-jitter-2026-09-13.md              |  0
 .../sd-stall-causal-test-plan-2026-09-13.md   |  0
 .../mode3-2026-09}/soak-handoff-2026-09-14.md |  0
 .../development/arena-studio-release-notes.md |  2 +-
 .../mode3-reliability-handoff-2026-09-14.md   | 24 +++++++++++++++----
 docs/development/mode3-wedge-soak-plan.md     | 14 +++++------
 .../telemetry-review-handoff-2026-09-13.md    |  8 +++----
 11 files changed, 41 insertions(+), 18 deletions(-)
 create mode 100644 docs/development/archive/mode3-2026-09/README.md
 rename docs/development/{ => archive/mode3-2026-09}/consolidation-plan-2026-09-13.md (100%)
 rename docs/development/{ => archive/mode3-2026-09}/mode3-perf-handover-2026-09-13.md (100%)
 rename docs/development/{ => archive/mode3-2026-09}/sd-read-jitter-2026-09-13.md (100%)
 rename docs/development/{ => archive/mode3-2026-09}/sd-stall-causal-test-plan-2026-09-13.md (100%)
 rename docs/development/{ => archive/mode3-2026-09}/soak-handoff-2026-09-14.md (100%)

diff --git a/CLAUDE.md b/CLAUDE.md
index f6eeaf82..eab9177b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -356,7 +356,7 @@ fix flows to every page automatically; two hand-written HTML pages never will.
   `display_gap` + `trial_quality` run-log events; the Studio flags, never auto-excludes. Offline analysis:
   `scripts/telemetry-report.py` (also reads the firmware repo's `scripts/sd_stall_test.py` logs). The card stalls
   themselves are card-internal (read-count maintenance, ~24.5k reads of a large file); see
-  `docs/development/sd-read-jitter-2026-09-13.md`.
+  `docs/development/archive/mode3-2026-09/sd-read-jitter-2026-09-13.md`.
 - Bump the footer version/timestamp on every edit; never Prettier the HTML.
 
 - **Telemetry ring — four rules from the 2026-09-12 Codex review (all tested):** (1) the ONLY gate
diff --git a/docs/development/archive/mode3-2026-09/README.md b/docs/development/archive/mode3-2026-09/README.md
new file mode 100644
index 00000000..418f8d9c
--- /dev/null
+++ b/docs/development/archive/mode3-2026-09/README.md
@@ -0,0 +1,9 @@
+# Archive — Mode-3 reliability working documents, 2026-09-13
+
+Superseded by `docs/development/mode3-reliability-handoff-2026-09-14.md` (the one hand-off document). Kept for history:
+
+- `sd-read-jitter-2026-09-13.md` — the SD-stall evidence write-up and the H-FAT explanation with diagrams (long).
+- `sd-stall-causal-test-plan-2026-09-13.md` — the four-arm causal test (result: H-FAT confirmed 15:11 ET) and the campaign design.
+- `consolidation-plan-2026-09-13.md` — review gates, decisions and small changes before the hand-off (all decided 17:30 ET).
+- `soak-handoff-2026-09-14.md` — the first run sheet; folded into `lab-test-day-windows-2026-09-14.md`.
+- `mode3-perf-handover-2026-09-13.md` — the session brief this work started from.
diff --git a/docs/development/consolidation-plan-2026-09-13.md b/docs/development/archive/mode3-2026-09/consolidation-plan-2026-09-13.md
similarity index 100%
rename from docs/development/consolidation-plan-2026-09-13.md
rename to docs/development/archive/mode3-2026-09/consolidation-plan-2026-09-13.md
diff --git a/docs/development/mode3-perf-handover-2026-09-13.md b/docs/development/archive/mode3-2026-09/mode3-perf-handover-2026-09-13.md
similarity index 100%
rename from docs/development/mode3-perf-handover-2026-09-13.md
rename to docs/development/archive/mode3-2026-09/mode3-perf-handover-2026-09-13.md
diff --git a/docs/development/sd-read-jitter-2026-09-13.md b/docs/development/archive/mode3-2026-09/sd-read-jitter-2026-09-13.md
similarity index 100%
rename from docs/development/sd-read-jitter-2026-09-13.md
rename to docs/development/archive/mode3-2026-09/sd-read-jitter-2026-09-13.md
diff --git a/docs/development/sd-stall-causal-test-plan-2026-09-13.md b/docs/development/archive/mode3-2026-09/sd-stall-causal-test-plan-2026-09-13.md
similarity index 100%
rename from docs/development/sd-stall-causal-test-plan-2026-09-13.md
rename to docs/development/archive/mode3-2026-09/sd-stall-causal-test-plan-2026-09-13.md
diff --git a/docs/development/soak-handoff-2026-09-14.md b/docs/development/archive/mode3-2026-09/soak-handoff-2026-09-14.md
similarity index 100%
rename from docs/development/soak-handoff-2026-09-14.md
rename to docs/development/archive/mode3-2026-09/soak-handoff-2026-09-14.md
diff --git a/docs/development/arena-studio-release-notes.md b/docs/development/arena-studio-release-notes.md
index 3612d78a..e807efae 100644
--- a/docs/development/arena-studio-release-notes.md
+++ b/docs/development/arena-studio-release-notes.md
@@ -43,7 +43,7 @@ history lives here. Newest first. (Per-session engineering detail stays in
   `scripts/telemetry-report.py` (SD read cost by step, stall clusters, per-trial verdicts).
 - Bench A/B helper `Studio.setSdDiag(flags)` (firmware with `SET_SD_DIAG` 0xCE): forces the legacy FAT-chain
   seek and/or disables the same-index read skip per iteration for the causal test of the card stalls
-  (`docs/development/sd-stall-causal-test-plan-2026-09-13.md`); the arm is recorded in `run_metadata.sd_card.sd_diag`.
+  (`docs/development/archive/mode3-2026-09/sd-stall-causal-test-plan-2026-09-13.md`); the arm is recorded in `run_metadata.sd_card.sd_diag`.
 - **Open-loop soak.** The soak driver accepts protocols without a FicTrac plugin (e.g. the Mode-2
   SD control `protocols/soak_mode2_open_loop.yaml`): the bridge is still the logger, but the
   "simulator frames arriving" gate and the 0x70 exposure test are skipped. New campaign protocols
diff --git a/docs/development/mode3-reliability-handoff-2026-09-14.md b/docs/development/mode3-reliability-handoff-2026-09-14.md
index 6279b8fc..05819a8d 100644
--- a/docs/development/mode3-reliability-handoff-2026-09-14.md
+++ b/docs/development/mode3-reliability-handoff-2026-09-14.md
@@ -12,7 +12,7 @@ numbers given); this is the narrative and the map.
 | B | **display freezes of 30–90 ms** every ~24.5k frame reads of a large pattern (fw #54) | firmware FAT access: SdFat re-walked the file's cluster chain on backward seeks and looked up the next cluster inside every read that crossed a 4 KB cluster boundary; those FAT-sector reads hammered one physical block of the card until its read-disturb maintenance paused the card | **contiguous O(1) seeks** (`FsFile` + `contiguousRange()`): the FAT is read once at pattern open and never during a trial | 4-arm causal test 2026-09-13: FAT touched → stalls at the old spacing; FAT untouched, same read count → 0; production: 0 in 482k + 72k commands + 1 h at 286 Hz |
 
 **Candidate build:** firmware `feat/sd-fastpath-2x10` @ `75405ee` (label `… freerun sdfast`, 0xCB flags `0x7C`);
-Studio v0.77 (PRs #198 + #202). **Run sheet for the bench:** `soak-handoff-2026-09-14.md`; **lab test day on Windows (no Claude):** `lab-test-day-windows-2026-09-14.md`; **what the overnight tests:** `overnight-soak-test-plan-2026-09-13.md`.
+Studio v0.77 (PRs #198 + #202). **Run sheet for the bench:** `archive/mode3-2026-09/soak-handoff-2026-09-14.md`; **lab test day on Windows (no Claude):** `lab-test-day-windows-2026-09-14.md`; **what the overnight tests:** `overnight-soak-test-plan-2026-09-13.md`.
 
 ---
 
@@ -113,7 +113,7 @@ behaviour samples; `cf` rows have 8 or 11 fields; readers go through `js/runlog-
   `test_crashreport_passthrough` after a HalfKay reflash (junk RAM), `test_overfill_evicts_oldest…` (timing).
 - **Bench smoke (Studio):** connect → label ends `freerun sdfast` → one 60 s Mode-3 trial with the simulator → the
   run log has `cc`/`cf`/`cs` rows, `run_metadata.firmware` + `.sd_card`, and a `trial_quality` event.
-- **Soak:** `soak-handoff-2026-09-14.md` (2 h stress, overnight benchmark, pass criteria).
+- **Soak:** `archive/mode3-2026-09/soak-handoff-2026-09-14.md` (2 h stress, overnight benchmark, pass criteria).
 
 ## 6. Evidence
 
@@ -207,6 +207,20 @@ precondition: pattern files contiguous on the card (uploads through the Studio a
    `runlog-format-review-2026-09-13.md`. A MATLAB reader in maDisplayTools, if one exists, needs rule 2 (string-tagged
    arrays are not behaviour) — the only change that can break an old parser.
 
+## 7.3 Ship plan (Michael, 2026-09-13 18:30 ET) and the paper trail
+
+- **Firmware:** the stack is re-based onto `main` on top of PR #48's per-board build scheme as branch
+  `feat/mode3-reliability` with a 2×10 variant (`-DARENA_HW_2_10`, env `teensy41-2-10-performance`) and a THREE-commit
+  story (variant · feature stack · tests+tools); that branch is what runs overnight and what the lab flashes; its PR
+  against `main` is the merge candidate. `feat/sd-fastpath-2x10` (PR #55, closed) keeps the fine-grained 31-commit
+  history; PR #53 closed as superseded.
+- **Studio:** PRs #198 and #202 squash-merged to `main` in the morning after a clean night (two commits: v0.76, v0.78),
+  no separate review; revert if the lab finds a problem.
+- **Docs:** the living set is this file, `lab-test-day-windows-2026-09-14.md`, `overnight-soak-test-plan-2026-09-13.md`,
+  `runlog-format-review-2026-09-13.md`, `telemetry-review-handoff-2026-09-13.md` and the bench log in
+  `mode3-wedge-soak-plan.md` §10. The working documents of the day (evidence write-up, causal plan, consolidation plan,
+  run sheet, session brief) are in `docs/development/archive/mode3-2026-09/` — read them only for history.
+
 ## 8. Where things live
 
 - Firmware: `src/Health.*`, `src/Telemetry.*`, `src/Watchdog*`/`Health` v2 fields, `src/SpiManager.*` (timer),
@@ -214,7 +228,7 @@ precondition: pattern files contiguous on the card (uploads through the Studio a
   (byte tables), `tests/telemetry_codec.py` (decoder), `scripts/` (bench tools).
 - Web: `js/arena-wire-g6.js`, `js/arena-telemetry.js`, `js/trial-quality.js`, `js/studio-postmortem.js`,
   `js/fictrac-bridge-client.js`, `arena_studio.html` (soak driver, sinks), `scripts/telemetry-report.py`,
-  `scripts/wedge-scan.py`, `docs/development/` (this file, `soak-handoff-2026-09-14.md`, `mode3-wedge-soak-plan.md`
-  §10 bench log, `sd-read-jitter-2026-09-13.md` §8 diagrams, `sd-stall-causal-test-plan-2026-09-13.md`,
-  `consolidation-plan-2026-09-13.md`, `telemetry-review-handoff-2026-09-13.md`).
+  `scripts/wedge-scan.py`, `docs/development/` (this file, `archive/mode3-2026-09/soak-handoff-2026-09-14.md`, `mode3-wedge-soak-plan.md`
+  §10 bench log, `archive/mode3-2026-09/sd-read-jitter-2026-09-13.md` §8 diagrams, `archive/mode3-2026-09/sd-stall-causal-test-plan-2026-09-13.md`,
+  `archive/mode3-2026-09/consolidation-plan-2026-09-13.md`, `telemetry-review-handoff-2026-09-13.md`).
 - Issues: firmware #50 (wedge, Michael's thread), #54 (SD stalls), web #197, #200, #201.
diff --git a/docs/development/mode3-wedge-soak-plan.md b/docs/development/mode3-wedge-soak-plan.md
index 1104da41..4d815247 100644
--- a/docs/development/mode3-wedge-soak-plan.md
+++ b/docs/development/mode3-wedge-soak-plan.md
@@ -305,7 +305,7 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   `394dee45` totals: 24 runs, 5.15 M 0x70s, ~7.7 h streaming, 0 wedges. Codex review of the findings/fix/upstream
   note reconciled (`mode3-wedge-upstream-note-2026-09-13.md` — baseline restated to the 200 Hz block, conditional
   3 % instead of P ≈ 0.0007, invariant-framed upstream fix); final texts await Michael. Handover for the
-  performance session: `mode3-perf-handover-2026-09-13.md`. Controller left on `394dee45`, Studio connected idle.
+  performance session: `archive/mode3-2026-09/mode3-perf-handover-2026-09-13.md`. Controller left on `394dee45`, Studio connected idle.
 
 - **2026-09-13 09:53–11:30 ET — performance session (Claude, worktree `vigilant-tereshkova`, host branch
   `claude/mode3-perf-sd` on #198; firmware `feat/sd-fastpath-2x10` on the ring branch, local).** Bench untouched so far
@@ -325,7 +325,7 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   0xCD → `run_metadata.sd_card`, telemetry-report.py; all suites green. Read-free access-pattern research (agent +
   Codex brainstorm): every course motion pattern except looming is an exact +1 px/frame roll; independent-frame LZ4
   shrinks the 813 KB bar to 15 KB → complete compressed RAM cache loaded in the ITI is the recommended next step;
-  panel PSRAM write path is specified but unimplemented in panel firmware (`docs/development/sd-read-jitter-2026-09-13.md` §6).
+  panel PSRAM write path is specified but unimplemented in panel firmware (`docs/development/archive/mode3-2026-09/sd-read-jitter-2026-09-13.md` §6).
   Codex round 2 on the round-1 fixes running; flash follows its reconciliation.
 
 - **2026-09-13 11:35:07–11:35:13 ET — flashed `3c71953` (SD fast path build) via the bootloader route** after Michael
@@ -411,14 +411,14 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   free); the :8092 worktree server stopped; bridge 3.1 + sim (200 Hz) left as Michael started them. Host branch
   `claude/mode3-perf-sd` pushed; firmware `feat/sd-fastpath-2x10` stays local (tip `f6c11d2` built, `3c71953` on the
   controller). Standing next steps: causal reflash; card screening with `sd_stall_test.py` when cards arrive; read-free
-  path (compressed RAM cache in the ITI, `sd-read-jitter-2026-09-13.md` §6); Codex diff review of `f6c11d2` before it
+  path (compressed RAM cache in the ITI, `archive/mode3-2026-09/sd-read-jitter-2026-09-13.md` §6); Codex diff review of `f6c11d2` before it
   is flashed; #201 PR consolidation; telemetry review session (`telemetry-review-handoff-2026-09-13.md`).
 
 - **2026-09-13 12:45 ET — causal test prepared (bench later, Michael):** firmware `2c83f45` adds `SET_SD_DIAG` 0xCE
   (bit0 legacy FAT-chain seek at the next open, bit1 no same-index skip; readback 0xCD byte 29; `sd_layout` bits 2/3;
   STATE marker), built, Codex round 3 running — NOT flashed (controller stays on `3c71953`). Studio v0.77 gains
   `Studio.setSdDiag(flags)` + `run_metadata.sd_card.sd_diag`; telemetry-report labels the arm. Plan with predictions,
-  stopping rules and procedure: `docs/development/sd-stall-causal-test-plan-2026-09-13.md` (arms 3 → 1 → 2 → 0 on one
+  stopping rules and procedure: `docs/development/archive/mode3-2026-09/sd-stall-causal-test-plan-2026-09-13.md` (arms 3 → 1 → 2 → 0 on one
   build, ~70 min; H-FAT fingerprint = `sd_slow` phase `seek` in the legacy-seek arms).
 
 - **2026-09-13 13:00 ET — Codex round 3 on the 0xCE build (`.codex-review/codex-diff-review-20260913-123149-22302`):**
@@ -430,7 +430,7 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   controller time, bounded stall detail, per-open read totals, resync after a timeout, `--sd-diag N` arm with
   applied-mode verification, exit 4 unless usable). Firmware tip built, NOT flashed; a Codex diff review of the
   round-3 delta is owed before it goes on the controller. Extended campaign matrix (patterns × Mode 2/3 × speeds)
-  added to `sd-stall-causal-test-plan-2026-09-13.md` §7.
+  added to `archive/mode3-2026-09/sd-stall-causal-test-plan-2026-09-13.md` §7.
 - **2026-09-13 13:30–14:15 ET — Michael back online (remote, no bench). Codex round 4 on the round-3 delta
   (`0fc6b01..9de97fe`, `.codex-review/codex-diff-review-20260913-133230-26229`, report `report-20260913-fw-round4.md`):
   no blocking firmware finding; harness/codec fixes committed as `75405ee` (exact worst/cluster statistics, legacy
@@ -448,7 +448,7 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   fix) → SD fast path on top of `arena-2x10-local` (fast-forward, 31 commits; conflicts with `main` only because #48
   moved main to per-board `-DARENA_HW_*` headers — the main port is a later PR, superseding #53). Web: PR #202 opened
   (`claude/mode3-perf-sd` → `claude/mode3-wedge-soak`, stacked on #198; both merge cleanly onto main, #198 CI green,
-  `pixi run test` green). One-page run sheet `docs/development/soak-handoff-2026-09-14.md` (flash, serve, card,
+  `pixi run test` green). One-page run sheet `docs/development/archive/mode3-2026-09/soak-handoff-2026-09-14.md` (flash, serve, card,
   three runs, pass criteria, merge order). Firmware branch still LOCAL — push + PR against `arena-2x10-local`
   awaits Michael's go. RAM-cached FAT chain (extent table): deferred — decide on the 70-min causal result
   (§5 of the causal plan).
@@ -497,7 +497,7 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   FRAME read time in verdicts, link-drop = CONTROLLER_FAULT, stress gain 0.18; PR #202 updated, `pixi run test`
   green). New docs: `mode3-reliability-handoff-2026-09-14.md` (the one hand-off document),
   `runlog-format-review-2026-09-13.md` (≈133 MB/h raw, 35–40 gz at 200 Hz; R1 stream-gzip, R2 schema v3),
-  `consolidation-plan-2026-09-13.md`. Plan for 16:12: stop the 286 Hz run (1 h), flash `e59767e`, HIL subset, upload
+  `archive/mode3-2026-09/consolidation-plan-2026-09-13.md`. Plan for 16:12: stop the 286 Hz run (1 h), flash `e59767e`, HIL subset, upload
   the 8 MB sine browser-free, verify indices, start the alternating campaign (286 Hz → 18:15, 200 Hz → 21:00).
 - **2026-09-13 16:02 ET — overnight test plan written (`overnight-soak-test-plan-2026-09-13.md`: timing T1–T7, log
   completeness L1–L7, recovery R1–R5 + a pre-overnight drill: injected stall via 0xCE, injected watchdog reset via
diff --git a/docs/development/telemetry-review-handoff-2026-09-13.md b/docs/development/telemetry-review-handoff-2026-09-13.md
index 5e167d41..bec8e89e 100644
--- a/docs/development/telemetry-review-handoff-2026-09-13.md
+++ b/docs/development/telemetry-review-handoff-2026-09-13.md
@@ -9,7 +9,7 @@ its own (no Analog Discovery, no Saleae). **Michael's acceptance numbers:** disp
 worst case; ≥ 30 ms is a visible artifact.
 
 Read in this order: this file → `telemetry-performance-handover-2026-09-12.md` §4–§6 (log format as of the
-ring's first night) → `sd-read-jitter-2026-09-13.md` (what changed today and why) → firmware README
+ring's first night) → `archive/mode3-2026-09/sd-read-jitter-2026-09-13.md` (what changed today and why) → firmware README
 "Telemetry ring", "Health + breadcrumb", "Free-running refresh timer", "SD fast path" sections (ring
 worktree `/Users/reiserm/Documents/GitHub/LED-Display_G6_Firmware_Arena-ring/README.md`) →
 `controller-telemetry-ring-buffer-proposal.md` (the original design + §8 clock fit, §9 instrument plan).
@@ -148,7 +148,7 @@ light. Options, cheapest first:
 1. **Control iterations on the new build — DONE 2026-09-13 12:27 ET:** two iterations, 482k commands, **0 stalls**
    (baseline: 4 clusters per iteration on the same card); bar backward-seek cost 2.0 → 1.46 ms; reads/command 0.76;
    `req_age_us` p50 1.7 ms, max 4.8 ms; all 40 trials pass. Working explanation: the FAT-sector re-reads of the
-   old seek path were the card's read-disturb hot spot (`sd-read-jitter-2026-09-13.md` §7, bench log 11:55). The
+   old seek path were the card's read-disturb hot spot (`archive/mode3-2026-09/sd-read-jitter-2026-09-13.md` §7, bench log 11:55). The
    causal test (reflash `394dee45` for one iteration) is pending Michael's decision.
 2. **Working-set test on the same file** (`sd_stall_test.py --window 50/100/200`, after the harness fixes): does a
    50-frame working set inside the 813 KB file stall? Discriminates card read-cache vs placement explanations.
@@ -157,10 +157,10 @@ light. Options, cheapest first:
 4. **Photodiode-on-AIN glass-to-glass** (§5.3): the only way to turn `req_age_us` into a latency to light.
 5. **FicTrac → command linkage** (§4.4) then the full chain on a real FicTrac rig (camera clock, not the sim).
 6. **Telemetry-on vs -off control iteration** (Debug ▾ toggle): the instrumentation's own cost.
-7. **Card screening** when cards arrive (protocol in `sd-read-jitter-2026-09-13.md` §5); never reformat the
+7. **Card screening** when cards arrive (protocol in `archive/mode3-2026-09/sd-read-jitter-2026-09-13.md` §5); never reformat the
    current card.
 8. **Resident-decode proof** (next implementation session, not this review): LZ4/zlib per-frame RAM cache of the
-   bar pattern loaded in the ITI; the read-free path (`sd-read-jitter-2026-09-13.md` §6).
+   bar pattern loaded in the ITI; the read-free path (`archive/mode3-2026-09/sd-read-jitter-2026-09-13.md` §6).
 
 ## 7. Known gaps / caveats for the reviewer
 

From ef4c864d087960ede03ca68a6c3edad5e3b8f78b Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 18:43:39 -0400
Subject: [PATCH 39/67] =?UTF-8?q?docs:=20archive=20the=20wedge-era=20worki?=
 =?UTF-8?q?ng=20notes=20(2026-09-08=20=E2=86=92=2009-13)=20under=20docs/de?=
 =?UTF-8?q?velopment/archive/mode3-2026-09;=20links=20repointed?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/development/archive/mode3-2026-09/README.md           | 7 +++++++
 .../{ => archive/mode3-2026-09}/codex-review-2026-09-09.md | 0
 .../mode3-2026-09}/codex-review-2026-09-12-mode3-wedge.md  | 2 +-
 .../codex-review-2026-09-13-mode3-wedge-fix.md             | 0
 .../mode3-2026-09}/lab-pc-handover-2026-09-09.md           | 4 ++--
 .../mode3-2026-09}/merge-bench-plan-2026-09-08.md          | 2 +-
 .../mode3-2026-09}/mode3-wedge-closeout-plan.md            | 0
 .../mode3-2026-09}/mode3-wedge-evidence-2026-09-13.md      | 0
 .../mode3-2026-09}/mode3-wedge-night2-scan-2026-09-13.md   | 0
 .../mode3-2026-09}/mode3-wedge-status-2026-09-12.md        | 2 +-
 .../mode3-2026-09}/mode3-wedge-upstream-note-2026-09-13.md | 0
 .../telemetry-performance-handover-2026-09-12.md           | 0
 docs/development/mode3-wedge-soak-plan.md                  | 6 +++---
 docs/development/telemetry-review-handoff-2026-09-13.md    | 2 +-
 14 files changed, 16 insertions(+), 9 deletions(-)
 rename docs/development/{ => archive/mode3-2026-09}/codex-review-2026-09-09.md (100%)
 rename docs/development/{ => archive/mode3-2026-09}/codex-review-2026-09-12-mode3-wedge.md (99%)
 rename docs/development/{ => archive/mode3-2026-09}/codex-review-2026-09-13-mode3-wedge-fix.md (100%)
 rename docs/development/{ => archive/mode3-2026-09}/lab-pc-handover-2026-09-09.md (98%)
 rename docs/development/{ => archive/mode3-2026-09}/merge-bench-plan-2026-09-08.md (99%)
 rename docs/development/{ => archive/mode3-2026-09}/mode3-wedge-closeout-plan.md (100%)
 rename docs/development/{ => archive/mode3-2026-09}/mode3-wedge-evidence-2026-09-13.md (100%)
 rename docs/development/{ => archive/mode3-2026-09}/mode3-wedge-night2-scan-2026-09-13.md (100%)
 rename docs/development/{ => archive/mode3-2026-09}/mode3-wedge-status-2026-09-12.md (98%)
 rename docs/development/{ => archive/mode3-2026-09}/mode3-wedge-upstream-note-2026-09-13.md (100%)
 rename docs/development/{ => archive/mode3-2026-09}/telemetry-performance-handover-2026-09-12.md (100%)

diff --git a/docs/development/archive/mode3-2026-09/README.md b/docs/development/archive/mode3-2026-09/README.md
index 418f8d9c..f0420808 100644
--- a/docs/development/archive/mode3-2026-09/README.md
+++ b/docs/development/archive/mode3-2026-09/README.md
@@ -7,3 +7,10 @@ Superseded by `docs/development/mode3-reliability-handoff-2026-09-14.md` (the on
 - `consolidation-plan-2026-09-13.md` — review gates, decisions and small changes before the hand-off (all decided 17:30 ET).
 - `soak-handoff-2026-09-14.md` — the first run sheet; folded into `lab-test-day-windows-2026-09-14.md`.
 - `mode3-perf-handover-2026-09-13.md` — the session brief this work started from.
+
+Wedge-era working notes (fw #50, 2026-09-08 → 09-13), superseded by the same hand-off document and the bench log in
+`../../mode3-wedge-soak-plan.md` §10:
+
+- `merge-bench-plan-2026-09-08.md`, `codex-review-2026-09-09.md`, `lab-pc-handover-2026-09-09.md` — the merge/bench plan and lab-PC handover before the wedge work.
+- `mode3-wedge-status-2026-09-12.md`, `codex-review-2026-09-12-mode3-wedge.md`, `telemetry-performance-handover-2026-09-12.md` — the wedge diagnosis status, its Codex review, the telemetry-performance handover.
+- `mode3-wedge-evidence-2026-09-13.md`, `mode3-wedge-night2-scan-2026-09-13.md`, `codex-review-2026-09-13-mode3-wedge-fix.md`, `mode3-wedge-upstream-note-2026-09-13.md`, `mode3-wedge-closeout-plan.md` — the evidence for the PIT race, the second night's scan, the fix review, the note for PJRC (Michael's thread), the close-out plan.
diff --git a/docs/development/codex-review-2026-09-09.md b/docs/development/archive/mode3-2026-09/codex-review-2026-09-09.md
similarity index 100%
rename from docs/development/codex-review-2026-09-09.md
rename to docs/development/archive/mode3-2026-09/codex-review-2026-09-09.md
diff --git a/docs/development/codex-review-2026-09-12-mode3-wedge.md b/docs/development/archive/mode3-2026-09/codex-review-2026-09-12-mode3-wedge.md
similarity index 99%
rename from docs/development/codex-review-2026-09-12-mode3-wedge.md
rename to docs/development/archive/mode3-2026-09/codex-review-2026-09-12-mode3-wedge.md
index a68cfb46..9e86cc59 100644
--- a/docs/development/codex-review-2026-09-12-mode3-wedge.md
+++ b/docs/development/archive/mode3-2026-09/codex-review-2026-09-12-mode3-wedge.md
@@ -1,7 +1,7 @@
 # Codex (gpt-6-astra) adversarial review — Mode-3 wedge campaign status + branch diff — reconciliation
 
 **Date:** 2026-09-12 · **Reviewer model:** `gpt-6-astra` (standard + adversarial passes, both runs) ·
-**Inputs:** `docs/development/mode3-wedge-status-2026-09-12.md` (plan/status review, run
+**Inputs:** `mode3-wedge-status-2026-09-12.md` (plan/status review, run
 `codex-plan-review-20260912-114033-86155`) and the branch diff `main...claude/mode3-wedge-soak`
 (5,597 lines, 31 files, run `codex-diff-review-20260912-114034-86380`). Claude's independent
 analyses were written first: `claude-analysis-20260912-status.md`, `claude-analysis-20260912-diff.md`.
diff --git a/docs/development/codex-review-2026-09-13-mode3-wedge-fix.md b/docs/development/archive/mode3-2026-09/codex-review-2026-09-13-mode3-wedge-fix.md
similarity index 100%
rename from docs/development/codex-review-2026-09-13-mode3-wedge-fix.md
rename to docs/development/archive/mode3-2026-09/codex-review-2026-09-13-mode3-wedge-fix.md
diff --git a/docs/development/lab-pc-handover-2026-09-09.md b/docs/development/archive/mode3-2026-09/lab-pc-handover-2026-09-09.md
similarity index 98%
rename from docs/development/lab-pc-handover-2026-09-09.md
rename to docs/development/archive/mode3-2026-09/lab-pc-handover-2026-09-09.md
index 54b66db8..7b5c0be6 100644
--- a/docs/development/lab-pc-handover-2026-09-09.md
+++ b/docs/development/archive/mode3-2026-09/lab-pc-handover-2026-09-09.md
@@ -1,8 +1,8 @@
 # Lab-PC handover — bench-testing the run-log v2 stack (+ optional analog), 2026-09-09
 
 **For a fresh Claude session on the lab Windows PC.** Read this file first, then
-`docs/development/merge-bench-plan-2026-09-08.md` (the full gated checklist) and
-`docs/development/codex-review-2026-09-09.md` (what was just fixed and what is still open).
+`merge-bench-plan-2026-09-08.md` (the full gated checklist) and
+`codex-review-2026-09-09.md` (what was just fixed and what is still open).
 The Mac session that wrote this may still be running; treat GitHub as the source of truth for
 branch state, not this file.
 
diff --git a/docs/development/merge-bench-plan-2026-09-08.md b/docs/development/archive/mode3-2026-09/merge-bench-plan-2026-09-08.md
similarity index 99%
rename from docs/development/merge-bench-plan-2026-09-08.md
rename to docs/development/archive/mode3-2026-09/merge-bench-plan-2026-09-08.md
index 6bd22304..bd2427b5 100644
--- a/docs/development/merge-bench-plan-2026-09-08.md
+++ b/docs/development/archive/mode3-2026-09/merge-bench-plan-2026-09-08.md
@@ -37,7 +37,7 @@ fps meter.
 ### Morning (desk)
 
 - [x] ~~Codex cross-review of all pending work~~ — done 2026-09-09 morning, see
-      `docs/development/codex-review-2026-09-09.md`: 7 true bugs fixed and pushed (#188 strict
+      `codex-review-2026-09-09.md`: 7 true bugs fixed and pushed (#188 strict
       mode; #190 sweep refusal + closed-loop gating, #191 rebased; fw #47 calibration guard +
       mV clamp + controller_info bits); design suggestions listed for discussion.
       Also rebased #186/#188/#190/#191 onto main afterwards: #193 and the two stacks all add
diff --git a/docs/development/mode3-wedge-closeout-plan.md b/docs/development/archive/mode3-2026-09/mode3-wedge-closeout-plan.md
similarity index 100%
rename from docs/development/mode3-wedge-closeout-plan.md
rename to docs/development/archive/mode3-2026-09/mode3-wedge-closeout-plan.md
diff --git a/docs/development/mode3-wedge-evidence-2026-09-13.md b/docs/development/archive/mode3-2026-09/mode3-wedge-evidence-2026-09-13.md
similarity index 100%
rename from docs/development/mode3-wedge-evidence-2026-09-13.md
rename to docs/development/archive/mode3-2026-09/mode3-wedge-evidence-2026-09-13.md
diff --git a/docs/development/mode3-wedge-night2-scan-2026-09-13.md b/docs/development/archive/mode3-2026-09/mode3-wedge-night2-scan-2026-09-13.md
similarity index 100%
rename from docs/development/mode3-wedge-night2-scan-2026-09-13.md
rename to docs/development/archive/mode3-2026-09/mode3-wedge-night2-scan-2026-09-13.md
diff --git a/docs/development/mode3-wedge-status-2026-09-12.md b/docs/development/archive/mode3-2026-09/mode3-wedge-status-2026-09-12.md
similarity index 98%
rename from docs/development/mode3-wedge-status-2026-09-12.md
rename to docs/development/archive/mode3-2026-09/mode3-wedge-status-2026-09-12.md
index b406fc21..855334b6 100644
--- a/docs/development/mode3-wedge-status-2026-09-12.md
+++ b/docs/development/archive/mode3-2026-09/mode3-wedge-status-2026-09-12.md
@@ -83,4 +83,4 @@ Both Codex passes (status/plan + branch diff) are reconciled in `.codex-review/r
 
 **12:20 ET addendum:** the ring firmware code itself was then Codex-reviewed (`LED-Display_G6_Firmware_Arena-ring/.codex-review/report-20260912-ring.md`). Flash is go after the bounded fix commit (reference-drainer handshake, HIL test corrections, ack/incarnation guard, heap guard coverage, exact-size boot repair); dual headers / linker reservation / PSRAM frame identity are deferred to the ship-to-course gate.
 
-**Tracking (12:35 ET):** deferred web items → #200; deferred firmware ring hardening → fw #54. Reconciliation reports committed as `docs/development/codex-review-2026-09-12-mode3-wedge.md` (this repo) and `docs/development/codex-review-2026-09-12-telemetry-ring.md` (ring branch).
+**Tracking (12:35 ET):** deferred web items → #200; deferred firmware ring hardening → fw #54. Reconciliation reports committed as `codex-review-2026-09-12-mode3-wedge.md` (this repo) and `docs/development/codex-review-2026-09-12-telemetry-ring.md` (ring branch).
diff --git a/docs/development/mode3-wedge-upstream-note-2026-09-13.md b/docs/development/archive/mode3-2026-09/mode3-wedge-upstream-note-2026-09-13.md
similarity index 100%
rename from docs/development/mode3-wedge-upstream-note-2026-09-13.md
rename to docs/development/archive/mode3-2026-09/mode3-wedge-upstream-note-2026-09-13.md
diff --git a/docs/development/telemetry-performance-handover-2026-09-12.md b/docs/development/archive/mode3-2026-09/telemetry-performance-handover-2026-09-12.md
similarity index 100%
rename from docs/development/telemetry-performance-handover-2026-09-12.md
rename to docs/development/archive/mode3-2026-09/telemetry-performance-handover-2026-09-12.md
diff --git a/docs/development/mode3-wedge-soak-plan.md b/docs/development/mode3-wedge-soak-plan.md
index 4d815247..1ecbd4d7 100644
--- a/docs/development/mode3-wedge-soak-plan.md
+++ b/docs/development/mode3-wedge-soak-plan.md
@@ -236,7 +236,7 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   the `IntervalTimer::end()` null-callback/`TFLG` race in the Teensy core → PIT interrupt storm with the main
   context's return address exactly at the captured PC (`channel->TCTRL = 0`); verified in the installed core
   1.160.0; quantitatively consistent with Isabel's ~292 k commands/failure (≈ 11 ns window). Now the leading
-  mechanism; bus hang is the alternative. Reconciliation: `codex-review-2026-09-13-mode3-wedge-fix.md`; evidence
+  mechanism; bus hang is the alternative. Reconciliation: `archive/mode3-2026-09/codex-review-2026-09-13-mode3-wedge-fix.md`; evidence
   doc §2b. Diff review of the free-running commit: keep the timer policy; fix the non-atomic ISR-lite record
   update, sticky `armed_hz_` on a failed `begin()`, the lost pre-watchdog ISR identity, the historical-record
   test assertion; README claims softened. All folded into one follow-up firmware commit (safe PRIMASK-guarded
@@ -281,7 +281,7 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
 - **2026-09-13 07:58 ET — morning summary (soak still running, iteration 20 on `394dee45`).**
   Exposure in the 200 Hz + jumps block: baseline `4860fef8` 1.96 h streaming, 1.42 M 0x70s, **2 wedges** (#5 at
   909 s of its run, #6 at 1022 s); fix build `394dee45` 6.53 h, 4.41 M 0x70s, **0 wedges**, 19/19 runs completed
-  (P ≈ 0.002 for zero events at the baseline's rate). Full table: `mode3-wedge-night2-scan-2026-09-13.md`.
+  (P ≈ 0.002 for zero events at the baseline's rate). Full table: `archive/mode3-2026-09/mode3-wedge-night2-scan-2026-09-13.md`.
   Display: 34–45 → 73–75 distinct frames/s at 190 commands/s (145 distinct requests/s), same SD/SPI timings; host
   RTT median 2 → 3 ms, p99 8–9 → 11 ms (more transfers competing in `loop()`). No kind 8/9 records on the fix build
   (no watchdog reset). fw #50 comment drafted (session scratchpad `fw50-comment-draft.md`) — outward-facing, for
@@ -303,7 +303,7 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
 
 - **2026-09-13 09:40 ET — soak wound down (operator stop; iteration 2 of the third soak aborted).** Fix build
   `394dee45` totals: 24 runs, 5.15 M 0x70s, ~7.7 h streaming, 0 wedges. Codex review of the findings/fix/upstream
-  note reconciled (`mode3-wedge-upstream-note-2026-09-13.md` — baseline restated to the 200 Hz block, conditional
+  note reconciled (`archive/mode3-2026-09/mode3-wedge-upstream-note-2026-09-13.md` — baseline restated to the 200 Hz block, conditional
   3 % instead of P ≈ 0.0007, invariant-framed upstream fix); final texts await Michael. Handover for the
   performance session: `archive/mode3-2026-09/mode3-perf-handover-2026-09-13.md`. Controller left on `394dee45`, Studio connected idle.
 
diff --git a/docs/development/telemetry-review-handoff-2026-09-13.md b/docs/development/telemetry-review-handoff-2026-09-13.md
index bec8e89e..7e8a0145 100644
--- a/docs/development/telemetry-review-handoff-2026-09-13.md
+++ b/docs/development/telemetry-review-handoff-2026-09-13.md
@@ -8,7 +8,7 @@ round-trip-latency measurement plan; (4) the next experiments, favouring measure
 its own (no Analog Discovery, no Saleae). **Michael's acceptance numbers:** display freeze 5 ms target, 10 ms
 worst case; ≥ 30 ms is a visible artifact.
 
-Read in this order: this file → `telemetry-performance-handover-2026-09-12.md` §4–§6 (log format as of the
+Read in this order: this file → `archive/mode3-2026-09/telemetry-performance-handover-2026-09-12.md` §4–§6 (log format as of the
 ring's first night) → `archive/mode3-2026-09/sd-read-jitter-2026-09-13.md` (what changed today and why) → firmware README
 "Telemetry ring", "Health + breadcrumb", "Free-running refresh timer", "SD fast path" sections (ring
 worktree `/Users/reiserm/Documents/GitHub/LED-Display_G6_Firmware_Arena-ring/README.md`) →

From 5036f89bf467764463d87703420f624df6c086ce Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 18:44:11 -0400
Subject: [PATCH 40/67] =?UTF-8?q?docs(hand-off):=20=C2=A76.0=20test=20hist?=
 =?UTF-8?q?ory=20=E2=80=94=20every=20bench=20run=20of=20the=20stack=20with?=
 =?UTF-8?q?=20build,=20workload=20and=20result?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../mode3-reliability-handoff-2026-09-14.md     | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/docs/development/mode3-reliability-handoff-2026-09-14.md b/docs/development/mode3-reliability-handoff-2026-09-14.md
index 05819a8d..f5a3f7fc 100644
--- a/docs/development/mode3-reliability-handoff-2026-09-14.md
+++ b/docs/development/mode3-reliability-handoff-2026-09-14.md
@@ -117,6 +117,23 @@ behaviour samples; `cf` rows have 8 or 11 fields; readers go through `js/runlog-
 
 ## 6. Evidence
 
+### 6.0 Test history (every bench run of this stack, oldest first; details with ET times in `mode3-wedge-soak-plan.md` §10)
+
+| when | build | what ran | result |
+|---|---|---|---|
+| 2026-09-11 night | health fw (`22b756d`) + Studio v0.76 | Mode-3 soak, simulator, CSHL 2×10 | wedge reproduced (the fault lifecycle, post-mortem and run-log artefact worked as designed) |
+| 2026-09-12 | ring fw (`c47ee68`) → watchdog fw (`fb11681`…`4860fef`) | soaks with the ring drained live; watchdog self-reset path | wedge lead-up captured in the ring → PIT race identified; watchdog resets and captures the PC; Studio self-reset path exercised |
+| 2026-09-12 night → 09-13 | free-running timer fw (`394dee45`) | 19 + 5 soak iterations, 5.15 M commands at 100/200/286 Hz | **0 wedges**; SD stalls now visible: 716 slow reads in 197 clusters, every ~24.5k reads of the 813 KB pattern |
+| 2026-09-13 11:45–12:27 | SD fast path fw (`3c71953`) + Studio v0.77 | 2 soak iterations, 482k commands | **0 reads > 10 ms, 40/40 trials pass** (vs 4 clusters per iteration the night before) |
+| 2026-09-13 14:47–15:11 | `75405ee` | **causal test**: 4 arms × 6 min via `SET_SD_DIAG`, bar pattern | FAT access is the cause (table below); same-index skip irrelevant |
+| 2026-09-13 15:12–16:12 | `75405ee` | 1 h production at 286 Hz, bar | 1.04 M commands, 0 reads > 1.8 ms, req_age max 3.0 ms |
+| 2026-09-13 16:12–18:16 | `e59767e` (review fixes) | campaign: 13 × 10 min at 286 Hz, 8 MB sine ⇄ 813 KB bar | 2.2 M commands; one 19.4 ms + one 6.4 ms data read 12 ms apart on the sine (single event, no driver error); everything else ≤ 1.8 ms |
+| 2026-09-13 18:16–21:00 | `e59767e` | campaign at 200 Hz | *(running; see the bench log)* |
+| 2026-09-13 night | `feat/mode3-reliability` (this stack on main/#48, 2×10 variant) | recovery drill + overnight Studio soak per `overnight-soak-test-plan-2026-09-13.md` | *(to be filled in the morning)* |
+| offline, every commit | — | firmware `pytest tests/test_telemetry_codec.py tests/test_sd_stall_stats.py` (17), `soak_mode3_selftest.py`; web `pixi run test` (all suites incl. 25 trial-quality, 41 telemetry-report, 65 arena-telemetry, 280 wire), `format-check` | green |
+| HIL (port free) | each flash | `test_firmware_version.py`, `test_health.py`, `test_telemetry.py` subsets | green except two pre-existing flakes and one open item (`test_loop_max_1s_window_is_populated` at 3 s uptime on `e59767e`; re-run at the drill) |
+
+
 **Problem A (wedge):** before — 6 occurrences incl. rig 2 (2026-07-11), ~1 in 10 Mode-3 runs on 2026-09-11/12 soaks.
 After the free-running timer (`394dee4`, 09-12 night → 09-13): 24 iterations, 5.15 M commands, 0 wedges, 0 watchdog
 resets. Root cause demonstrated stand-alone: stock `IntervalTimer::end()` dies in < 0.5 s under the reproducer,

From 20101c15299728e0d20f00e4792f7108e0f911fb Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 18:46:35 -0400
Subject: [PATCH 41/67] =?UTF-8?q?fix(studio):=20session=20rig=20follows=20?=
 =?UTF-8?q?the=20controller's=20reported=20geometry=20when=20no=20explicit?=
 =?UTF-8?q?=20rig=20is=20set=20(fresh=20profiles=20came=20up=20g6=5F3x10?=
 =?UTF-8?q?=20on=20a=202=C3=9710=20controller)=20=E2=80=94=20Studio=20v0.7?=
 =?UTF-8?q?9?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 arena_studio.html                             | 24 ++++++++++++++++++-
 .../development/arena-studio-release-notes.md |  8 +++++++
 2 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/arena_studio.html b/arena_studio.html
index b98fa1e7..2ef4b961 100644
--- a/arena_studio.html
+++ b/arena_studio.html
@@ -2959,7 +2959,7 @@ <h2 id="modalTitle">Import error</h2>
 </div>
 
 <footer id="footer">
-  <span class="foot-left">Arena Studio v0.78 | 2026-09-13 15:42 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.79 | 2026-09-13 18:48 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)">
@@ -3720,6 +3720,7 @@ <h2 id="modalTitle">Import error</h2>
             if (v) {
                 Studio.firmwareVersion = v;
                 Studio.firmware = v.label;
+                if (Studio.deriveRigFromController) Studio.deriveRigFromController(v.rows, v.cols); // no explicit rig → follow the hardware
                 if ($('pvFw')) { $('pvFw').textContent = v.label; $('pvFw').title = 'git ' + v.sha + (v.dirty ? ' (dirty tree)' : '') + ' · ' + v.branch + ' · built ' + v.date + ' · ' + v.arena + (v.debug ? ' · DEBUG_SERIAL' : ''); }
                 rawLine('‹ firmware build: ' + v.label, 'info');
                 Studio.sdCard = null;
@@ -6370,6 +6371,27 @@ <h2 id="modalTitle">Import error</h2>
     });
     if (rigIndex && rigIndex[0]) setSessionRig(rigIndex[0].name, { explicit: false });
 }
+// The controller knows its own geometry (GET_FIRMWARE_VERSION rows × cols). When nobody
+// has chosen a rig explicitly (no ?rig=, no user pick), follow the hardware instead of
+// the index's first entry — a fresh browser profile used to come up as g6_3x10 on a
+// 2×10 controller, which is the wrong geometry for streamed frames and the wrong rig
+// io: power-on defaults (bench 2026-09-13). First index entry whose arena is RxC wins
+// (for 2×10 that is the CSHL fly-on-ball rig). Explicit choices are never overridden.
+Studio.deriveRigFromController = function (rows, cols) {
+    rows = Number(rows); cols = Number(cols); // decodeFirmwareVersion parses them from the label text
+    if (!(rows > 0 && cols > 0) || !rigIndex) return null;
+    const cur = Studio.currentRig;
+    if (cur && cur.explicit) return null;
+    const hit = rigIndex.find((r) => {
+        const m = /^G6_(\d+)x(\d+)/.exec(String(r.arena || ''));
+        return m && Number(m[1]) === rows && Number(m[2]) === cols;
+    });
+    if (!hit || (cur && cur.name === hit.name)) return null;
+    setSessionRig(hit.name, { explicit: false });
+    Studio.rawLog('session rig follows the controller: ' + hit.name + ' (' + rows + '×' + cols + ')', 'info');
+    if (Studio.applyRigIo) { Studio.applyRigIo().catch(() => {}); } // the derived rig's io: defaults, not the placeholder's
+    return hit.name;
+};
 // Point the session rig at a rig name. `explicit` marks a user/URL choice
 // (encoded to the URL); a derived follow (protocol load) never overrides an
 // explicit choice — updateDeviceLine raises the mismatch chip instead.
diff --git a/docs/development/arena-studio-release-notes.md b/docs/development/arena-studio-release-notes.md
index e807efae..e877fcb9 100644
--- a/docs/development/arena-studio-release-notes.md
+++ b/docs/development/arena-studio-release-notes.md
@@ -4,6 +4,14 @@ 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.79 (2026-09-13) · Session rig follows the controller
+
+- **A fresh Studio no longer starts on the wrong arena.** With no explicit rig (no `?rig=`, no user pick) the
+  session rig used to be the first entry of the rig index (`g6_3x10`), whatever controller was plugged in. It now
+  follows the geometry the controller reports at connect (`GET_FIRMWARE_VERSION` rows × cols): on a 2×10
+  controller that is the CSHL fly-on-ball rig. Explicit choices are never overridden; the derived rig's I/O
+  power-on defaults are applied.
+
 ## v0.78 (2026-09-13) · Whole-stack review fixes: the verdict lands in the log
 
 - **The stimulus-quality verdict is written before the run log is exported.** The final telemetry

From 4b838301d2d140024ca9a21dcfb3fad6f9e90a46 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 18:55:12 -0400
Subject: [PATCH 42/67] =?UTF-8?q?docs:=20candidate=20is=20feat/mode3-relia?=
 =?UTF-8?q?bility=20@=20488d5b9=20(PR=20#56=20on=20main,=202=C3=9710=20var?=
 =?UTF-8?q?iant)=20=E2=80=94=20identities=20in=20the=20hand-off,=20lab=20p?=
 =?UTF-8?q?lan,=20test=20plan;=20bench=20log?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../lab-test-day-windows-2026-09-14.md         | 18 ++++++++++--------
 .../mode3-reliability-handoff-2026-09-14.md    | 18 ++++++++++--------
 docs/development/mode3-wedge-soak-plan.md      | 10 ++++++++++
 .../overnight-soak-test-plan-2026-09-13.md     |  4 ++--
 4 files changed, 32 insertions(+), 18 deletions(-)

diff --git a/docs/development/lab-test-day-windows-2026-09-14.md b/docs/development/lab-test-day-windows-2026-09-14.md
index 632bb426..04d42c29 100644
--- a/docs/development/lab-test-day-windows-2026-09-14.md
+++ b/docs/development/lab-test-day-windows-2026-09-14.md
@@ -6,9 +6,10 @@ what changed and why: `mode3-reliability-handoff-2026-09-14.md`.
 
 ## 0. Before you start (Michael)
 
-- [x] Firmware branch `feat/sd-fastpath-2x10` pushed (17:35 ET) — merge-candidate PR
-      [reiserlab/LED-Display_G6_Firmware_Arena#55](https://github.com/reiserlab/LED-Display_G6_Firmware_Arena/pull/55);
-      the lab builds the SAME identity from it (`e59767e5` is compiled in from git).
+- [x] Firmware branch **`feat/mode3-reliability`** pushed (18:55 ET) — merge-candidate PR
+      [reiserlab/LED-Display_G6_Firmware_Arena#56](https://github.com/reiserlab/LED-Display_G6_Firmware_Arena/pull/56)
+      against `main` (Frank's per-board scheme + a 2×10 variant); the lab builds the SAME identity from it
+      (`488d5b9` is compiled in from git).
 - [ ] The CSHL 2×10 controller + its bench card (patterns 36 = bar, 46 = sine already on it) travel to the lab PC,
       or plan 10 extra minutes to upload the two patterns (step 3).
 - [ ] Overnight results from the Mac pasted into §6 of the hand-off document (the reference numbers for §5 below).
@@ -21,7 +22,7 @@ what changed and why: `mode3-reliability-handoff-2026-09-14.md`.
 git clone https://github.com/reiserlab/webDisplayTools.git; cd webDisplayTools; git checkout claude/mode3-perf-sd
 pixi install                              # Node + Python + websockets (needs pixi: https://pixi.sh)
 cd ..; git clone https://github.com/reiserlab/LED-Display_G6_Firmware_Arena.git; cd LED-Display_G6_Firmware_Arena
-git checkout feat/sd-fastpath-2x10
+git checkout feat/mode3-reliability
 pip install platformio pyserial          # or the PlatformIO VS Code extension; Teensy Loader comes with PlatformIO
 ```
 Chrome or Edge (Web Serial). Use **PowerShell**, not Git Bash, for anything with times (Git Bash prints UTC labelled ET).
@@ -29,13 +30,14 @@ Chrome or Edge (Web Serial). Use **PowerShell**, not Git Bash, for anything with
 ## 2. Flash and identify (10 min)
 
 ```powershell
-pio run -e teensy41-performance -t upload --upload-port COM5      # find COMx in Device Manager: "USB Serial Device"
+pio run -e teensy41-2-10-performance -t upload --upload-port COM5   # 2×10 variant; find COMx in Device Manager: "USB Serial Device"
 ```
 Windows gotchas (fw PR #49 notes): the **first upload attempt often fails — run it again**; the arena must be powered;
 if the port vanishes, unplug/replug once. Then in Chrome: `pixi run python -m http.server 8092` in the webDisplayTools
 checkout → `http://localhost:8092/arena_studio.html?advanced=1&soak=1` → **Connect** → pick the Teensy port.
-**Look for**, in the Console log: `firmware e59767e5 2x10 2026-09-13 feat/sd-fastpath-2x10 freerun sdfast` and an
-`sd card: … SD8GB … FAT32 4 KiB clusters` line. If the label is not `e59767e5`, stop: wrong build.
+**Look for**, in the Console log: `firmware 488d5b9b 2x10 2026-09-13 feat/mode3-reliability freerun sdfast`, then
+`session rig follows the controller: cshl_g6_2x10_ball (2×10)` (v0.79) and an `sd card: … SD8GB … FAT32 4 KiB
+clusters` line. If the label is not `488d5b9b`, stop: wrong build.
 
 ## 3. Card check (2 min, or 10 with uploads)
 
@@ -62,7 +64,7 @@ Studio: File ▾ → Open → `protocols/soak_mode3_stress.yaml`; rig `cshl_g6_2
 | B | **Injected stall** (checks the flagging path): in the browser console `await Studio.setSdDiag(3)`, run ONE Test run of the stress protocol, then `await Studio.setSdDiag(0)` | during the run: `display gap NN ms (sd_slow, body) in trial …` lines; at the end `⚠ stimulus quality: … flagged`; after `setSdDiag(0)`, Console identity shows `sd diag 0` | at least one trial flagged; the soak did NOT stop; switches back to 0 |
 | C | **Simulator kill:** during a Soak (start a 2-iteration soak), close the sim window for 30 s, restart it | `soak: no FicTrac frames — waiting for the simulator`, then the next iteration starts | soak resumes by itself; no fault counted |
 | D | **Link drop:** during a trial pull the controller's USB cable, wait 5 s, plug it back | `run ended by a link drop … treating as a controller event`; post-mortem lines (`confirm`, `probe`, `reconnect`); the run's outcome `CONTROLLER_FAULT`; the arena goes **dark** on replug and stays dark until the next trial | reconnects without a page reload; next iteration runs |
-| F | **An old course protocol runs unchanged:** sign in to the course repo (Settings), open rig1 `p3-heisenberg-ts-full.yaml`, run it once as a Test run (simulator running) | it runs to the end exactly as in July; banner `… pass`; the run log has `trial_quality` and `run_metadata.firmware` = `e59767e5 …` | completes, all trials pass |
+| F | **An old course protocol runs unchanged:** sign in to the course repo (Settings), open rig1 `p3-heisenberg-ts-full.yaml`, run it once as a Test run (simulator running) | it runs to the end exactly as in July; banner `… pass`; the run log has `trial_quality` and `run_metadata.firmware` = `488d5b9b …` | completes, all trials pass |
 | E | **Panel firmware update still works with the watchdog** (5 min, only if a spare panel/known-good image is at hand): Console → Firmware → program one panel | progress completes; no controller reboot mid-update (the Console would show a disconnect) | update completes |
 
 Never power-cycle the controller after something odd: the evidence is in RAM until the Studio's post-mortem has read it.
diff --git a/docs/development/mode3-reliability-handoff-2026-09-14.md b/docs/development/mode3-reliability-handoff-2026-09-14.md
index f5a3f7fc..b1ce6238 100644
--- a/docs/development/mode3-reliability-handoff-2026-09-14.md
+++ b/docs/development/mode3-reliability-handoff-2026-09-14.md
@@ -11,8 +11,9 @@ numbers given); this is the narrative and the map.
 | A | **controller wedge**: ~1 in 10 Mode-3 runs the controller went 100–500 ms per command, power cycle only (fw #50) | a race in `IntervalTimer::end()`: SET_FRAME_POSITION disarmed/re-armed the refresh timer per command; a PIT interrupt landing between the two left the PIT firing with a null callback (an ISR storm) | **free-running refresh timer** — 0x70 never touches the PIT; plus an atomic `end()`; plus a hardware watchdog that resets and records the PC if anything like it ever recurs | 24 soak iterations, 5.15 M commands, 0 wedges (was 1 in 10 runs) |
 | B | **display freezes of 30–90 ms** every ~24.5k frame reads of a large pattern (fw #54) | firmware FAT access: SdFat re-walked the file's cluster chain on backward seeks and looked up the next cluster inside every read that crossed a 4 KB cluster boundary; those FAT-sector reads hammered one physical block of the card until its read-disturb maintenance paused the card | **contiguous O(1) seeks** (`FsFile` + `contiguousRange()`): the FAT is read once at pattern open and never during a trial | 4-arm causal test 2026-09-13: FAT touched → stalls at the old spacing; FAT untouched, same read count → 0; production: 0 in 482k + 72k commands + 1 h at 286 Hz |
 
-**Candidate build:** firmware `feat/sd-fastpath-2x10` @ `75405ee` (label `… freerun sdfast`, 0xCB flags `0x7C`);
-Studio v0.77 (PRs #198 + #202). **Run sheet for the bench:** `archive/mode3-2026-09/soak-handoff-2026-09-14.md`; **lab test day on Windows (no Claude):** `lab-test-day-windows-2026-09-14.md`; **what the overnight tests:** `overnight-soak-test-plan-2026-09-13.md`.
+**Candidate build:** firmware **`feat/mode3-reliability` @ `488d5b9`** — the stack on `main` (Frank's per-board scheme,
+PR #48) with a 2×10 variant; build `pio run -e teensy41-2-10-performance`, label `488d5b9 2x10 … freerun sdfast`, 0xCB
+flags `0x7C`; merge-candidate PR reiserlab/LED-Display_G6_Firmware_Arena#56. Studio v0.79 (PRs #198 + #202). **Run sheet for the bench:** `archive/mode3-2026-09/soak-handoff-2026-09-14.md`; **lab test day on Windows (no Claude):** `lab-test-day-windows-2026-09-14.md`; **what the overnight tests:** `overnight-soak-test-plan-2026-09-13.md`.
 
 ---
 
@@ -36,7 +37,7 @@ Studio v0.77 (PRs #198 + #202). **Run sheet for the bench:** `archive/mode3-2026
    (bench switches). Studio v0.77 added per-trial **pass / flagged / unknown** verdicts and the card identity in the
    run metadata. The causal test on Sunday afternoon settled the cause (§6).
 
-## 2. Firmware changes, by layer (all on `arena-2x10-local`, 31 commits, fast-forward)
+## 2. Firmware changes, by layer (three commits on `main` in PR #56; the 31-commit fine-grained history is `feat/sd-fastpath-2x10`)
 
 | layer | commits | opcodes / records | 0xCB flag | README § | HIL tests |
 |---|---|---|---|---|---|
@@ -226,11 +227,12 @@ precondition: pattern files contiguous on the card (uploads through the Studio a
 
 ## 7.3 Ship plan (Michael, 2026-09-13 18:30 ET) and the paper trail
 
-- **Firmware:** the stack is re-based onto `main` on top of PR #48's per-board build scheme as branch
-  `feat/mode3-reliability` with a 2×10 variant (`-DARENA_HW_2_10`, env `teensy41-2-10-performance`) and a THREE-commit
-  story (variant · feature stack · tests+tools); that branch is what runs overnight and what the lab flashes; its PR
-  against `main` is the merge candidate. `feat/sd-fastpath-2x10` (PR #55, closed) keeps the fine-grained 31-commit
-  history; PR #53 closed as superseded.
+- **Firmware:** DONE 18:55 ET — `feat/mode3-reliability` @ `488d5b9` on `main` (PR #48 scheme) with the 2×10 variant
+  (`-DARENA_HW_2_10`, env `teensy41-2-10-performance`), three commits (variant · feature stack · tests+tools);
+  `src/` byte-identical to the bench build `e59767e` except the variant plumbing (tables verified); Codex pass
+  reconciled in the port worktree's `.codex-review/report-20260913-port.md`. **PR #56 against `main` is the merge
+  candidate**; it runs overnight and the lab flashes it. `feat/sd-fastpath-2x10` (PR #55, closed) keeps the
+  fine-grained history; PR #53 closed as superseded.
 - **Studio:** PRs #198 and #202 squash-merged to `main` in the morning after a clean night (two commits: v0.76, v0.78),
   no separate review; revert if the lab finds a problem.
 - **Docs:** the living set is this file, `lab-test-day-windows-2026-09-14.md`, `overnight-soak-test-plan-2026-09-13.md`,
diff --git a/docs/development/mode3-wedge-soak-plan.md b/docs/development/mode3-wedge-soak-plan.md
index 1ecbd4d7..38304441 100644
--- a/docs/development/mode3-wedge-soak-plan.md
+++ b/docs/development/mode3-wedge-soak-plan.md
@@ -528,6 +528,16 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   "phase body on the 8 MB file" watch item from the campaign plan (a data-region event?). Rate so far: 1 in
   ~2.5 M fast-path reads today; below Michael's 30 ms "detectable" line, above the 10 ms flag line → that trial would
   be *flagged*. Night phase (200 Hz) started 18:16; watching for recurrence and whether it stays on the 8 MB file.
+- **2026-09-13 18:25–18:58 ET — port onto `main` (Michael: build tonight's candidate on Frank's #48).** A Fable
+  sub-agent produced `feat/mode3-reliability` = main + the stack + a 2×10 variant (`ARENA_HW_2_10`, envs
+  `teensy41-2-10[-performance]`), three commits (`6782cda` variant, `165dc8f` stack, `488d5b9` tests+tools); all
+  three arena variants build; `src/` byte-identical to `e59767e` except the variant plumbing; 2×10 `panel_sets`
+  (50 numbers) and tie-high list verified equal to the bench build. Codex pass (`…-port/.codex-review/report-20260913-port.md`):
+  nothing against the plumbing; HIL `SET_SD_DIAG` tests made exFAT-aware; blank-before-`sd.begin()` and the test
+  geometry fixture deferred. **Pushed; PR #56 against `main` = merge candidate; #55 and #53 closed.** Hex
+  `firmware-488d5b9-2-10.hex` (sha `d8b31ca7…`) archived in the scratchpad; flash at the drill. Studio v0.79 (session
+  rig follows the controller's rows × cols — fresh profiles came up `g6_3x10`). Docs: wedge-era notes archived;
+  PRs #198/#202 carry a History-and-tests section; hand-off §6.0 test history.
 
 ## 11. T4 as built (2026-09-12) — soak with ring-buffer logging
 
diff --git a/docs/development/overnight-soak-test-plan-2026-09-13.md b/docs/development/overnight-soak-test-plan-2026-09-13.md
index f65c6eca..92648be4 100644
--- a/docs/development/overnight-soak-test-plan-2026-09-13.md
+++ b/docs/development/overnight-soak-test-plan-2026-09-13.md
@@ -1,4 +1,4 @@
-# Overnight soak — what exactly we are testing for (2026-09-13, candidate firmware `e59767e` + Studio v0.78)
+# Overnight soak — what exactly we are testing for (2026-09-13, candidate firmware `488d5b9` on `feat/mode3-reliability` + Studio v0.79)
 
 Three questions, each with the metric, where it comes from in the log, the pass line, and the command that checks it.
 The overnight run goes through the **Studio** (soak driver + bridge + simulator), not the browser-free harness:
@@ -26,7 +26,7 @@ iterations, ≈ 560 trials, ≈ 6 M frame commands.
 
 | # | claim | metric | source | pass | check |
 |---|---|---|---|---|---|
-| L1 | **Every iteration produced one committed run log** with the tail (v0.78 ordering fix) | per file: `run_metadata` (firmware label `e59767e5 … freerun sdfast`, `sd_card`, `sd_diag` 0), `stream_schema`, `trial_quality` event present, and it comes AFTER the last `cc`/`cf`/`cs` row | run-log `.jsonl(.gz)` | 28 of 28 files; `trial_quality` last among controller rows in every file | `runlog-check.py` (below) |
+| L1 | **Every iteration produced one committed run log** with the tail (v0.78 ordering fix) | per file: `run_metadata` (firmware label `488d5b9b … freerun sdfast`, `sd_card`, `sd_diag` 0), `stream_schema`, `trial_quality` event present, and it comes AFTER the last `cc`/`cf`/`cs` row | run-log `.jsonl(.gz)` | 28 of 28 files; `trial_quality` last among controller rows in every file | `runlog-check.py` (below) |
 | L2 | **Nothing lost in the drain** | drainer stats at iteration end: `dropped`, `gaps`, `notStored`, `errors`; `cc` accepted 0x70 count vs `a` accepted count | soak `iteration-end.telemetry`; row counts | all four 0; counts equal ±1 per file | `runlog-check.py` |
 | L3 | **Sequence continuity** across the night | ring `seq` of `cc`/`cf`/`cs` monotonic, no gap between files except at the ring's version/incarnation boundary (none expected) | rows field 3 | 0 gaps | `wedge-scan.py` `seq gaps` |
 | L4 | **Per-trial read accounting closes** | `sd_reads` (kind 13) present for every trial and ≈ index changes + 1 | `cs` kind 13, `cc` rows | every trial has it; |reads − (index changes + 1)| ≤ 2 | `telemetry-report.py` per-trial table (`reads_fw`) |

From a64c7b92305e7e2ce7b9cc427c59662d8beec745 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 18:56:36 -0400
Subject: [PATCH 43/67] =?UTF-8?q?feat(studio):=20banner=20+=20log=20warnin?=
 =?UTF-8?q?g=20when=20SET=5FSD=5FDIAG=20switches=20are=20found=20on=20at?=
 =?UTF-8?q?=20connect=20(decision:=20keep=20the=20switch=20in=20production?=
 =?UTF-8?q?,=20banner=20it);=20decisions=20recorded=20in=20the=20hand-off?=
 =?UTF-8?q?=20=E2=80=94=20v0.79?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 arena_studio.html                                      | 10 +++++++++-
 docs/development/arena-studio-release-notes.md         |  2 ++
 .../mode3-reliability-handoff-2026-09-14.md            |  3 +++
 3 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/arena_studio.html b/arena_studio.html
index 2ef4b961..2019c70a 100644
--- a/arena_studio.html
+++ b/arena_studio.html
@@ -2959,7 +2959,7 @@ <h2 id="modalTitle">Import error</h2>
 </div>
 
 <footer id="footer">
-  <span class="foot-left">Arena Studio v0.79 | 2026-09-13 18:48 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.79 | 2026-09-13 18:56 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)">
@@ -3729,6 +3729,14 @@ <h2 id="modalTitle">Import error</h2>
                         const si = Wire.decodeSdInfo(await Studio.session.send(Wire.encodeGetSdInfo(), { timeoutMs: 2000 }));
                         Studio.sdCard = si;
                         if (si) rawLine('‹ sd card: ' + si.label + (si.mounted ? ' · cid ' + si.cidHex : ''), si.mounted ? 'info' : 'warn');
+                        // The bench A/B switches (SET_SD_DIAG) persist until the controller reboots: a stray
+                        // arm silently degrades every later trial (legacy FAT-chain seeks / no read skip).
+                        // Say so loudly at connect; production is 0 (Michael, 2026-09-13: keep the switch, banner it).
+                        if (si && (si.sdDiag & 0x03)) {
+                            const arm = (si.sdDiag & 1 ? 'legacy FAT-chain seek' : '') + (si.sdDiag & 3 ? (si.sdDiag & 1 && si.sdDiag & 2 ? ' + ' : '') : '') + (si.sdDiag & 2 ? 'no same-index read skip' : '');
+                            rawLine('⚠ SD diagnostic switches are ON (' + arm + ') — every trial runs degraded until Studio.setSdDiag(0) or a controller reboot', 'warn');
+                            showBanner('⚠ SD diagnostic switches are ON (arm ' + (si.sdDiag & 3) + ': ' + arm + '). Production is 0 — run `await Studio.setSdDiag(0)` unless this is the causal test.');
+                        }
                     } catch (e) { rawLine('sd info: ' + (e && e.message ? e.message : e), 'warn'); }
                 }
                 return v;
diff --git a/docs/development/arena-studio-release-notes.md b/docs/development/arena-studio-release-notes.md
index e877fcb9..c5d6cc85 100644
--- a/docs/development/arena-studio-release-notes.md
+++ b/docs/development/arena-studio-release-notes.md
@@ -11,6 +11,8 @@ history lives here. Newest first. (Per-session engineering detail stays in
   follows the geometry the controller reports at connect (`GET_FIRMWARE_VERSION` rows × cols): on a 2×10
   controller that is the CSHL fly-on-ball rig. Explicit choices are never overridden; the derived rig's I/O
   power-on defaults are applied.
+- **Banner when the SD diagnostic switches are on at connect** (`SET_SD_DIAG` readback ≠ 0): the switches persist
+  until a controller reboot and silently degrade every trial; the banner names the arm and how to clear it.
 
 ## v0.78 (2026-09-13) · Whole-stack review fixes: the verdict lands in the log
 
diff --git a/docs/development/mode3-reliability-handoff-2026-09-14.md b/docs/development/mode3-reliability-handoff-2026-09-14.md
index b1ce6238..425dfa67 100644
--- a/docs/development/mode3-reliability-handoff-2026-09-14.md
+++ b/docs/development/mode3-reliability-handoff-2026-09-14.md
@@ -235,6 +235,9 @@ precondition: pattern files contiguous on the card (uploads through the Studio a
   fine-grained history; PR #53 closed as superseded.
 - **Studio:** PRs #198 and #202 squash-merged to `main` in the morning after a clean night (two commits: v0.76, v0.78),
   no separate review; revert if the lab finds a problem.
+- **Decisions closed (Michael, 2026-09-13 19:00 ET):** keep `SET_SD_DIAG` in production (gated, off at boot, Studio
+  banner when found on at connect — v0.79); one build for the hand-off, no lean variant; firmware PR #56 on `main`;
+  Studio #198 + #202 squash-merged to `main` in the morning; the overnight runs through the Studio.
 - **Docs:** the living set is this file, `lab-test-day-windows-2026-09-14.md`, `overnight-soak-test-plan-2026-09-13.md`,
   `runlog-format-review-2026-09-13.md`, `telemetry-review-handoff-2026-09-13.md` and the bench log in
   `mode3-wedge-soak-plan.md` §10. The working documents of the day (evidence write-up, causal plan, consolidation plan,

From a9ee92a7685a6fbbac1e3c8d373898db0f475a74 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 19:11:29 -0400
Subject: [PATCH 44/67] protocols: one-trial Mode-3 drill (injected-stall test
 / pre-overnight recovery drill)

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 protocols/mode3_drill_1trial.yaml | 67 +++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)
 create mode 100644 protocols/mode3_drill_1trial.yaml

diff --git a/protocols/mode3_drill_1trial.yaml b/protocols/mode3_drill_1trial.yaml
new file mode 100644
index 00000000..0d292cef
--- /dev/null
+++ b/protocols/mode3_drill_1trial.yaml
@@ -0,0 +1,67 @@
+version: 3
+
+# ============================================================================
+# One-trial Mode-3 drill — for the recovery drill before an overnight soak and
+# for the lab's injected-stall test (lab-test-day-windows-2026-09-14.md, test B):
+# a single 60 s closed-loop trial on the 813 KB bar with the simulator, nothing
+# else. Run it as a Test run; the banner at the end is the result.
+#   before:  await Studio.setSdDiag(3)      (inject the stall arm)
+#   after:   await Studio.setSdDiag(0)
+# ============================================================================
+
+experiment_info:
+  name: "Mode-3 drill (one 60 s bar trial)"
+  author: "webDisplayTools"
+
+rig: "./configs/rigs/cshl_g6_2x10_ball.yaml"
+
+plugins:
+  - name: "fictrac"
+    type: "class"
+    matlab:
+      class: "FicTracPlugin"
+    config:
+      bridge_url: "ws://localhost:8765"
+      fictrac_port: 60000
+      proto: "udp"
+      gain: 1.8
+      offset: 0
+
+experiment:
+  - "drill_setup"
+  - "cl_bar_200f"
+  - "drill_shutdown"
+
+conditions:
+  - name: "drill_setup"
+    commands:
+      - type: "plugin"
+        plugin_name: "fictrac"
+        command_name: "connect"
+
+  - name: "cl_bar_200f"
+    commands:
+      - type: "controller"
+        command_name: "trialParams"
+        pattern: "frame2_h_ccw_200f"
+        pattern_ID: 4
+        duration: 60
+        mode: 3
+        frame_index: 0
+        frame_rate: 0
+        gain: 0
+      - type: "plugin"
+        plugin_name: "fictrac"
+        command_name: "startClosedLoop"
+        params:
+          gain: 1.8
+      - type: "wait"
+        duration: 60
+      - type: "plugin"
+        plugin_name: "fictrac"
+        command_name: "stopClosedLoop"
+
+  - name: "drill_shutdown"
+    commands:
+      - type: "controller"
+        command_name: "stopDisplay"

From d1d116df4fa8b9850892733dcf155b2cb558c205 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 19:17:02 -0400
Subject: [PATCH 45/67] docs(bench log): campaign stopped, 488d5b9 flashed +
 HIL, Studio v0.79 connected (rig derived), drill started

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/development/mode3-wedge-soak-plan.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/docs/development/mode3-wedge-soak-plan.md b/docs/development/mode3-wedge-soak-plan.md
index 38304441..f5413a33 100644
--- a/docs/development/mode3-wedge-soak-plan.md
+++ b/docs/development/mode3-wedge-soak-plan.md
@@ -538,6 +538,15 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   `firmware-488d5b9-2-10.hex` (sha `d8b31ca7…`) archived in the scratchpad; flash at the drill. Studio v0.79 (session
   rig follows the controller's rows × cols — fresh profiles came up `g6_3x10`). Docs: wedge-era notes archived;
   PRs #198/#202 carry a History-and-tests section; hand-off §6.0 test history.
+- **2026-09-13 19:09 ET — campaign stopped (18 complete segments: 13 × 286 Hz, 5 × 200 Hz, all usable; the only
+  event the 19.4/6.4 ms pair in segment 9); flashed `488d5b9` (2×10 variant on main) 19:09:59.** HIL subset: 26 passed,
+  3 failed = the two pre-existing flakes (`test_crashreport_passthrough` after HalfKay, `test_overfill…`) +
+  `test_loop_max_1s_window_is_populated` at ~3 s uptime, which **passes when re-run at normal uptime** → early-boot
+  artefact, not a regression. Studio v0.79 on :8092 (Michael picked the port after the re-enumeration): label
+  `488d5b9b 2x10 2026-09-13 feat/mode3-reliability freerun sdfast`, **session rig derived `cshl_g6_2x10_ball`** (the
+  log shows the g6_3x10 io defaults applied first, then re-applied for the derived rig one second later — ordering
+  follow-up, same io values), sd card line, `sdDiag` 0, telemetry available. 19:17 drill step 1: `setSdDiag(3)` +
+  one-trial drill protocol (`protocols/mode3_drill_1trial.yaml`).
 
 ## 11. T4 as built (2026-09-12) — soak with ring-buffer logging
 

From 0419166664c85293e29e79ef6990923c6fc2b137 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 19:21:13 -0400
Subject: [PATCH 46/67] protocols: course-card pattern names (p3_heisenberg_ts
 = idx 36, sine idx 46); drill trial 180 s and run as a 1-iteration soak; lab
 plan + test plan updated

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../lab-test-day-windows-2026-09-14.md          |  4 ++--
 .../overnight-soak-test-plan-2026-09-13.md      |  4 ++--
 protocols/mode3_drill_1trial.yaml               | 17 ++++++++++-------
 protocols/soak_mode3_stress.yaml                |  8 +++++---
 4 files changed, 19 insertions(+), 14 deletions(-)

diff --git a/docs/development/lab-test-day-windows-2026-09-14.md b/docs/development/lab-test-day-windows-2026-09-14.md
index 04d42c29..852176cd 100644
--- a/docs/development/lab-test-day-windows-2026-09-14.md
+++ b/docs/development/lab-test-day-windows-2026-09-14.md
@@ -41,7 +41,7 @@ clusters` line. If the label is not `488d5b9b`, stop: wrong build.
 
 ## 3. Card check (2 min, or 10 with uploads)
 
-Console → the SD listing must show `frame2_h_ccw_200f` (200 frames) and `sine_2000f_gs16` (2000 frames). If not:
+Console → the SD listing must show `p3_heisenberg_ts` (index 36 on the course card: the 813 KB, 200-frame bar) and `sine_2000f_gs16` (index 46, 2000 frames). If not:
 `pixi run node scripts/make-stress-patterns.js` writes both into `soak-patterns\`; upload them from the Console
 (SD upload) with the display stopped. Indices are by sorted filename; the protocol resolves names, so numbers don't matter.
 
@@ -61,7 +61,7 @@ Studio: File ▾ → Open → `protocols/soak_mode3_stress.yaml`; rig `cshl_g6_2
 | # | do | look for (Studio log / files) | pass |
 |---|---|---|---|
 | A | **Soak, 3 iterations (~1 h):** File ▾ → Soak…, `iterations 3, gap 10 s, first fault halt, then reset-continue, max resets 3` | `soak ended (iterations) after 3 iteration(s), 0 fault(s), 0 reset(s)`; every iteration banner `… pass · 0 flagged · 0 unknown` | 0 faults, 0 resets, 60 of 60 trials pass |
-| B | **Injected stall** (checks the flagging path): in the browser console `await Studio.setSdDiag(3)`, run ONE Test run of the stress protocol, then `await Studio.setSdDiag(0)` | during the run: `display gap NN ms (sd_slow, body) in trial …` lines; at the end `⚠ stimulus quality: … flagged`; after `setSdDiag(0)`, Console identity shows `sd diag 0` | at least one trial flagged; the soak did NOT stop; switches back to 0 |
+| B | **Injected stall** (checks the flagging path): in the browser console `await Studio.setSdDiag(3)`, open `protocols/mode3_drill_1trial.yaml` and run it as a 1-iteration Soak (File ▾ → Soak…, iterations 1), then `await Studio.setSdDiag(0)` | during the run: `display gap NN ms (sd_slow, body) in trial …` lines; at the end `⚠ stimulus quality: … flagged`; after `setSdDiag(0)`, Console identity shows `sd diag 0` | at least one trial flagged; the soak did NOT stop; switches back to 0 |
 | C | **Simulator kill:** during a Soak (start a 2-iteration soak), close the sim window for 30 s, restart it | `soak: no FicTrac frames — waiting for the simulator`, then the next iteration starts | soak resumes by itself; no fault counted |
 | D | **Link drop:** during a trial pull the controller's USB cable, wait 5 s, plug it back | `run ended by a link drop … treating as a controller event`; post-mortem lines (`confirm`, `probe`, `reconnect`); the run's outcome `CONTROLLER_FAULT`; the arena goes **dark** on replug and stays dark until the next trial | reconnects without a page reload; next iteration runs |
 | F | **An old course protocol runs unchanged:** sign in to the course repo (Settings), open rig1 `p3-heisenberg-ts-full.yaml`, run it once as a Test run (simulator running) | it runs to the end exactly as in July; banner `… pass`; the run log has `trial_quality` and `run_metadata.firmware` = `488d5b9b …` | completes, all trials pass |
diff --git a/docs/development/overnight-soak-test-plan-2026-09-13.md b/docs/development/overnight-soak-test-plan-2026-09-13.md
index 92648be4..30e7bebc 100644
--- a/docs/development/overnight-soak-test-plan-2026-09-13.md
+++ b/docs/development/overnight-soak-test-plan-2026-09-13.md
@@ -55,8 +55,8 @@ judged by evidence, not by the soak still running in the morning.
 
 ### Recovery drill BEFORE the overnight (≈ 15 min, on the candidate build, Studio path) — exercises R2 and R3 on purpose
 
-1. **Injected stall (R3 + the never-yet-seen Studio banner):** `await Studio.setSdDiag(3)`; run one 60 s bar trial
-   (`Studio.runOnce(false)` on the standard soak protocol); expect ≥ 1 `display_gap`, the trial `fail`, the banner
+1. **Injected stall (R3 + the never-yet-seen Studio banner):** `await Studio.setSdDiag(3)`; run `protocols/mode3_drill_1trial.yaml`
+   (one 180 s bar trial) as a 1-iteration Soak — a plain Test run writes a Test-style log without `run_metadata`/`a` rows; expect ≥ 1 `display_gap`, the trial `fail`, the banner
    "⚠ stimulus quality: … flagged", `sd_layout` legacy+no-skip in the log; then `await Studio.setSdDiag(0)` and
    confirm `Studio.sdCard.sdDiag === 0` after a reconnect (persistence check).
 2. **Injected watchdog reset (R2):** during a trial send `SET_TELEMETRY` with flags `0x31` (events on + watchdog bits
diff --git a/protocols/mode3_drill_1trial.yaml b/protocols/mode3_drill_1trial.yaml
index 0d292cef..18957d04 100644
--- a/protocols/mode3_drill_1trial.yaml
+++ b/protocols/mode3_drill_1trial.yaml
@@ -3,14 +3,15 @@ version: 3
 # ============================================================================
 # One-trial Mode-3 drill — for the recovery drill before an overnight soak and
 # for the lab's injected-stall test (lab-test-day-windows-2026-09-14.md, test B):
-# a single 60 s closed-loop trial on the 813 KB bar with the simulator, nothing
-# else. Run it as a Test run; the banner at the end is the result.
+# a single 180 s closed-loop trial on the 813 KB bar with the simulator, nothing
+# else (≈ 36k reads at 200 Hz — more than one of the old ~24.5k-read stall periods,
+# so the injected legacy arm has time to stall). Run it as a Test run; the banner at the end is the result.
 #   before:  await Studio.setSdDiag(3)      (inject the stall arm)
 #   after:   await Studio.setSdDiag(0)
 # ============================================================================
 
 experiment_info:
-  name: "Mode-3 drill (one 60 s bar trial)"
+  name: "Mode-3 drill (one 180 s bar trial)"
   author: "webDisplayTools"
 
 rig: "./configs/rigs/cshl_g6_2x10_ball.yaml"
@@ -39,13 +40,15 @@ conditions:
         plugin_name: "fictrac"
         command_name: "connect"
 
+  # The 813 KB, 200-frame bar on the CSHL course card is p3's pattern (036_p3_heisenberg_ts.pat);
+  # names resolve against the card listing, pattern_ID is only the fallback.
   - name: "cl_bar_200f"
     commands:
       - type: "controller"
         command_name: "trialParams"
-        pattern: "frame2_h_ccw_200f"
-        pattern_ID: 4
-        duration: 60
+        pattern: "p3_heisenberg_ts"
+        pattern_ID: 36
+        duration: 180
         mode: 3
         frame_index: 0
         frame_rate: 0
@@ -56,7 +59,7 @@ conditions:
         params:
           gain: 1.8
       - type: "wait"
-        duration: 60
+        duration: 180
       - type: "plugin"
         plugin_name: "fictrac"
         command_name: "stopClosedLoop"
diff --git a/protocols/soak_mode3_stress.yaml b/protocols/soak_mode3_stress.yaml
index 0a403fdc..47ae6dd3 100644
--- a/protocols/soak_mode3_stress.yaml
+++ b/protocols/soak_mode3_stress.yaml
@@ -78,7 +78,7 @@ conditions:
       - type: "controller"
         command_name: "trialParams"
         pattern: "sine_2000f_gs16"
-        pattern_ID: 0
+        pattern_ID: 46
         duration: *cl_dur
         mode: 3
         frame_index: 0
@@ -96,12 +96,14 @@ conditions:
         command_name: "stopClosedLoop"
 
   # The file every bench stall happened on (813 KB, 200 frames) — continuity with the evidence.
+  # The 813 KB, 200-frame bar on the CSHL course card is p3's pattern (036_p3_heisenberg_ts.pat);
+  # names resolve against the card listing, pattern_ID is only the fallback.
   - name: "cl_bar_200f"
     commands:
       - type: "controller"
         command_name: "trialParams"
-        pattern: "frame2_h_ccw_200f"
-        pattern_ID: 4
+        pattern: "p3_heisenberg_ts"
+        pattern_ID: 36
         duration: *cl_dur
         mode: 3
         frame_index: 0

From 58c7692f01a59cef61dbfd5758052c8809b7a27e Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 19:22:41 -0400
Subject: [PATCH 47/67] =?UTF-8?q?feat(studio):=20fill=20pattern=20frame=20?=
 =?UTF-8?q?counts=20from=20GET=5FPATTERN=5FINFO=20after=20the=20SD=20listi?=
 =?UTF-8?q?ng=20=E2=80=94=20the=20closed-loop=20index=20modulus=20for=20ne?=
 =?UTF-8?q?ver-previewed=20(large)=20patterns=20(#201)=20=E2=80=94=20v0.79?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 arena_studio.html                             | 25 ++++++++++++++++++-
 .../development/arena-studio-release-notes.md |  3 +++
 2 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/arena_studio.html b/arena_studio.html
index 2019c70a..a7b6a472 100644
--- a/arena_studio.html
+++ b/arena_studio.html
@@ -2959,7 +2959,7 @@ <h2 id="modalTitle">Import error</h2>
 </div>
 
 <footer id="footer">
-  <span class="foot-left">Arena Studio v0.79 | 2026-09-13 18:56 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.79 | 2026-09-13 19:22 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)">
@@ -7313,7 +7313,30 @@ <h2 id="modalTitle">Import error</h2>
     });
     populatePatDropdown(); // empty set clears the dropdown + unlocks cPat
     Studio.updateRunGate(); // the missing-pattern preflight tracks the SD listing
+    fillPatternFramesFromCard(m); // frame counts via GET_PATTERN_INFO (the closed-loop index modulus)
 };
+// Frame counts for every card pattern from GET_PATTERN_INFO 0x88 (a header read, ~ms each),
+// filled right after the listing so `patternFramesByName` — which the closed-loop resolver
+// pushes to the bridge as the heading→index modulus — is correct for patterns whose preview
+// was never rendered (an 8 MB pattern is never fetched for a thumbnail; the bridge then used
+// its default of 200 and wrapped the index — bench 2026-09-13, #201). Sequential, single-flight,
+// abandons on a new listing, a disconnect or a run (a run owns the link).
+let patFramesGen = 0;
+async function fillPatternFramesFromCard(m) {
+    const gen = ++patFramesGen;
+    const W = window.ArenaWireG6;
+    if (!W || !W.encodeGetPatternInfo || !Studio.session || !Studio.session.connected) return;
+    const todo = Object.values(m.patterns).filter((p) => !(p.preview && Number.isFinite(p.preview.frames)));
+    let n = 0;
+    for (const p of todo) {
+        if (gen !== patFramesGen || !Studio.session.connected || Studio.session.running) return;
+        try {
+            const info = W.decodePatternInfo(await Studio.session.send(W.encodeGetPatternInfo(p.index), { timeoutMs: 1500, silent: true }));
+            if (info && info.frameCount > 0) { p.preview = Object.assign(p.preview || {}, { frames: info.frameCount }); n++; }
+        } catch (_) { /* best effort: the preview path can still fill it later */ }
+    }
+    if (n && gen === patFramesGen) (Studio.clog || Studio.rawLog || function () {})('pattern frame counts read from the card for ' + n + ' pattern' + (n === 1 ? '' : 's') + ' (GET_PATTERN_INFO)', 'dim');
+}
 function wirePatPicker() {
     const sel = $('cPatName');
     if (sel) sel.addEventListener('change', () => {
diff --git a/docs/development/arena-studio-release-notes.md b/docs/development/arena-studio-release-notes.md
index c5d6cc85..94ec083a 100644
--- a/docs/development/arena-studio-release-notes.md
+++ b/docs/development/arena-studio-release-notes.md
@@ -11,6 +11,9 @@ history lives here. Newest first. (Per-session engineering detail stays in
   follows the geometry the controller reports at connect (`GET_FIRMWARE_VERSION` rows × cols): on a 2×10
   controller that is the CSHL fly-on-ball rig. Explicit choices are never overridden; the derived rig's I/O
   power-on defaults are applied.
+- **Frame counts come from the card.** After the SD listing the Studio reads every pattern's header
+  (`GET_PATTERN_INFO`), so the closed-loop heading→index modulus is right for patterns whose thumbnail
+  was never rendered (an 8 MB pattern used to fall back to 200 frames and wrap).
 - **Banner when the SD diagnostic switches are on at connect** (`SET_SD_DIAG` readback ≠ 0): the switches persist
   until a controller reboot and silently degrade every trial; the banner names the arm and how to clear it.
 

From 5d25939da56e240788c5e35cf4fab10822a2b216 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 19:31:14 -0400
Subject: [PATCH 48/67] =?UTF-8?q?docs(bench=20log):=20drill=20step=201=20?=
 =?UTF-8?q?=E2=80=94=20course-card=20pattern=20names,=20soak-path=20log=20?=
 =?UTF-8?q?completeness=20confirmed,=20legacy=20arm=20clean=20at=20fast-pa?=
 =?UTF-8?q?th=20cost=20(investigating)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/development/mode3-wedge-soak-plan.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/docs/development/mode3-wedge-soak-plan.md b/docs/development/mode3-wedge-soak-plan.md
index f5413a33..3de16004 100644
--- a/docs/development/mode3-wedge-soak-plan.md
+++ b/docs/development/mode3-wedge-soak-plan.md
@@ -547,6 +547,20 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   log shows the g6_3x10 io defaults applied first, then re-applied for the derived rig one second later — ordering
   follow-up, same io values), sd card line, `sdDiag` 0, telemetry available. 19:17 drill step 1: `setSdDiag(3)` +
   one-trial drill protocol (`protocols/mode3_drill_1trial.yaml`).
+- **2026-09-13 19:17–19:30 ET — drill step 1 (injected stall), two runs.** (a) 60 s Test run via `runOnce(false)`:
+  ran **pattern 4** (`p100_slow_bar`), not the bar — the bench card is the COURSE card (36 = `p3_heisenberg_ts`, the
+  813 KB/200-frame file used all day; 5 = `course_grating_36deg`; 46 = the sine) and the protocols' names
+  `frame2_h_ccw_200f`/`grating_sq` do not exist on it, so they fell back to `pattern_ID`; the Test-run log had no
+  `run_metadata` and v1-style `arena_command` objects instead of `a` rows. Fixed the protocols (names + ids 36/46,
+  drill 180 s) and documented "drill via a 1-iteration soak". (b) **180 s via the soak driver, arm 3 (legacy seek +
+  no skip), pattern 36: 34,903 commands, 34,904 reads, reads/cmd 1.00, sd_layout = legacy applied + no-skip —
+  0 stalls, worst read 2.0 ms, −1 step p50 1.39 ms (the FAST-path cost; the same arm showed 2.0 ms and clusters
+  every 23k reads at 15:00 on `75405ee`).** Log completeness on this soak-path file: `run_metadata` (label
+  `488d5b9b…`, card + arm), 34,905 `a` rows vs 34,903 `cc`, drainer gaps/notStored/errors 0, `trial_quality` AFTER
+  the last controller row → **the v0.78 export-ordering fix confirmed on a real run**; `runlog-check` fails it only
+  for the expected arm ≠ 0. Frame-count-from-0x88 fill added to the Studio (v0.79) — the sine would otherwise have
+  run with the bridge's 200-frame default modulus tonight. 19:32: harness arm 3 on `488d5b9` to see whether the
+  legacy arm stopped biting because of the Studio path or the build.
 
 ## 11. T4 as built (2026-09-12) — soak with ring-buffer logging
 

From aa0712ce58e3a67ed60e59a4e24035c0c023839c Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 19:35:48 -0400
Subject: [PATCH 49/67] docs: the 20-frame-modulus finding (stale bridge
 frames) and T8 index-coverage criterion; bench log

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/development/mode3-wedge-soak-plan.md               | 8 ++++++++
 docs/development/overnight-soak-test-plan-2026-09-13.md | 1 +
 2 files changed, 9 insertions(+)

diff --git a/docs/development/mode3-wedge-soak-plan.md b/docs/development/mode3-wedge-soak-plan.md
index 3de16004..94d56683 100644
--- a/docs/development/mode3-wedge-soak-plan.md
+++ b/docs/development/mode3-wedge-soak-plan.md
@@ -561,6 +561,14 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   for the expected arm ≠ 0. Frame-count-from-0x88 fill added to the Studio (v0.79) — the sine would otherwise have
   run with the bridge's 200-frame default modulus tonight. 19:32: harness arm 3 on `488d5b9` to see whether the
   legacy arm stopped biting because of the Studio path or the build.
+- **2026-09-13 19:35 ET — RESOLVED: the Studio drill ran a 20-frame loop.** Harness arm 3 on `488d5b9`, 3 min,
+  pattern 36: −1 step 1.99 ms, 1 stall (21.8 ms) → the build and the arm are fine. Index coverage: harness 200
+  distinct frames, uniform; **Studio drill: frames 0–19 only** — the bridge's heading→index modulus was still 20
+  (the last `config.frames` it had received, the grating this morning) because the Studio had no frame count for
+  `p3_heisenberg_ts` and passed none. 20 frames = 80 KB inside one FAT sector → no chain walk, no stall, fast-path
+  costs. The frames-from-`GET_PATTERN_INFO` fill (v0.79, 19:25) is the fix; without it the overnight would have run
+  every pattern as a 20-frame loop. Lesson for the test plan: **index coverage (distinct frames per trial) is a
+  pass criterion**, added as T8.
 
 ## 11. T4 as built (2026-09-12) — soak with ring-buffer logging
 
diff --git a/docs/development/overnight-soak-test-plan-2026-09-13.md b/docs/development/overnight-soak-test-plan-2026-09-13.md
index 30e7bebc..10e0e011 100644
--- a/docs/development/overnight-soak-test-plan-2026-09-13.md
+++ b/docs/development/overnight-soak-test-plan-2026-09-13.md
@@ -20,6 +20,7 @@ iterations, ≈ 560 trials, ≈ 6 M frame commands.
 | T4 | **Round trip host-side** | `a`-row `dt` p50 / p99 | `a` rows | p99 ≤ 11 ms (Codex-agreed bound from #198), no upward trend | `wedge-scan.py` RTT columns |
 | T5 | **Refresh cadence holds under load** | presented frames per second; `superseded` share; `timer_fail` | `cf` count / trial duration; `cf` field 10; `cs` kind 10 | ≈ commands with an index change; superseded < 2 % at 200 Hz; 0 `timer_fail` | `telemetry-report.py` (presentation section) |
 | T6 | **Per-read cost, both files** (no size dependence) | SD read µs by step class (+1 / −1 / small / jump), sine vs bar | `cf` `sd_load_us` | +1 ≈ 0.62 ms; random ≤ 1.5 ms p50, ≤ 1.8 ms max, sine ≈ bar | `telemetry-report.py` step-class table |
+| T8 | **The trial actually swept the file** (the drill on 2026-09-13 silently ran a 20-frame loop of a 200-frame pattern when the bridge had a stale modulus) | distinct frame indices per trial; index max | `cf` field 4 | bar ≥ 190 of 200, sine ≥ 1900 of 2000 distinct indices in every 60 s trial | `telemetry-report.py` (add the coverage column) / `runlog-check.py` |
 | T7 | **Watchdog never fires** | boot count, `boot` STATE records, HEALTH `wdogFlags` "previous reset was watchdog" | ring header `boot_count` (soak `telemetry` stats), `cs` kind 1, morning `GET_HEALTH` | boot_count unchanged all night; 0 boot records; flag clear | soak events + Console health read in the morning |
 
 ## 2. The log files are complete

From de303302d508047b6b38cacf971fe4e0ee1e291d Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 19:52:18 -0400
Subject: [PATCH 50/67] =?UTF-8?q?fix(sim):=20FicTrac=20field=2022=20is=20n?=
 =?UTF-8?q?anoseconds=20=E2=80=94=20the=20simulator=20wrote=20ms,=20so=20e?=
 =?UTF-8?q?very=20sim=20log's=20ft=20was=201000=C3=97=20too=20small=20(fou?=
 =?UTF-8?q?nd=20by=20the=20telemetry=20logging=20review)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 fictrac-bridge/fictrac_sim.py | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/fictrac-bridge/fictrac_sim.py b/fictrac-bridge/fictrac_sim.py
index e55a8042..f93d88b2 100644
--- a/fictrac-bridge/fictrac_sim.py
+++ b/fictrac-bridge/fictrac_sim.py
@@ -146,7 +146,10 @@ def next_record(self) -> list[float]:
         fields[18] = speed  # 19 movement speed
         fields[19] = self.fwd  # 20-21 integrated fwd/side
         fields[20] = self.side
-        fields[21] = ts_ms  # 22 timestamp
+        # FicTrac writes field 22 in NANOSECONDS; the bridge divides it by FT_TS_NS_PER_MS to get ms
+        # (every simulator log before 2026-09-13 had ft 1000× too small — found by the telemetry
+        # logging review). Field 25 stays in ms as FicTrac's "ms since midnight".
+        fields[21] = ts_ms * 1_000_000.0  # 22 timestamp (ns)
         fields[22] = seq  # 23 sequence counter
         fields[23] = delta_ms  # 24 delta ms
         fields[24] = abs_ms  # 25 abs ms since midnight

From 78ca119f8f8182e53e183572066007c09cf3c329 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 19:54:52 -0400
Subject: [PATCH 51/67] =?UTF-8?q?fix(studio):=20bind=20the=20stimulus-qual?=
 =?UTF-8?q?ity=20finalize=20to=20its=20run=20id=20=E2=80=94=20a=20previous?=
 =?UTF-8?q?=20run's=20late=20terminal=20event=20no=20longer=20finalizes=20?=
 =?UTF-8?q?the=20next=20run's=20trials=20(bench=202026-09-13);=20runlog-ch?=
 =?UTF-8?q?eck=20wording=20=E2=80=94=20v0.79?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 arena_studio.html                              | 16 ++++++++++++----
 docs/development/arena-studio-release-notes.md |  3 +++
 scripts/runlog-check.py                        |  2 +-
 3 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/arena_studio.html b/arena_studio.html
index a7b6a472..2434d219 100644
--- a/arena_studio.html
+++ b/arena_studio.html
@@ -2959,7 +2959,7 @@ <h2 id="modalTitle">Import error</h2>
 </div>
 
 <footer id="footer">
-  <span class="foot-left">Arena Studio v0.79 | 2026-09-13 19:22 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.79 | 2026-09-13 19:54 ET| 2026-09-13 19:22 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)">
@@ -3345,7 +3345,7 @@ <h2 id="modalTitle">Import error</h2>
         // per-trial `trial_quality` verdict must be written FIRST (whole-stack review,
         // 2026-09-13: they used to land after the export and were lost from committed logs).
         const finalizeThenCommit = async () => {
-            try { if (Studio.finalizeTrialQuality) await Studio.finalizeTrialQuality(); } catch (_) { /* best effort */ }
+            try { if (Studio.finalizeTrialQuality) await Studio.finalizeTrialQuality(log.meta && log.meta.run_id); } catch (_) { /* best effort */ }
             await maybeCommitRunLog(log, summary);
         };
         if (summary && summary.outcome === 'CONTROLLER_FAULT' && Studio.handleControllerFault) {
@@ -8237,7 +8237,11 @@ <h2 id="modalTitle">Import error</h2>
 // export closes the file. Called from onRunFinished (before the commit) and from runSteps (a
 // fallback); runs once per run — later callers await the first. Flag only — excluding or
 // repeating a trial is the experimenter's decision (selection-bias caveat, Codex review).
-Studio.finalizeTrialQuality = function () {
+Studio.finalizeTrialQuality = function (runId) {
+    if (runId !== undefined && runId !== Studio._tqRunId) {
+        Studio.rawLog('stimulus quality: ignoring a finalize for a previous run (' + runId + ')', 'dim');
+        return Promise.resolve(null); // stale caller: a previous run's terminal event
+    }
     if (Studio._tqFinal) return Studio._tqFinal;
     Studio._tqFinal = (async () => {
         if (!Studio.trialQuality) return null;
@@ -8745,6 +8749,10 @@ <h2 id="modalTitle">Import error</h2>
     Studio._linkDropped = false;
     if (Studio.trialQuality) Studio.trialQuality.reset(); // per-trial stimulus-quality verdicts start fresh
     Studio._tqFinal = null; // finalizeTrialQuality() runs once per run (first caller wins, others await it)
+    // Bind the verdict to THIS run: a late terminal event from a previous (aborted) run must not finalize
+    // this one's trials — bench 2026-09-13: an overlapping start let the old run's finalize close the new
+    // run's trials one second in, and the real stall went unjudged.
+    Studio._tqRunId = (Studio.activeRunLog && Studio.activeRunLog.meta && Studio.activeRunLog.meta.run_id) || ('run-' + Date.now());
     try {
         // NOTE: do NOT pass onProgress — the session broadcasts 'runstatus' which
         // Studio.onRunStatus (subscribed once) consumes, so the log/highlight stay
@@ -8778,7 +8786,7 @@ <h2 id="modalTitle">Import error</h2>
         }
         // Stimulus quality: normally already finalized by onRunFinished (before the export);
         // this is the fallback for runs without a run log (Test runs).
-        await Studio.finalizeTrialQuality();
+        await Studio.finalizeTrialQuality(Studio._tqRunId);
     } catch (e) {
         Studio.rawLog('run error: ' + (e && e.message ? e.message : e), 'err');
         if (Studio.activeRunLog && !Studio.activeRunLog.summary) {
diff --git a/docs/development/arena-studio-release-notes.md b/docs/development/arena-studio-release-notes.md
index 94ec083a..078ba03a 100644
--- a/docs/development/arena-studio-release-notes.md
+++ b/docs/development/arena-studio-release-notes.md
@@ -14,6 +14,9 @@ history lives here. Newest first. (Per-session engineering detail stays in
 - **Frame counts come from the card.** After the SD listing the Studio reads every pattern's header
   (`GET_PATTERN_INFO`), so the closed-loop heading→index modulus is right for patterns whose thumbnail
   was never rendered (an 8 MB pattern used to fall back to 200 frames and wrap).
+- **The stimulus-quality verdict is bound to its run.** A late terminal event from a previous, aborted run
+  can no longer finalize the next run's trials (it did once on the bench, one second into a drill, and
+  the real stall went unjudged).
 - **Banner when the SD diagnostic switches are on at connect** (`SET_SD_DIAG` readback ≠ 0): the switches persist
   until a controller reboot and silently degrade every trial; the banner names the arm and how to clear it.
 
diff --git a/scripts/runlog-check.py b/scripts/runlog-check.py
index 9be39b3c..cd4322bc 100644
--- a/scripts/runlog-check.py
+++ b/scripts/runlog-check.py
@@ -70,7 +70,7 @@ def check_file(path):
         for g in gaps:
             if g.get("trial") not in flagged: p.append(f"display_gap for trial {g.get('trial')} but that trial is not flagged")
     c["cc_0x70_ok"] = cc70; c["a_ok"] = a_ok
-    if cc70 and a_ok and abs(cc70 - a_ok) > 2: p.append(f"controller-accepted 0x70 {cc70} vs host-accepted {a_ok}: drain lost records")
+    if cc70 and a_ok and abs(cc70 - a_ok) > 2: p.append(f"controller-accepted 0x70 {cc70} vs host-accepted {a_ok} differ by {abs(cc70 - a_ok)} (a drain gap if a > cc; a second run in the same file if cc > a)")
     if iter_end and isinstance(iter_end.get("telemetry"), dict):
         t = iter_end["telemetry"]; c["drainer"] = {k: t.get(k) for k in ("dropped", "gaps", "notStored", "errors", "records")}
         # `dropped` is the controller's CUMULATIVE ring-overrun counter: records evicted while nobody drained —

From 112c80fe7e5a064f1c148a53d7b5f3843eb9e846 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 19:56:00 -0400
Subject: [PATCH 52/67] =?UTF-8?q?fix(studio):=20footer=20stamp=20(a=20sed?=
 =?UTF-8?q?=20with=20-E=20treated=20\|=20as=20alternation=20and=20duplicat?=
 =?UTF-8?q?ed=20the=20stamp)=20=E2=80=94=20v0.79?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 arena_studio.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/arena_studio.html b/arena_studio.html
index 2434d219..5448aa73 100644
--- a/arena_studio.html
+++ b/arena_studio.html
@@ -2959,7 +2959,7 @@ <h2 id="modalTitle">Import error</h2>
 </div>
 
 <footer id="footer">
-  <span class="foot-left">Arena Studio v0.79 | 2026-09-13 19:54 ET| 2026-09-13 19:22 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.79 | 2026-09-13 19:55 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)">

From b3bdc14623035542fa61a4b2b2962491b1a738e6 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 19:56:23 -0400
Subject: [PATCH 53/67] docs(bench log): drill exposes the overlapping-run
 finalize bug (fixed), sim ft fix, retry

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/development/mode3-wedge-soak-plan.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/docs/development/mode3-wedge-soak-plan.md b/docs/development/mode3-wedge-soak-plan.md
index 94d56683..ec3ba71c 100644
--- a/docs/development/mode3-wedge-soak-plan.md
+++ b/docs/development/mode3-wedge-soak-plan.md
@@ -569,6 +569,15 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   costs. The frames-from-`GET_PATTERN_INFO` fill (v0.79, 19:25) is the fix; without it the overnight would have run
   every pattern as a 20-frame loop. Lesson for the test plan: **index coverage (distinct frames per trial) is a
   pass criterion**, added as T8.
+- **2026-09-13 19:49–19:55 ET — drill via the reloaded Studio (frame counts from the card: bar 200, sine 2000;
+  index coverage 200/200):** the legacy arm now bit through the Studio path too — −1 step 1.99 ms, **one 18.3 ms
+  body-phase stall** in 35.7k reads. But the Studio's verdict said `pass` with two phantom trials: my two start
+  commands overlapped; the first soak was aborted and its LATE terminal event finalized the second run's trials one
+  second in (v0.78 finalize memoised per run, reset at run start, so the second run's own finalize was a no-op and the
+  stall was fed with no open trial). **Fixed (v0.79): the finalize is bound to the run id; a stale caller is
+  ignored.** Also fixed: simulator field 22 written in ms instead of ns (every sim log's `ft` was 1000× too small;
+  found by the telemetry-review session) — sim restarted 19:55 with the fix; a footer stamp mangled by `sed -E`.
+  `pixi run test` green. Retrying the drill with a single start.
 
 ## 11. T4 as built (2026-09-12) — soak with ring-buffer logging
 

From 8a53461b6eb9b5351232ad6ef6f9a7cbeca27994 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 20:09:59 -0400
Subject: [PATCH 54/67] =?UTF-8?q?docs:=20telemetry=20&=20run-log=20referen?=
 =?UTF-8?q?ce=20=E2=80=94=20rows/events,=20three-clock=20model,=20round-tr?=
 =?UTF-8?q?ip=20recipe=20(+=20figures)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

One format authority for behavior_v2 run logs as built in Studio v0.79 / bridge 3.1 /
fw candidate 488d5b9: every row (FicTrac, a, cc, cf 8|11, cs kinds 1–14) and event with
producer citations and real example lines; timestamp merging (rx = browser drain time per
block, a↔cc order join, seq rule, pair-by-order fit); the closed-loop latency recipe with
the two non-derivable links; readers/tools; ranked Teensy-first instrumentation gaps.
HTML companion carries the clock swimlane and latency-chain figures. Pointers added in
CLAUDE.md, runlog-behavior-v2-plan.md, oscilloscope-view-spec.md; design-record header
on the ring proposal.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 CLAUDE.md                                     |  11 +-
 ...ntroller-telemetry-ring-buffer-proposal.md |   9 +-
 docs/development/oscilloscope-view-spec.md    |   2 +
 docs/development/runlog-behavior-v2-plan.md   |   3 +
 .../telemetry-logging-reference.md            | 347 ++++++++++++++++++
 docs/development/telemetry-reference.html     | 172 +++++++++
 6 files changed, 539 insertions(+), 5 deletions(-)
 create mode 100644 docs/development/telemetry-logging-reference.md
 create mode 100644 docs/development/telemetry-reference.html

diff --git a/CLAUDE.md b/CLAUDE.md
index eab9177b..eb244ba2 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -347,16 +347,19 @@ fix flows to every page automatically; two hand-written HTML pages never will.
   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.
+  `run_metadata` from anything but the acked/inferred level. **The format authority for every
+  row and event (FicTrac rows, `a`, controller `cc`/`cf`/`cs`, all `{type:"log"}` events), the
+  three-clock model and the round-trip recipe is `docs/development/telemetry-logging-reference.md`.**
 - **Controller telemetry rows + stimulus quality (v0.77, fw `sdfast`):** `cf` rows carry three OPTIONAL trailing fields
   (`req_age_us`, `superseded`, `flags`) from ring-v2 firmware (0xCB flags bit 5) — readers must accept 8- or
   11-element `cf` rows and STATE kinds 11–13 (`sd_layout`/`sd_slow_ctx`/`sd_reads`, reads = arg << code). `GET_SD_INFO`
   0xCD is gated on 0xCB bit 5 only. Per-trial pass/flagged/unknown verdicts come from `js/trial-quality.js` (fed from
   the drainer in ring order, dedup by seq; fail = any read or request age > 10 ms; `unknown` never becomes `pass`) →
   `display_gap` + `trial_quality` run-log events; the Studio flags, never auto-excludes. Offline analysis:
-  `scripts/telemetry-report.py` (also reads the firmware repo's `scripts/sd_stall_test.py` logs). The card stalls
-  themselves are card-internal (read-count maintenance, ~24.5k reads of a large file); see
-  `docs/development/archive/mode3-2026-09/sd-read-jitter-2026-09-13.md`.
+  `scripts/telemetry-report.py` (also reads the firmware repo's `scripts/sd_stall_test.py` logs). The 30–90 ms card stalls were
+  firmware FAT access (chain-walking seeks + `fatGet` at cluster crossings), proven by the 4-arm causal test on 2026-09-13 and
+  removed by the contiguous-seek fast path — never re-introduce per-seek chain walks; see
+  `docs/development/mode3-reliability-handoff-2026-09-14.md`.
 - Bump the footer version/timestamp on every edit; never Prettier the HTML.
 
 - **Telemetry ring — four rules from the 2026-09-12 Codex review (all tested):** (1) the ONLY gate
diff --git a/docs/development/controller-telemetry-ring-buffer-proposal.md b/docs/development/controller-telemetry-ring-buffer-proposal.md
index 116fb835..68ad47d6 100644
--- a/docs/development/controller-telemetry-ring-buffer-proposal.md
+++ b/docs/development/controller-telemetry-ring-buffer-proposal.md
@@ -1,6 +1,13 @@
 # Controller telemetry ring buffer — feasibility + test proposal
 
-Drafted 2026-09-07 17:38 ET (Michael + Claude). Status: **proposal, no code**. Companion to
+> **Design record (2026-09-13).** The ring shipped (fw `feat/telemetry-ring` → `488d5b9`; Studio v0.76+). As built it
+> differs from §3: FRAME is 26 B with `sd_load_us`/`req_age_us` u32, run-log rows are `[tag, rx, t_us, seq, …]` (no
+> `t_off`/`rx_off`, no `ct` tick rows), there is no `GET_CLOCK`, and the gate is 0xCB flag bit 2 (not 0xC2 bit 7).
+> The as-built layouts, clock model and latency recipe are in
+> [`telemetry-logging-reference.md`](telemetry-logging-reference.md); §5 (T1–T6) and §9 (L1–L4) here remain the
+> bench/instrument plans.
+
+Drafted 2026-09-07 17:38 ET (Michael + Claude). Status at drafting: **proposal, no code**. Companion to
 `docs/development/analog-acquisition-handover.md` (§ 3.2 F3 / § 3.3 S4, the analog block
 stream) and to Linear **LAB-149** ("controller and panel diagnostics with a retrievable
 event log"). This document answers one question — *can the G6 controller keep an event log
diff --git a/docs/development/oscilloscope-view-spec.md b/docs/development/oscilloscope-view-spec.md
index aec3ff49..25b3bc39 100644
--- a/docs/development/oscilloscope-view-spec.md
+++ b/docs/development/oscilloscope-view-spec.md
@@ -1,6 +1,8 @@
 # Live Oscilloscope View — Specification
 
 **Status:** ✅ IMPLEMENTED in Arena Studio v0.15 (2026-07-07). As-built notes below.
+Run-log format authority (all rows and events, `behavior_v2` + controller streams):
+[`telemetry-logging-reference.md`](telemetry-logging-reference.md).
 
 > **As built (2026-07-07) — the §3 data contract changed.** Per the #140 decision
 > (comment 4900650706) the bridge now forwards + logs the **`behavior_v1`** schema
diff --git a/docs/development/runlog-behavior-v2-plan.md b/docs/development/runlog-behavior-v2-plan.md
index 0be92009..327a9655 100644
--- a/docs/development/runlog-behavior-v2-plan.md
+++ b/docs/development/runlog-behavior-v2-plan.md
@@ -7,6 +7,9 @@ at the end. None bench-tested yet. **Merge order:** PR 3 (readers) must be live
 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.
 
+> **Format authority:** the as-built row/event catalogue, clock model and latency recipe are in
+> [`telemetry-logging-reference.md`](telemetry-logging-reference.md). This file keeps the design rationale.
+
 ## Problem
 
 The Studio commits run logs through GitHub's Contents API, which rejects files over
diff --git a/docs/development/telemetry-logging-reference.md b/docs/development/telemetry-logging-reference.md
new file mode 100644
index 00000000..0941d36e
--- /dev/null
+++ b/docs/development/telemetry-logging-reference.md
@@ -0,0 +1,347 @@
+# Telemetry & run-log reference — what is logged, how the clocks merge, how to compute round-trip latency
+
+**Status:** authoritative for the current stack (2026-09-13). Describes **Arena Studio v0.79** (`claude/mode3-perf-sd`
+@ `e64bb33`, PRs #198 + #202 → `main`), **fictrac-bridge 3.1**, and the firmware **merge candidate `488d5b9`**
+(`feat/mode3-reliability`, fw PR #56; ring v2; 0xCB flags `0x7C`). Firmware citations use the bench-build history
+`feat/sd-fastpath-2x10` @ `75405ee`, whose `src/` is byte-identical to `488d5b9` except the per-board variant headers.
+Every row shape below was checked against the code AND against real logs (`soak-logs/arena-log-20260913-120611-713.jsonl`
+— 5.06 M lines, fw `3c71953`, Studio v0.77 — plus `…-114448-137.jsonl`, `soak-logs/wedges/wedge6-*.jsonl.gz` and a
+committed `.jsonl.gz` protocol run from rig05). Diagrams: [`telemetry-reference.html`](telemetry-reference.html).
+
+Companion docs (do not duplicate them): [`mode3-reliability-handoff-2026-09-14.md`](mode3-reliability-handoff-2026-09-14.md)
+(the narrative; §7.2 = the four parsing rules), [`runlog-format-review-2026-09-13.md`](runlog-format-review-2026-09-13.md)
+(bytes per hour, compaction plan R1–R4), firmware `README.md` (byte tables: "Telemetry ring", "Health + breadcrumb",
+"SD fast path", "Build identity"), [`runlog-behavior-v2-plan.md`](runlog-behavior-v2-plan.md) (why `behavior_v2` exists).
+
+**Acceptance numbers (Michael):** display freeze **5 ms target, 10 ms worst case; ≥ 30 ms is a visible artifact.**
+`js/trial-quality.js` defaults `target_us = 5000`, `threshold_us = 10000`; firmware `kSdSlowThresholdUs = 10000`.
+
+---
+
+## 0. What is where (one paragraph)
+
+FicTrac (or `fictrac_sim.py`) → UDP → **bridge** (`fictrac-bridge/bridge.py`, Python, same PC as the browser) → WebSocket
+→ **Studio** (browser; owns the Web Serial port) → USB CDC → **controller** (Teensy 4.1) → SPI → panels. The bridge
+writes ONE NDJSON file per logging session. It originates the FicTrac rows and the session/schema lines; **everything
+else in the file is sent by the browser** over the WebSocket — protocol events as `{type:"log", event:…}` objects, and
+the controller's telemetry ring as pre-decoded array rows (`{type:"rows"}`). The controller never talks to the bridge.
+
+On `main` today (Studio v0.74) none of the controller streams exist; a `main` reader that meets a `cc`/`cf`/`cs` row
+must skip it (rule 2 in the hand-off §7.2). After #198 merges, all readers below are on `main`.
+
+## 1. File anatomy
+
+| line | who writes | shape | source |
+|---|---|---|---|
+| 1 | bridge | `{"type":"session","event":"logging_started","file":"<name>","ms":<epoch ms>}` | `bridge.py:603` `_open` |
+| 2 | bridge | `{"type":"frame_schema","level":"behavior_v2","cols":["ms","fc","idx","ft","x","y","hd"],"arena_cols":["t_off","dt","hex","status","rx_off"],"t0":<epoch ms>}` — **`t0` = line 1's `ms`**, the origin of every `_off` field | `bridge.py:204` |
+| 3 | browser (echoed) | `{"type":"log_control","enabled":true,"level":"behavior_v2","dir":"browser→bridge","rx_ms":…}` | `bridge.py:935` |
+| … | interleaved | numeric FicTrac rows · `["a",…]` · `["cc"\|"cf"\|"cs",…]` · `{type:"log",…}` events · `{type:"config"}` / `{type:"hello"}` echoes | §2, §3 |
+| last | bridge | `{"type":"session","event":"logging_stopped","ms":…}` | `bridge.py:714` |
+
+- **Event envelope.** Every browser `{type:"log", event:X, …}` passes through `write_inbound` (`bridge.py:673`), which
+  adds `dir:"browser→bridge"` and `rx_ms` (bridge wall clock at receipt). Browser control messages (`hello`, `config`,
+  `log_control`) are echoed the same way. **`{type:"rows"}` batches are NOT enveloped** — `write_rows` (`bridge.py:655`)
+  writes each array verbatim after a shape check (`ROW_MIN_LEN = {cc:7, cf:8, cs:7}`, `bridge.py:550`).
+- **Levels.** `behavior_v2` (default, this document) · `behavior_v1` (same rows, `arena_command` as objects, no
+  `frame_schema.t0`) · `full` (25-column FicTrac objects). Advertised in `hello_ack {bridge, levels, level, logging}`
+  (`bridge.py:912`).
+- **Rotation + ack.** `log_control{enabled:true, level}` → `set_level`, `reset_base()` (re-zeroes the FicTrac `ms`
+  origin and `ft0`, `bridge.py:738`), `start_new_log()` → a fresh `arena-log-YYYYmmdd-HHMMSS-mmm.jsonl` in `--log-dir`
+  (default: the bridge's CWD; `--log <file>` appends instead). `enabled:false` closes the file. The bridge replies
+  `log_control_ack {enabled, level, requested, file}` (`bridge.py:952`) **to the asking client only — it is a socket
+  message, never a log line.** Studio waits ≤ 800 ms for it (`arena_studio.html:8687`); with no ack it assumes
+  `behavior_v1` and writes that into `run_metadata.log_format`.
+- **Commit path.** At run end Studio gzips the bridge's export and commits `runlogs/<bench>/<name>.jsonl.gz`
+  (`GH.commitFile`; > 30 MiB via the Git Database API). Readers inflate on the `1f 8b` magic (`js/runlog-format.js`
+  `readRunlogText`). **v0.78 guarantee:** the final ring drain and the `trial_quality` event are written **before** the
+  export, on normal and on fault runs (v0.77 files can have controller rows after `trial_quality` — see §7).
+
+## 2. Row catalogue (arrays)
+
+All examples are verbatim lines from `arena-log-20260913-120611-713.jsonl` unless noted. "Clock" names the owner of the
+stamp — see §5.
+
+### 2.1 FicTrac behaviour sample — `[ms, fc, idx, ft, x, y, hd]` (7 fields, first element numeric)
+
+`[3,9002558,6,0.0,38.98338,405.69664,0.82451]`
+
+| field | type | clock | meaning | source |
+|---|---|---|---|---|
+| `ms` | int ms | bridge wall (`time.time()`) | receipt of the FicTrac packet, relative to the last `log_control{enabled:true}` (re-zeroed per activation, so it restarts at 0 on every run/soak iteration) | `bridge.py:775`, `:738` |
+| `fc` | int | FicTrac | frame counter (FicTrac col 1) | `behavior_v1_row`, `bridge.py:147` |
+| `idx` | int | derived | frame index the bridge computed from heading: `round((deg(hd)+offset)/gain) mod frames`; `gain`/`offset`/`frames` come from the browser's `{type:"config"}` message (pushed per trial by the runner); `0` when gain is unset | `bridge.py:465` |
+| `ft` | float ms or `null` | **FicTrac camera clock** | FicTrac col 22 minus its value on the first frame after activation, **÷ 1 000 000 (ns → ms)**; `null` if the record has < 22 fields | `bridge.py:140,147` |
+| `x`, `y`, `hd` | float (5 dp) | — | FicTrac cols 15, 16, 17 (integrated x/y, heading rad) | `bridge.py:147` |
+
+**Caveat — simulator `ft` in logs before 2026-09-13 evening.** `fictrac_sim.py` used to fill col 22 in
+**milliseconds** while the bridge divides by 1e6 expecting ns, so every simulator-driven log up to and including the
+2026-09-13 soaks has `ft` ≈ 1000× too small (the 1280 s run above ends at `ft = 21.962`; the first ~100 frames read
+`0.0`). Fixed on `claude/mode3-perf-sd` @ `f16e67e` (col 22 written in ns; sim restarted before the overnight run).
+For older sim logs use `ms`, not `ft`. Real-FicTrac `ft` (ns) has not yet been checked on a rig.
+
+### 2.2 Host arena-command echo — `["a", t_off, dt, hex, status, rx_off(, error)]` (6 or 7 fields)
+
+Studio path: `["a",20,2,"03700100",0,22]` · harness path (`sd_stall_test.py`): `["a",312.652,2.285,"03 70 02 00",0,314.953]`
+
+| field | type | clock | meaning | source |
+|---|---|---|---|---|
+| `t_off` | int ms | browser `Date.now()` − bridge `t0` | time the command entered the host send queue (before the single-flight link wait) | `js/arena-session.js:363`; subtraction `bridge.py:259` |
+| `dt` | int ms | browser `performance.now()` | send-queue entry → reply decoded, **including queue wait** behind the previous command | `js/arena-session.js:408` |
+| `hex` | string | — | request bytes `len cmd …` (≤ 8 B); Studio logs are unspaced (the bridge strips spaces), the firmware harness writes spaced | `bridge.py:259` |
+| `status` | int or `null` | — | reply status byte; `null` = no decodable reply (host timeout ≈ 500 ms — a `dt` near 500 with `null` is the timeout, not a measured RTT) | `js/arena-session.js:391` |
+| `rx_off` | int ms | bridge wall − `t0` | when the bridge received the echo (after the reply) | `bridge.py:673` |
+| `error` | string | — | 7th element only on failure | `bridge.py:259` |
+
+- One `a` row per non-silent `session.send` — the 0x70 stream, TRIAL_PARAMS, STOP, etc. Silent sends (the 0xA9 ring
+  drain, the analog-in poller, GET_HEALTH probes) are not echoed.
+- **Requests longer than 8 bytes** (TRIAL_PARAMS 0x08 = 14 B) cannot be compacted (`head` ends in `…`) and are written
+  as the v1 object: `{"type":"log","event":"arena_command","t":<epoch>,"dt":6,"len":14,"head":"0d 08 03 24 00 00 00 00 …","status":0,"echo":8,"ok":true,"error":null,"dir":…,"rx_ms":…}`
+  (`bridge.py:217,259`). `expandV2Line` / `compactV1Line` in `js/runlog-format.js` are the exact inverses.
+- **No field links an `a` row to the FicTrac frame that caused it** (the `fc` → 0x70 gap, §6).
+
+### 2.3 Controller command record — `["cc", rx, t_us, seq, cmd, status, req]` (7 fields)
+
+`["cc",1789315572700,1860411193,427767,8,0,"0324000000000000"]`
+
+| field | type | clock | meaning | source |
+|---|---|---|---|---|
+| `rx` | float epoch ms | **browser `Date.now()`** | when the 0xA9 block containing this record was parsed — **one value for every record of the block**, up to ~100 ms after the event (10 Hz poll); NOT the command's time, NOT a bridge stamp | `js/arena-telemetry.js:341`, `:222` |
+| `t_us` | u32 µs | controller `micros()` | **receipt of the command, before dispatch** (`t_rx_us`); wraps every 71.6 min | fw `CommandProcessor.cpp:142`, `:984` |
+| `seq` | u32 | controller | ring append order; contiguous unless records were evicted | fw `Telemetry.cpp` `append` |
+| `cmd` | int | — | opcode (8 = TRIAL_PARAMS, 112 = 0x70 SET_FRAME_POSITION, …) | |
+| `status` | int | — | the reply's status byte | fw `CommandProcessor.cpp:984` |
+| `req` | hex string | — | first ≤ 8 request bytes **after** `len cmd` (so a 0x70 for index 45 is `"2d00"` while the `a` row has `"03702d00"`) | fw README "Telemetry ring" |
+
+Not recorded by the firmware: 0xA9 itself, 0x32 stream frames, 0x85/0xE0 bulk headers, 0x01 SYSTEM_RESET.
+
+### 2.4 Displayed frame change — `["cf", rx, t_us, seq, idx, pattern, sd_load_us, spi_us, req_age_us, superseded, flags]` (11 fields; **8 on ring-v1 firmware**)
+
+`["cf",1789315572700,1860419028,427768,0,36,1340,776,4833,0,3]`
+
+| field | type | clock | meaning | source |
+|---|---|---|---|---|
+| `rx`, `seq` | | | as `cc` | |
+| `t_us` | u32 µs | controller | **start of the SPI transfer** that put this frame on the panels | fw `CommandProcessor.cpp:1763` |
+| `idx`, `pattern` | u16 | — | frame index and SD pattern id now displayed | |
+| `sd_load_us` | u32 µs | controller | duration of the SD read that produced the buffer (`last_sd_read_us`) | |
+| `spi_us` | u16 µs (sat.) | controller | transfer duration (~776 µs on a 2×10) | |
+| `req_age_us` | u32 µs | controller | dispatch of the 0x70 that requested this frame (Mode 2/4: the `loadFrame` decision) → SPI start. **The request→presentation latency, measured on one clock.** | fw `CommandProcessor.h:104` |
+| `superseded` | u8 | — | SD frames loaded into the buffer but replaced before any transfer since the previous FRAME record | |
+| `flags` | u8 | — | bit0 buffer came from an SD read · bit1 the open pattern file is contiguous (O(1) seek path). `3` = both | fw `Telemetry.h` `kFrameFlag*` |
+
+- Only **changes** are recorded (`cur_frame_index_ != tel_last_frame_ || pattern != …`); a held frame produces nothing.
+- Ring v1 (fw before `3c71953`): 8 fields, no `req_age_us`; **consumers gate on length**, never assume 11.
+- Trial verdicts use `sd_load_us` from FRAME records too (v0.78), so a slow read counts even when no `sd_slow` STATE
+  was emitted (ring v1 flagged only > 20 ms).
+
+### 2.5 Controller state / error / boot — `["cs", rx, t_us, seq, kind, code, arg]` (7 fields)
+
+`["cs",1789315572700,1860414194,427764,7,0,36]` · `["cs",…,11,1,8]` · `["cs",…,13,0,9173]` · `["cs",…,4,0,327]` (ring v1: 32.7 ms read)
+
+| kind | name | `code` | `arg` | when |
+|---|---|---|---|---|
+| 1 | `boot` | reset-cause bits (bit 7 = watchdog, as decoded by `wedge-scan.py`) | previous breadcrumb op | first record after a reset (ring contents survive a soft reset; `boot_count` in the block header) |
+| 2 | `state_change` | controller state id | context (pattern id in the samples) | display state machine transitions (STOP, SHOW_FRAME, …) |
+| 3 | `error_glyph` | error | — | an error glyph was shown on the arena |
+| 4 | `sd_slow` | bits 0–1 slowest phase: 1 seek · 2 body · 3 CRC trailer; bit 7 = read error | read µs **/ 100**, saturating | a `readFrame` > **10 ms** (ring v2; 20 ms on v1) |
+| 5 | `ring_overrun` | `0x00` evicted · `0xFF` heap collision (ring disabled for the session) | records evicted since the last marker | overflow episode (≥ 1 s apart); the durable signal is the header `dropped` counter + `seq` gaps |
+| 6 | `telemetry` | opcode that changed settings (`0xCE` for SD diag) | new flags | SET_TELEMETRY / SET_SD_DIAG; also `[…,6,1,0]` right after boot |
+| 7 | `sd_open` | 0 = ok, else error | pattern id | pattern opened → **trial boundary** for `trial-quality` (`code === 0`) |
+| 8 | `wdog_context` | watchdog handler's EXC_RETURN low byte (`0xF9` thread, `0xF1` handler) | IPSR bits 0–8 \| `isr_last << 9` | first boot after a watchdog reset |
+| 9 | `prev_isr_count` | ISR id (4 usb · 5 sdhc · 6 lpspi · 7 pit) | `min(65535, count >> 12)` | after a watchdog reset, one per ISR with a count |
+| 10 | `timer_fail` | 0 | requested refresh Hz | `IntervalTimer::begin()` failed |
+| 11 | `sd_layout` | bit0 contiguous · bit1 exFAT · bit2 legacy seek forced (diag) · bit3 same-index skip off (diag) | sectors per cluster (8 = 4 KiB) | after each `sd_open` |
+| 12 | `sd_slow_ctx` | SdFat sticky `errorCode()` | USDHC `IRQSTAT` bits 16–31 | immediately after every `sd_slow` |
+| 13 | `sd_reads` | shift | reads for that open = `arg << code` | pattern close / re-open |
+| 14 | `sd_reads_ckpt` | shift | cumulative so far = `arg << code` (lower bound if the run dies) | every 30 k reads while open (fw flag bit 6) |
+
+Source: fw `src/Telemetry.h:169–214` (`StateKind`, `kSdSlow*`, `kFrameFlag*`, `kSdSlowThresholdUs`),
+`CommandProcessor.cpp:2151–2178`; names mirrored in `js/arena-telemetry.js:45` `STATE_KINDS` and written into every
+file's `stream_schema` (a log from fw `3c71953` lists kinds 1–13; `488d5b9` lists 1–14).
+
+**Ordering inside one dispatch:** STATE records are appended *during* a handler, the CMD record *after* it — so a
+trial's `sd_open`/`sd_layout` (`seq` 427764/765) precede the TRIAL_PARAMS `cc` (427767) while carrying a **later**
+`t_us`. Rows are in ring order in the file; **never sort controller rows by `rx` or `t_us`, order by `seq`.**
+
+## 3. Event catalogue (objects)
+
+All are `{"type":"log","event":<name>,…,"dir":"browser→bridge","rx_ms":<bridge epoch ms>}` unless marked. Emitters are
+Studio v0.79 (`arena_studio.html`) or the named module; the bridge only adds the envelope.
+
+| event | emitter | when | fields |
+|---|---|---|---|
+| `run_metadata` | `arena_studio.html:8719` (meta half built by `js/run-log.js:184`) | run start, after the level ack | `rig_id`, `log_format` (acked level), `run_id`, `experimenter`, `genotype`, `age`, `sex`, `fly_number`, `notes`, `protocol_filename`, `protocol_sha256` (`null` for test intent), `arena_config`, `rig`, **`firmware`** (0xCB label, e.g. `"3c719534 2x10 2026-09-13 feat/sd-fastpath-2x10 freerun sdfast"`), `controller_id` (MAC), `tool_version`, `timestamp_start` (ISO), **`telemetry`** (`"ring-10hz"` \| `"off"`), **`sd_card`** (0xCD identity `{label, manufacturer, pnm, prv, psn_hex, mdt, capacity_gb, card_type, fat, bytes_per_cluster, cid_hex, sd_diag}` or `null`), **`gap_threshold_ms`** (10), `soak` `{iteration, policy, first_fault}` (soak runs only) |
+| `stream_schema` | `arena_studio.html:8740` | right after `run_metadata`, when the ring is on | `streams: {cc:{cols,desc}, cf:{cols,desc}, cs:{cols,desc,kinds}}` = `ArenaTelemetry.STREAM_SCHEMA`. **`cols` omit the tag: `cols[i]` ↔ `row[i+1]`** (whereas `frame_schema.cols[0]` ↔ `row[0]`) |
+| `runner` | `js/arena-session.js:513` | every runner status | `phase` (`sequence-start`, `trial_start`, `condition-start`, …), `index`, `total`, `op`, `value`, `reason`, `message`, `level`, `durationSec`, `conditionName`, `params`, `condition`, `status`/`ok` (allow-listed by `_sanitizeRunStatus`, `:522`) |
+| `log` | `js/arena-runner-g6.js:1454` | runner INFO/WARN lines | `message`, `level` |
+| `config` (`type:"config"`, no `event`) | `js/fictrac-bridge-client.js` per trial | closed-loop trial start | `fictrac_port`, `gain`, `offset`, `frames` — the bridge's `idx` parameters |
+| `arena_command` | `js/arena-session.js:391` | > 8-byte requests (TRIAL_PARAMS) | v1 object, see §2.2 |
+| `trial_quality` | `arena_studio.html:8264` ← `js/trial-quality.js:246` `summary()` | **once, at run end, before export** (v0.78) | `threshold_us`, `target_us`, `trials[]`, `counts {pass, fail, unknown, open}`, `worst_gap_us`, `flagged_trials[]`, `unknown_trials[]`, `duplicates_dropped`, `records`. Per trial: `trial`, `pattern`, `status` (`pass`\|`fail`\|`unknown`), `duration_s`, `cmds70`, `index_changes`, `reads`, `frames`, `slow_reads`, `stalls`, `max_read_ms`, `age_gaps`, `max_age_ms`, `over_target`, `superseded`, `coverage[]` |
+| `display_gap` | `js/trial-quality.js:101` `gapEvent` → `arena_studio.html:8479` | one per gap > threshold, as it happens | `trial`, `pattern`, `seq`, `t_us`, `ms`, `kind` ∈ `sd_slow` (+ `phase`, `read_error`) · `frame_read` (+ `idx`; a slow read seen only in the FRAME record) · `frame_age` (+ `idx`; `req_age_us` > threshold). Absent from a clean run |
+| `soak` | `arena_studio.html:8317` `logSoak` | soak driver phases | `phase` ∈ `start` · `iteration-start` · `iteration-end` · `paused` · `end`; `iteration-end` carries `iteration`, `outcome`, `fault`, `stop_acked`, `postmortem`, `applied_0x70`, `duration_s`, `telemetry` (drainer stats: `ackSeq`, `lastSeq`, `records`, `blocks`, `bytes`, `gaps`, `dropped`, `errors`, `notStored`, …). **`dropped` is the controller's lifetime evicted-record counter from the block header** (1157 with `gaps: 0` in the sample = eviction before the drainer started, not in-run loss) |
+| `sd_diag` | `arena_studio.html:8543` | `Studio.setSdDiag()` and the v0.79 connect banner | `flags`, `in_force` (GET_SD_INFO byte 29), `label` |
+| `probe` | `js/studio-postmortem.js:112` | post-mortem after a controller fault | `name`, `phase`, `cmd`, `req`, `sd`, then `dt`, `resp`, `status`, `ok`, `decoded` — or `error`, or `skipped: "capability X absent"`. The health read appears here as `name:"health"` with `decoded` |
+| `telemetry_dump` | `arena_studio.html:8580` | post-mortem | `summary {tag, records, blocks, survivedReboot, bootCount, dropped, gaps, heapCollision, tail[]}`, `raw_blocks[]` (hex) |
+| `crash_report` | `arena_studio.html:8554` | post-mortem, fw flag bit 3 | `present`, `fault`, `ret_addr`, `cfsr`, `hfsr`, `bfar`, `mmfar`, `raw_hex` (junk after a HalfKay reflash — known) |
+| `health` | `arena_studio.html:5587` | **Console `chealth` only** | `source:"console"`, `health` (decoded 0xCA) |
+| `analog_loopback_sweep` | `arena_studio.html:5303` | Console Analog In panel | `channel`, `rows`, `fit`, `verdict` |
+
+Not log lines: `hello_ack`, `log_control_ack` (socket replies). Not implemented: `soak_note` (an operator can type
+`bridge.log({event:'soak_note', …})` in the console; no code emits it).
+
+## 4. Controller reads (pointer table — byte layouts live in the firmware README)
+
+| opcode | name | gate | reply | README § | Studio decoder |
+|---|---|---|---|---|---|
+| 0xA8 | `SET_TELEMETRY` `[04 A8 flags rate_lo rate_hi]` | 0xCB bit 2 | echo | Telemetry ring | `js/arena-wire-g6.js:74` |
+| 0xA9 | `GET_TELEMETRY_BLOCK` `[08 A9 ack_seq(u32) max_bytes(u16) flags]` — frees `seq ≤ ack_seq`, returns **18-B header** `{t_now_us u32, first_seq u32, n_records u16, dropped u32, more u8, flags u8, boot_count u16}` + whole records (`len, type, seq u32, t_us u32, payload`; CMD 13–21 B · FRAME 26 B · STATE 14 B, little-endian) | bit 2 | ≤ 196 B | Telemetry ring | `js/arena-telemetry.js:103` `parseBlock`; drain loop `createDrainer` `:272` (ack = stored by the bridge; loop on `more`; 200 chunks/poll; 10 Hz poller `:445`) |
+| 0xCA | `GET_HEALTH` | 0xC2 capability bit 7 | **ver 5, 114 B** | Health + breadcrumb | `decodeHealth` `:744` |
+| 0xCB | `GET_FIRMWARE_VERSION` | cap bit 7 | 46 B `{ver, rows, cols, flags, sha[8], date[10], branch[24]}`; flags: bit0 dirty · 1 debug · **2 telemetry ring · 3 crash report · 4 free-running refresh · 5 SD fast path (0xCD, FRAME v2, kinds 11–13) · 6 SD diag (0xCE, kind 14)** | Build identity | `decodeFirmwareVersion` `:942` → `run_metadata.firmware` |
+| 0xCC | `GET_CRASHREPORT` | bit 3 | 128 B raw | Watchdog | `decodeCrashReport` `:881` |
+| 0xCD | `GET_SD_INFO` | bit 5 | 30 B (CID, FAT type, cluster size, `sd_status_maint`, byte 29 = diag readback) | SD card identity | `decodeSdInfo` `:1026` → `run_metadata.sd_card` |
+| 0xCE | `SET_SD_DIAG` `[02 CE flags]` | bit 6 | echo | A/B switches | `Studio.setSdDiag` |
+
+**Gating rule:** every ring-era feature is gated on a **0xCB flag bit, never on the 0xC2 capability byte** (it is full;
+its bit 7 is `health`). An ungated opcode gets `CE_UNKNOWN_CMD` and an error glyph on the arena.
+
+## 5. Timestamp merging — the clocks and how to align them
+
+### 5.1 Every stamp in the file
+
+| stamp | in | clock | absolute / relative | notes |
+|---|---|---|---|---|
+| `t0` | `frame_schema` | bridge wall (`time.time()`) | epoch ms | origin of `t_off`, `rx_off`; equals line 1's `ms` |
+| `ms` | FicTrac row | bridge wall | relative to the last `log_control{enabled}` (`t0_ms`, a *different* variable set µs after `t0`; treat as `t0`) | UDP receipt |
+| `ft` | FicTrac row | **FicTrac camera** (col 22, ns) | relative to the first frame after activation | the only stamp from the tracker's clock; sim value broken (§2.1) |
+| `t_off` | `a` | **browser** `Date.now()` | − `t0` | send-queue entry |
+| `dt` | `a` | browser `performance.now()` | duration | includes host queue wait |
+| `rx_off` | `a`, `rx_ms` on events | bridge wall | − `t0` / epoch | bridge receipt of the browser message |
+| `rx` | `cc`/`cf`/`cs` | **browser** `Date.now()` | epoch ms (float) | 0xA9 block parse time; shared by the block; ≤ 100 ms late |
+| `t_us` | `cc`/`cf`/`cs` | **controller** `micros()` | u32, wraps 71.6 min | CMD = receipt-before-dispatch; FRAME = SPI start; STATE = at the event |
+| `t_now_us` | 0xA9 header (not in the file today) | controller | u32 | reply time; the natural host↔controller pair point (`rx`, `t_now_us`) — not logged, see §8 |
+
+Three clocks, then: **FicTrac** (`ft`), **host** (bridge and browser are the same PC — `t0`, `ms`, `t_off`, `rx_off`,
+`rx` are all host epoch ms; the browser and bridge processes read the same OS clock, so treat them as one clock with
+sub-ms process latency), **controller** (`t_us`). The file mixes bridge-stamped (`rx_off`) and browser-stamped (`rx`)
+host times without a marker; both are host epoch, so the mix is harmless for alignment but confusing to read
+(format review R2 proposes `drain_ms`, t0-relative).
+
+### 5.2 Rules
+
+1. **Order controller rows by `seq`** (= file order). `rx` is quantised to the drain (13 rows share one `rx` in the
+   sample), and `t_us` runs backwards across a STATE→CMD boundary (41 such steps in the 20-trial log = one per
+   `sd_open`+TRIAL_PARAMS). `seq` gaps = evicted records (`dropped` in the header grows).
+2. **Unwrap `t_us`** with `seq`: consecutive records are ≤ seconds apart, so a decrease of ~2³² µs is a wrap.
+   Discard a **pre-run backlog** (ring contents from before connect) by its offset: `rx − t_us/1000` differs from the
+   run's offset by seconds.
+3. **`a` ↔ `cc` join is by order**, not by key: both are complete sequences of the same commands (host echo vs
+   controller record); counts differ by the commands in flight at the end (and, on v0.77 files, by the tail written
+   after `trial_quality` — `runlog-check.py` reports both). A host command counter on `a` is R2 in the format review.
+4. **Host↔controller offset is a fit, not a constant.** Pair 0x70 `a` rows with 0x70 `cc` rows by order, take
+   `t_host = t0 + a.t_off` vs `cc.t_us` (unwrapped), fit `t_host = α + β·t_us`. Measured 2026-09-12 on one run: slope
+   **−3 ppm**; residuals = USB/CDC queueing + `serviceUsb` (one command per `loop()`). **Not implemented in any
+   script** — `telemetry-report.py` and `wedge-scan.py` never fit clocks; it is a recipe. A cleaner pair point is
+   (`rx`, `t_now_us`) once the block header time is logged (§8).
+5. **FicTrac ↔ host:** `ms − ft` is constant plus camera→UDP latency, only on a real rig (sim `ft` is unusable).
+   Never measured.
+
+### 5.3 Per-edge evidence
+
+| edge | what the file gives | status |
+|---|---|---|
+| camera → FicTrac → bridge | `ms − ft` (real FicTrac only) | **unmeasured** on a rig |
+| bridge → browser → `apply` → send | nothing: the `a` row carries no `fc`; the client coalesces frames (newest index wins, `js/fictrac-bridge-client.js:584`) with no counter | **not derivable** |
+| host send → controller dispatch | `cc.t_us` (via the §5.2.4 fit) − (`t0 + a.t_off`) | derivable; measured once (−3 ppm, residual = USB) |
+| dispatch → SD read → SPI start | **`cf.req_age_us`** (ring v2) or `cf.t_us − cc.t_us` by `seq` (v1); split: `sd_load_us` + tick wait (0–3.3 ms at 300 Hz) + loop | **measured per frame**: p50 1.72 ms, p99 2.56, max 4.8 ms (20 trials, 2026-09-13, fw `3c71953`) |
+| SPI transfer | `cf.spi_us` ≈ 776 µs | measured |
+| SPI end → LEDs lit | — | **unmeasured** (needs a light sensor, §8) |
+| controller reply → host | `a.dt` − in-controller time (≈ `req_age_us` when the frame changed, else ~0.1 ms) | derivable; `a.dt` median 2 ms, includes queue wait |
+| event → log line | `rx − t_us` (after the fit) | ≤ 100 ms drain lag; seconds when the bridge refuses rows |
+
+## 6. Round-trip timing recipe (one closed-loop step)
+
+Chain: FicTrac frame *k* → bridge (`ms_k`, `ft_k`) → browser apply → 0x70 sent (`a.t_off`) → controller receipt
+(`cc.t_us`) → SD read (`cf.sd_load_us`) → wait for tick → SPI start (`cf.t_us`; `cf.req_age_us` covers receipt→SPI)
+→ LEDs (unmeasured) ; reply → browser (`a.t_off + a.dt`).
+
+| step | compute | clock(s) | today |
+|---|---|---|---|
+| 1. tracker → bridge | `ms_k − ft_k` (constant offset + jitter) | FicTrac vs host | real rig only |
+| 2. bridge → 0x70 sent | needs `fc` on the `a` row | host | **not derivable** — bound it: ≤ one FicTrac period + coalescing |
+| 3. sent → controller receipt | `fit(cc.t_us) − (t0 + a.t_off)` for the paired rows | host→controller (fit) | median ≈ 1–2 ms, tail = USB |
+| 4. receipt → SPI start | `cf.req_age_us`; `sd_load_us` is the SD part, the rest is the refresh-tick wait | controller only (no fit) | 1.7 ms p50 / 4.8 max; +1 step reads 0.62 ms, any other step 1.19–1.46 ms |
+| 5. SPI | `cf.spi_us` | controller | 0.78 ms |
+| 6. LED latch + update | — | — | unmeasured (§8 #3) |
+| 7. reply → host | `a.dt − step 4` | host | ≈ 2 ms − 1.7 ms |
+
+**Glass-to-glass today** = step 1 + [step 2 unknown] + step 3 + `req_age_us` + `spi_us` + [step 6 unknown]. The two
+unknowns are the reason for §8 items 3 and 5. **Superseded frames** (`cf.superseded`, 0.5 % of frames in the sample) are
+requests that never reached the panels because a newer one arrived first — the controller-side coalescing; the
+host-side coalescing (bridge client) is uncounted.
+
+## 7. Readers and tools
+
+| tool | reads | does |
+|---|---|---|
+| `js/runlog-format.js` (+ byte-identical copy `dashboard/data-browser/vendor/runlog-format.js`, divergence test) | any level, gzip | `readRunlogText` inflates; `createNormalizer().normalize(rec)` expands **only `"a"` arrays** to v1 objects and passes every other array through unchanged — **callers skip string-tagged rows** (`dashboard/data-browser/analysis-core.js`, `js/runlog-replay.js`; both guards ship with #198) |
+| `scripts/telemetry-report.py` | `cc`/`cf`/`cs` + `run_metadata` (skips `a` and FicTrac) | reads per pattern, SD cost by index-step class, stall clusters (with spacing in commands / index changes / s), `req_age_us` percentiles, per-trial verdicts — same rule as `trial-quality.js` (`fail` if any stall or age gap; `unknown` if coverage gaps) |
+| `scripts/runlog-check.py` | whole file | completeness: metadata, `stream_schema`, `trial_quality` present and after the last controller row, `cc` 0x70 vs `a` counts, drainer stats, FicTrac rows per trial-second, `display_gap` ↔ `trial_quality` provenance; exit 1 on a problem |
+| `scripts/wedge-scan.py` | `a` (+ v1 objects), `cc`/`cf`/`cs`, events | wedge onset/outcome, host RTT median/p99/max (from `a.dt`), controller-order and host-order tails around a `boot` |
+| firmware `scripts/sd_stall_test.py` | writes the same row shapes (browser-free) | card comparisons; exact worst/cluster stats (Codex rounds 1–4 applied on `75405ee`) |
+| `tests/telemetry_codec.py` (fw), `tests/test-arena-telemetry.js`, `tests/test-trial-quality.js`, `tests/test-telemetry-report.py`, `tests/test-wedge-scan.py` (web) | — | the shape oracles: change a column → these fail |
+
+Sample, `arena-log-20260913-120611-713.jsonl` (v0.77, fw `3c71953`, 2 soak iterations, 20 trials, 1280 s):
+
+```
+telemetry-report:  pattern 36: 121 001 accepted 0x70 · 91 874 index changes · 91 884 fw reads · 0.759 reads/cmd · contiguous, 8 spc
+                   SD read cost (µs): +1 step p50 621 · other steps p50 1460 (pat 36) / 1190 (pat 5) · max 1798
+                   stalls > 10 ms: 0 · req_age p50 1716 · p90 2555 · p99 2556 · max 4835 · superseded 0.5 % · trials {'pass': 20}
+runlog-check:      firmware 3c719534 … freerun sdfast · verdicts {'pass': 20} · cc_0x70_ok 242178 vs a_ok 242200
+                   ! trial_quality at line 923845 BEFORE the last controller row at 924204   ← v0.77 export ordering (fixed v0.78)
+```
+
+## 8. Gaps → instrumentation (ranked; Teensy-only first, no AD3 / Saleae)
+
+| # | gap | smallest fix | where |
+|---|---|---|---|
+| 1 | CMD `t_us` is dispatch-side; USB queue time invisible | stamp `micros()` in `SerialManager::parseIncoming` when `cmd_ready_`, carry on `ParsedCommand`, add to CMD (or a STATE) | fw |
+| 2 | no host↔controller pair point without the order-join | log the 0xA9 header `t_now_us` with the block `rx` (one `["ct", rx, t_now_us, first_seq]` row per block, or in `soak`/drainer stats) → direct fit, ~10 pairs/s | `js/arena-telemetry.js` `toRows` |
+| 3 | SPI start → light unmeasured | photodiode/phototransistor on **Analog In 1**; arm the i.MX RT ADC compare interrupt after each transfer, record `light_us − cf.t_us` as a FRAME field or STATE (bench build: poll ≤ 5 ms after `transferFrame`); alternate dark/lit frames at the sensor | fw (analog-in path exists: 0xA4–0xA7) |
+| 4 | framescan envelope not cross-checked | loop `out_debug_framescan` (Digital IO 1) into Digital IO 2 as an edge-interrupt input; timestamp both edges → validates `spi_us` and tick phase | fw + one wire |
+| 5 | FicTrac frame → 0x70 not linkable | add `fc` to the `arena_command` object / `a` row (one int; R2 in the format review); optionally echo 2 bytes in the 0x70 payload the firmware ignores so it lands in `cc.req` | `js/arena-session.js`, `bridge.py` (+ readers) |
+| 6 | host coalescing uncounted | counter at the `_pending` overwrite (`js/fictrac-bridge-client.js:584`) → drainer/`soak` stats and run end | web |
+| 7 | refresh-tick phase unknown | record `micros()` (or a 16-bit counter) in `refreshISR`; log tick→transfer per FRAME → separates "waited for the tick" from "loop busy" | fw |
+| 8 | `rx` semantics confuse readers | schema v3: `drain_ms` t0-relative (format review R2); until then, this document | web |
+| 9 | sim `ft` unit bug (§2.1) | **fixed** `claude/mode3-perf-sd` @ `f16e67e` (col 22 in ns); logs before the overnight of 2026-09-13 keep the wrong `ft` | bridge |
+| 10 | LEDs / camera with instruments | proposal §9 L1–L4 (AD3-toggled IR LED in the camera view, Saleae on framescan + photodiode, motorised ball) — when instruments are back | bench |
+
+## 9. Next experiments (state as of 2026-09-13 evening) and document lineage
+
+**Done:** control iterations on the fast-path build (482 k commands, 0 stalls, 40/40 pass) · 4-arm causal test (FAT
+access is the cause; same-index skip irrelevant) · 1 h at 286 Hz (1.04 M commands, 0 reads > 1.8 ms) · 13 × 10-min
+286 Hz campaign (one 19.4 ms body-phase read on the 8 MB sine — the watch item). **Running:** overnight benchmark on
+`488d5b9` per [`overnight-soak-test-plan-2026-09-13.md`](overnight-soak-test-plan-2026-09-13.md) (its §4 lists what the
+night does NOT test).
+
+**Open, in the order they pay off:**
+1. Photodiode on Analog In (§8 #3) — the only way to turn `req_age_us` into latency-to-light.
+2. `t_now_us` pair rows + `fc` on `a` (§8 #2, #5) — makes the whole chain derivable from one file; then run it on a
+   real FicTrac rig (camera clock).
+3. Working-set test on the same file (`sd_stall_test.py --window 50/100/200`) — card read-cache vs placement.
+4. `0x32` host streaming at 100/200/286 Hz — removes SD entirely; tests USB against the deadline.
+5. Telemetry on vs off control iteration — the instrumentation's own cost.
+6. Card screening when cards arrive (protocol: archive `sd-read-jitter-2026-09-13.md` §5); never reformat the bench card.
+7. Resident decode (compressed per-frame RAM cache) — only if a read-free path is still wanted after the benchmark.
+
+**Lineage — which document owns what now:**
+
+| document | status | owns |
+|---|---|---|
+| this file | living | row/event catalogue, clocks, latency recipe, gaps |
+| `mode3-reliability-handoff-2026-09-14.md` | living | the narrative, firmware layers, test history, ship plan, parsing rules §7.2 |
+| `runlog-format-review-2026-09-13.md` | living | bytes per hour, compaction R1–R4 |
+| `runlog-behavior-v2-plan.md` | living | why `behavior_v2` / `.jsonl.gz`; the level negotiation design |
+| `controller-telemetry-ring-buffer-proposal.md` | design record | the ring's rationale, T1–T6, instrument plan L1–L4 (§9); as-built layouts differ — see §2, §4 here |
+| `telemetry-review-handoff-2026-09-13.md` | **delivered by this file** — suggested header for the clean-up: *"Deliverables (1)–(4) landed in `telemetry-logging-reference.md`; kept for the experiment rationale in §5."* | Teensy-only measurement rationale |
+| `archive/mode3-2026-09/*` | history | see its README |
diff --git a/docs/development/telemetry-reference.html b/docs/development/telemetry-reference.html
new file mode 100644
index 00000000..a86847af
--- /dev/null
+++ b/docs/development/telemetry-reference.html
@@ -0,0 +1,172 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Telemetry Reference — clocks and the closed-loop latency chain</title>
+<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;600&family=IBM+Plex+Mono:wght@400;500&display=swap" rel="stylesheet">
+<style>
+  :root { --bg:#0f1419; --surface:#1a1f26; --border:#2d3640; --text:#e6edf3; --dim:#8b949e; --accent:#00e676; --hover:#00c853;
+          --fictrac:#ffb86b; --host:#7dd3fc; --ctl:#00e676; --panel:#c4b5fd; --warn:#ff7b72; --unk:#8b949e; }
+  * { box-sizing:border-box; }
+  body { margin:0; background:var(--bg); color:var(--text); font-family:'IBM Plex Mono',monospace; font-size:14px; line-height:1.5; }
+  header, main, footer { max-width:1180px; margin:0 auto; padding:0 24px; }
+  header { padding-top:28px; }
+  h1 { font-family:'JetBrains Mono',monospace; font-size:20px; font-weight:600; margin:0 0 6px; }
+  h2 { font-family:'JetBrains Mono',monospace; font-size:16px; font-weight:600; margin:36px 0 8px; color:var(--accent); }
+  p.lead { color:var(--dim); margin:0 0 8px; }
+  a { color:var(--accent); text-decoration:none; } a:hover { color:var(--hover); text-decoration:underline; }
+  figure { margin:12px 0 0; background:var(--surface); border:1px solid var(--border); border-radius:8px; padding:16px; }
+  figcaption { color:var(--dim); font-size:12.5px; margin-top:10px; }
+  svg { width:100%; height:auto; display:block; font-family:'IBM Plex Mono',monospace; }
+  .lane-label { font-family:'JetBrains Mono',monospace; font-weight:600; font-size:13px; }
+  .lbl { font-size:12px; fill:var(--text); }
+  .dim { font-size:11px; fill:var(--dim); }
+  .stamp { font-size:12px; font-weight:500; }
+  .legend { display:flex; flex-wrap:wrap; gap:18px; color:var(--dim); font-size:12.5px; margin-top:10px; }
+  .legend span::before { content:''; display:inline-block; width:22px; height:0; border-top:3px solid; margin-right:6px; vertical-align:middle; }
+  .legend .m::before { border-color:var(--ctl); } .legend .d::before { border-color:var(--host); border-top-style:dashed; }
+  .legend .u::before { border-color:var(--warn); border-top-style:dotted; } .legend .n::before { border-color:var(--unk); border-top-style:dotted; }
+  code { background:var(--surface); border:1px solid var(--border); border-radius:4px; padding:0 5px; font-size:12.5px; }
+  footer { border-top:1px solid var(--border); margin-top:40px; padding:14px 24px 28px; color:var(--dim); font-size:12px; }
+</style>
+</head>
+<body>
+<header>
+  <h1>Telemetry Reference — the three clocks and the closed-loop latency chain</h1>
+  <p class="lead">Companion figures for <a href="telemetry-logging-reference.md">telemetry-logging-reference.md</a> (Arena Studio v0.79 · bridge 3.1 · firmware candidate 488d5b9, ring v2). Field names are the ones in the run log.</p>
+</header>
+<main>
+
+<h2>1. Where every timestamp is taken</h2>
+<figure>
+<svg viewBox="0 0 1120 440" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="Swimlane of FicTrac, bridge, browser, controller and panels with every log timestamp placed on its lane">
+  <defs>
+    <marker id="arr" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0 0L10 5L0 10z" fill="#8b949e"/></marker>
+  </defs>
+  <!-- lanes -->
+  <g font-size="12">
+    <rect x="0" y="20" width="1120" height="70" fill="#141a21"/>
+    <rect x="0" y="90" width="1120" height="70" fill="#111720"/>
+    <rect x="0" y="160" width="1120" height="70" fill="#141a21"/>
+    <rect x="0" y="230" width="1120" height="70" fill="#111720"/>
+    <rect x="0" y="300" width="1120" height="70" fill="#141a21"/>
+    <text x="14" y="50" class="lane-label" fill="#ffb86b">FicTrac / sim</text><text x="14" y="68" class="dim">camera clock · col 22 (ns)</text>
+    <text x="14" y="120" class="lane-label" fill="#7dd3fc">bridge (py)</text><text x="14" y="138" class="dim">host wall clock · time.time()</text>
+    <text x="14" y="190" class="lane-label" fill="#7dd3fc">Studio (browser)</text><text x="14" y="208" class="dim">host wall clock · Date.now() (+ performance.now() for dt)</text>
+    <text x="14" y="260" class="lane-label" fill="#00e676">controller (Teensy)</text><text x="14" y="278" class="dim">micros() · u32, wraps 71.6 min</text>
+    <text x="14" y="330" class="lane-label" fill="#c4b5fd">panels</text><text x="14" y="348" class="dim">no clock · light is unmeasured</text>
+  </g>
+  <!-- flow arrows -->
+  <g stroke="#8b949e" stroke-width="1.4" fill="none" marker-end="url(#arr)">
+    <path d="M300 62 L300 112"/>                       <!-- UDP -->
+    <path d="M380 128 L380 182"/>                      <!-- websocket frame -->
+    <path d="M470 198 L470 252"/>                      <!-- usb 0x70 -->
+    <path d="M720 268 L720 322"/>                      <!-- spi -->
+    <path d="M790 252 L790 198"/>                      <!-- reply -->
+    <path d="M850 182 L850 128"/>                      <!-- a row echo to bridge -->
+    <path d="M990 252 L990 198"/>                      <!-- 0xA9 block -->
+    <path d="M1040 182 L1040 128"/>                    <!-- rows to bridge -->
+  </g>
+  <g class="dim">
+    <text x="306" y="92">UDP</text>
+    <text x="386" y="160">WebSocket frame</text>
+    <text x="476" y="230">USB · 0x70 idx</text>
+    <text x="634" y="313">SPI transfer</text>
+    <text x="796" y="230">reply status</text>
+    <text x="856" y="160">{event:arena_command}</text>
+    <text x="996" y="230">0xA9 block</text>
+    <text x="1046" y="160">{type:rows}</text>
+  </g>
+  <!-- stamps -->
+  <g class="stamp">
+    <circle cx="300" cy="50" r="5" fill="#ffb86b"/><text x="230" y="45" fill="#ffb86b">ft</text>
+    <circle cx="300" cy="120" r="5" fill="#7dd3fc"/><text x="240" y="115" fill="#7dd3fc">ms</text>
+    <text x="300" y="112" class="dim" text-anchor="middle"></text>
+    <circle cx="470" cy="190" r="5" fill="#7dd3fc"/><text x="440" y="180" fill="#7dd3fc">t → t_off</text>
+    <circle cx="790" cy="190" r="5" fill="#7dd3fc"/><text x="700" y="180" fill="#7dd3fc">dt = reply − t (mono)</text>
+    <circle cx="850" cy="120" r="5" fill="#7dd3fc"/><text x="820" y="115" fill="#7dd3fc">rx_off</text>
+    <circle cx="470" cy="260" r="5" fill="#00e676"/><text x="428" y="290" fill="#00e676">CMD t_us</text>
+    <circle cx="720" cy="260" r="5" fill="#00e676"/><text x="672" y="290" fill="#00e676">FRAME t_us</text>
+    <circle cx="600" cy="260" r="4" fill="#00e676" opacity=".7"/><text x="560" y="290" fill="#00e676" opacity=".8">STATE t_us</text>
+    <circle cx="990" cy="260" r="5" fill="#00e676"/><text x="920" y="290" fill="#00e676">t_now_us · header only</text>
+    <circle cx="990" cy="190" r="5" fill="#7dd3fc"/><text x="962" y="180" fill="#7dd3fc">rx (per block)</text>
+  </g>
+  <!-- horizontal spans -->
+  <g stroke-width="3" fill="none">
+    <path d="M470 260 L720 260" stroke="#00e676"/><text x="595" y="248" class="lbl" text-anchor="middle" fill="#00e676">req_age_us</text>
+    <path d="M720 330 L760 330" stroke="#c4b5fd"/><text x="740" y="348" class="lbl" text-anchor="middle" fill="#c4b5fd">spi_us</text>
+    <path d="M760 330 L870 330" stroke="#ff7b72" stroke-dasharray="3 4"/><text x="815" y="322" class="lbl" text-anchor="middle" fill="#ff7b72">latch → light ?</text>
+    <path d="M470 166 L790 166" stroke="#7dd3fc" stroke-dasharray="6 4" opacity=".6"/>
+  </g>
+  <!-- file row -->
+  <g>
+    <rect x="0" y="380" width="1120" height="52" fill="#1a1f26" stroke="#2d3640"/>
+    <text x="14" y="401" class="lane-label" fill="#e6edf3">run log</text>
+    <text x="14" y="420" class="dim">one NDJSON file</text>
+    <text x="190" y="401" class="lbl" fill="#ffb86b">[ms, fc, idx, ft, x, y, hd]</text>
+    <text x="190" y="420" class="dim">bridge · relative to activation</text>
+    <text x="470" y="401" class="lbl" fill="#7dd3fc">["a", t_off, dt, hex, status, rx_off]</text>
+    <text x="470" y="420" class="dim">browser t, dt · bridge rx_off · − t0</text>
+    <text x="790" y="401" class="lbl" fill="#00e676">["cc"|"cf"|"cs", rx, t_us, seq, …]</text>
+    <text x="790" y="420" class="dim">t_us controller · rx browser, per block · by seq</text>
+  </g>
+</svg>
+<figcaption>Bridge and browser run on the same PC — <code>t0</code>, <code>ms</code>, <code>t_off</code>, <code>rx_off</code> and <code>rx</code> are all host epoch ms. <code>ft</code> is the only tracker-clock stamp (unusable from the simulator, which writes ms where the bridge expects ns). <code>t_us</code> is the only controller-clock stamp; <code>req_age_us</code> is measured entirely on that clock and needs no alignment. The host↔controller offset is a linear fit over paired <code>a</code>/<code>cc</code> rows (−3 ppm measured), not a constant.</figcaption>
+</figure>
+
+<h2>2. One closed-loop step — what each edge costs and how you get the number</h2>
+<figure>
+<svg viewBox="0 0 1120 300" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="Latency chain from a FicTrac frame to light on the panels and back to the host, with the log fields that give each edge">
+  <defs><marker id="arr2" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto"><path d="M0 0L10 5L0 10z" fill="#8b949e"/></marker></defs>
+  <!-- nodes -->
+  <g font-size="12" text-anchor="middle">
+    <g><rect x="20" y="110" width="120" height="50" rx="6" fill="#1a1f26" stroke="#ffb86b"/><text x="80" y="131" class="lbl">FicTrac frame k</text><text x="80" y="148" class="dim">ft · fc</text></g>
+    <g><rect x="185" y="110" width="110" height="50" rx="6" fill="#1a1f26" stroke="#7dd3fc"/><text x="240" y="131" class="lbl">bridge</text><text x="240" y="148" class="dim">ms · idx</text></g>
+    <g><rect x="340" y="110" width="120" height="50" rx="6" fill="#1a1f26" stroke="#7dd3fc"/><text x="400" y="131" class="lbl">0x70 sent</text><text x="400" y="148" class="dim">a.t_off</text></g>
+    <g><rect x="505" y="110" width="120" height="50" rx="6" fill="#1a1f26" stroke="#00e676"/><text x="565" y="131" class="lbl">received</text><text x="565" y="148" class="dim">cc.t_us</text></g>
+    <g><rect x="670" y="110" width="120" height="50" rx="6" fill="#1a1f26" stroke="#00e676"/><text x="730" y="131" class="lbl">SPI start</text><text x="730" y="148" class="dim">cf.t_us</text></g>
+    <g><rect x="835" y="110" width="110" height="50" rx="6" fill="#1a1f26" stroke="#c4b5fd"/><text x="890" y="131" class="lbl">light</text><text x="890" y="148" class="dim">—</text></g>
+    <g><rect x="990" y="110" width="110" height="50" rx="6" fill="#1a1f26" stroke="#7dd3fc"/><text x="1045" y="131" class="lbl">reply at host</text><text x="1045" y="148" class="dim">a.t_off + a.dt</text></g>
+  </g>
+  <!-- edges -->
+  <g stroke-width="3" fill="none" marker-end="url(#arr2)">
+    <path d="M140 135 L183 135" stroke="#ff7b72" stroke-dasharray="2 4"/>
+    <path d="M295 135 L338 135" stroke="#8b949e" stroke-dasharray="2 4"/>
+    <path d="M460 135 L503 135" stroke="#7dd3fc" stroke-dasharray="7 4"/>
+    <path d="M625 135 L668 135" stroke="#00e676"/>
+    <path d="M790 135 L833 135" stroke="#ff7b72" stroke-dasharray="2 4"/>
+  </g>
+  <path d="M565 160 C565 230 1045 230 1045 160" stroke="#7dd3fc" stroke-width="3" stroke-dasharray="7 4" fill="none" marker-end="url(#arr2)"/>
+  <!-- edge labels -->
+  <g stroke="#2d3640" stroke-width="1">
+    <line x1="317" y1="60" x2="317" y2="126"/><line x1="482" y1="60" x2="482" y2="126"/><line x1="812" y1="60" x2="812" y2="126"/>
+  </g>
+  <g text-anchor="middle">
+    <text x="162" y="98" class="lbl" fill="#ff7b72">ms − ft</text><text x="162" y="84" class="dim">real rig only</text>
+    <text x="317" y="42" class="lbl" fill="#8b949e">not derivable</text><text x="317" y="56" class="dim">no fc on a · coalescing</text>
+    <text x="482" y="42" class="lbl" fill="#7dd3fc">fit(cc.t_us) − a.t_off</text><text x="482" y="56" class="dim">USB + queue · ~1–2 ms</text>
+    <text x="647" y="98" class="lbl" fill="#00e676">cf.req_age_us</text><text x="647" y="84" class="dim">1.7 ms p50 · 4.8 max</text>
+    <text x="647" y="70" class="dim">= sd_load_us + tick wait (0–3.3 ms)</text>
+    <text x="812" y="42" class="lbl" fill="#ff7b72">spi_us 0.78 + latch ?</text><text x="812" y="56" class="dim">needs a light sensor</text>
+    <text x="805" y="222" class="lbl" fill="#7dd3fc">a.dt − req_age_us</text><text x="805" y="238" class="dim">USB both ways + host queue wait · a.dt ≈ 2 ms median</text>
+  </g>
+  <!-- acceptance scale -->
+  <g>
+    <line x1="20" y1="275" x2="1100" y2="275" stroke="#2d3640"/>
+    <text x="20" y="266" class="dim">display-freeze acceptance (req_age_us / sd_load_us):</text>
+    <g font-size="12">
+      <line x1="440" y1="268" x2="440" y2="282" stroke="#00e676" stroke-width="2"/><text x="440" y="296" text-anchor="middle" fill="#00e676">5 ms target</text>
+      <line x1="640" y1="268" x2="640" y2="282" stroke="#ffb86b" stroke-width="2"/><text x="640" y="296" text-anchor="middle" fill="#ffb86b">10 ms worst case → trial flagged</text>
+      <line x1="960" y1="268" x2="960" y2="282" stroke="#ff7b72" stroke-width="2"/><text x="960" y="296" text-anchor="middle" fill="#ff7b72">≥ 30 ms visible artifact</text>
+    </g>
+  </g>
+</svg>
+<div class="legend"><span class="m">measured on one clock</span><span class="d">derivable (fit or subtraction)</span><span class="u">unmeasured today</span><span class="n">not derivable from the file</span></div>
+<figcaption>Numbers are from <code>arena-log-20260913-120611-713.jsonl</code> (fw 3c71953, 20 trials). The two dotted edges are why the reference's §8 ranks a photodiode on Analog In first and <code>fc</code> on the <code>a</code> row second. Superseded frames (<code>cf.superseded</code>) are the controller-side coalescing; the host-side coalescing in the bridge client is not counted.</figcaption>
+</figure>
+
+</main>
+<footer>Telemetry Reference v1 | 2026-09-13 19:30 ET · <a href="https://github.com/reiserlab/webDisplayTools" target="_blank" rel="noopener">GitHub</a></footer>
+</body>
+</html>

From 7e2d1957b910b0982b1460e7edb4ed42347017fc Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 20:11:06 -0400
Subject: [PATCH 55/67] =?UTF-8?q?docs:=20fold=20the=20telemetry=20logging?=
 =?UTF-8?q?=20reference=20in=20=E2=80=94=20review-handoff=20status=20heade?=
 =?UTF-8?q?r,=20rx=20=3D=20browser=20parse=20time=20of=20the=20drain=20blo?=
 =?UTF-8?q?ck,=20stream=5Fschema=20cols=20offset;=20CLAUDE.md=20stall=20se?=
 =?UTF-8?q?ntence=20updated=20to=20the=20causal=20result?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/development/runlog-format-review-2026-09-13.md    |  9 +++++----
 .../development/telemetry-review-handoff-2026-09-13.md | 10 ++++++----
 2 files changed, 11 insertions(+), 8 deletions(-)

diff --git a/docs/development/runlog-format-review-2026-09-13.md b/docs/development/runlog-format-review-2026-09-13.md
index 00d78e39..bb329863 100644
--- a/docs/development/runlog-format-review-2026-09-13.md
+++ b/docs/development/runlog-format-review-2026-09-13.md
@@ -23,13 +23,14 @@ Measured on real files from this weekend (Studio + bridge iteration `arena-log-2
 |---|---|---|---|---|
 | FicTrac frame | bridge, every FicTrac/simulator frame (200 Hz) | `[4,7167479,12,0.0,-16.1773,580.57226,4.14543]` | `ms` (t0-relative), `fc`, `idx` (applied frame), `ft` (FicTrac col-22, relative), `x`, `y`, `hd` | 55 |
 | `a` | browser, one per command sent (0x70 at 200 Hz) | `["a",312.652,2.285,"03 70 02 00",0,314.953]` | `t_off` (t0-relative ms), `dt` (round-trip ms), `hex` (request bytes), `status`, `rx_off`(, `error`) | 34 (Studio) / 49 (harness, longer hex) |
-| `cc` | controller ring via the drainer, one per dispatched command | `["cc",1789325242813.438,28600458,5203,112,0,"b800"]` | `rx` (host epoch ms **of the drain block**), `t_us` (controller µs at dispatch), `seq`, `cmd`, `status`, `req` (params hex) | 54 |
+| `cc` | controller ring via the drainer, one per dispatched command | `["cc",1789325242813.438,28600458,5203,112,0,"b800"]` | `rx` (the browser's `Date.now()` **when the drain block was parsed**), `t_us` (controller µs at dispatch), `seq`, `cmd`, `status`, `req` (params hex) | 54 |
 | `cf` | controller ring, one per displayed frame change | `["cf",1789325242917.999,73238920,5229,2,36,1956,776,3029,1,1]` | `rx`, `t_us` (SPI start), `seq`, `idx`, `pattern`, `sd_load_us`, `spi_us`(, `req_age_us`, `superseded`, `flags`) | 55–66 |
 | `cs` | controller ring, state/error events | `["cs",1789325242813.438,28611677,5205,2,0,36]` | `rx`, `t_us`, `seq`, `kind`, `code`, `arg` | 48 |
 | objects | bridge/browser events | `{"type":"log","event":"runner",…}` | `run_metadata`, `runner`, `config`, `log_control`, `stream_schema`, `frame_schema`, `trial_quality`, `display_gap`, `soak`, `arena_command` (non-0x70 commands, full object) | 100–1200, rare |
 
-Schema lines: `frame_schema` names the FicTrac columns and `arena_cols` for `a`; `stream_schema` names the `cc`/`cf`/
-`cs` columns and the `cs` kind table. Readers: `js/runlog-format.js` (normalizer, gzip-aware), `js/runlog-replay.js`,
+Schema lines: `frame_schema` names the FicTrac columns (`cols[0]` ↔ `row[0]`) and `arena_cols` for `a`; `stream_schema`
+names the `cc`/`cf`/`cs` columns WITHOUT the tag (`cols[i]` ↔ `row[i+1]`) and the `cs` kind table. Full authority:
+`telemetry-logging-reference.md`. Readers: `js/runlog-format.js` (normalizer, gzip-aware), `js/runlog-replay.js`,
 dashboard `analysis-core.js` (vendored copy, test-enforced), `scripts/wedge-scan.py`, `scripts/telemetry-report.py`.
 
 ## 3. Where the bytes go (per active hour, Mode 3, 200 Hz, Studio + bridge path)
@@ -63,7 +64,7 @@ analysis step the telemetry review session owns).
 the same rows), which is the property that matters for a data pipeline: the log is the truth, the banner is a view.
 
 **Weak points, honestly:**
-1. `rx` on `cc`/`cf`/`cs` is the host time the *block* was drained, so it is up to 100 ms late and identical for all
+1. `rx` on `cc`/`cf`/`cs` is the browser's time when the *block* was parsed after the drain, so it is up to 100 ms late and identical for all
    records of a block. It is documented in the module header but readers keep mistaking it for the command's time;
    `t_us` is the controller-side time. → Rename in the schema-v3 pass (`drain_ms`) and make it t0-relative.
 2. The `a` row has no key to its `cc` row; the join is by command order (both are complete sequences, and
diff --git a/docs/development/telemetry-review-handoff-2026-09-13.md b/docs/development/telemetry-review-handoff-2026-09-13.md
index 7e8a0145..6ba15b20 100644
--- a/docs/development/telemetry-review-handoff-2026-09-13.md
+++ b/docs/development/telemetry-review-handoff-2026-09-13.md
@@ -1,5 +1,7 @@
 # Handoff — telemetry review session: what is logged now, how the three clocks relate, how to measure round-trip latency, and what to test next (Teensy-only timing)
 
+> **Status (2026-09-13 evening):** Deliverables (1)–(4) landed in `telemetry-logging-reference.md`; kept for the experiment rationale in §5. Two facts below were corrected there: `rx` on `cc`/`cf`/`cs` rows is the **browser's** `Date.now()` when the 0xA9 block was parsed (`js/arena-telemetry.js`), not a bridge receipt; and `stream_schema.cols` omit the tag (`cols[i]` ↔ `row[i+1]`) while `frame_schema.cols[0]` ↔ `row[0]`.
+
 **Written:** 2026-09-13 (performance session, Studio v0.77 / firmware `feat/sd-fastpath-2x10` `3c71953`).
 **For:** a review session that does NOT implement anything. Deliverables of that session: (1) an authoritative
 "what gets logged" reference (the pieces below are scattered over five docs and three code bases); (2) a
@@ -21,9 +23,9 @@ worktree `/Users/reiserm/Documents/GitHub/LED-Display_G6_Firmware_Arena-ring/REA
 | system | clock | what it stamps | where it lands |
 |---|---|---|---|
 | **FicTrac (or `fictrac_sim.py`)** | camera hardware clock (real rigs: col 22 in ns, converted to ms by the bridge; sim: `frame × dt_ms`, monotonic from 0) | one row per tracked frame: `fc` frame counter, `ft` col-22 timestamp, heading, x/y | behavior_v2 frame rows `[ms, fc, idx, ft, x, y, hd]` |
-| **bridge** (`fictrac-bridge/bridge.py` 3.1, Python, same machine as the browser) | `time.time()` wall clock, epoch ms | `ms` = bridge receipt of the FicTrac packet; `rx_off` = bridge receipt of a Studio echo; `rx` = bridge receipt of a drained ring block; `t0` in `frame_schema` = log origin (epoch ms) | every row it writes; `frame_schema.t0`; `log_control_ack` |
+| **bridge** (`fictrac-bridge/bridge.py` 3.1, Python, same machine as the browser) | `time.time()` wall clock, epoch ms | `ms` = bridge receipt of the FicTrac packet; `rx_off` = bridge receipt of a Studio echo; `rx` = the BROWSER's `Date.now()` when it parsed the drained 0xA9 block (not the bridge); `t0` in `frame_schema` = log origin (epoch ms) | every row it writes; `frame_schema.t0`; `log_control_ack` |
 | **Studio** (browser, `js/arena-session.js`) | `Date.now()` epoch for stamps, `performance.now()` for durations | `t_off` = `Date.now() − t0` when the command is SENT; `dt` = monotonic round trip **including queue wait** (single-flight link) | `["a", t_off, dt, hex, status, rx_off(, error)]` |
-| **controller** (Teensy, `micros()` u32, wraps every 71.6 min) | `t_us` | CMD record: dispatch entry of every command; FRAME record: **start of the SPI transfer** of a displayed frame change; STATE records: at the event; 0xA9 block header `t_now_us`: reply time | ring records → `cc` / `cf` / `cs` rows (`rx` = bridge receipt of the DRAIN, not of the event) |
+| **controller** (Teensy, `micros()` u32, wraps every 71.6 min) | `t_us` | CMD record: dispatch entry of every command; FRAME record: **start of the SPI transfer** of a displayed frame change; STATE records: at the event; 0xA9 block header `t_now_us`: reply time | ring records → `cc` / `cf` / `cs` rows (`rx` = the browser's parse time of the DRAIN block, not of the event) |
 
 Known relationships (measured): host↔controller drift **−3 ppm** (fit of `a`-row send time vs `cc.t_us` paired by
 order, 2026-09-12); Chrome background-tab throttling quantises timers to ~1 s (night 1). Missing today: **no field
@@ -94,7 +96,7 @@ end-to-end latency (FicTrac frame → LED) is wanted (§4).
 | dispatch → SPI start | `cc.t_us` → next `cf.t_us` (seq+1) = 4.7 ms median / 5.8 p99 at 100 Hz (2026-09-12); now directly as `cf.req_age_us` per displayed frame | measured; now first-class |
 | SPI start → photons | `spi_us` 0.77 ms is the transfer; panel latch + LED update after that is **unmeasured** (needs an optical sensor) | not measured |
 | controller reply → Studio | `a.dt` − (controller time) — `dt` includes queue wait, so subtract the in-controller time from `cc`/`cf` pairing | derivable |
-| ring record → log | `rx` is drain receipt (≤ 100 ms late, up to seconds when the bridge refuses rows); ordering by `seq` is exact; a CMD is appended AFTER its handler's STATE records (lower seq for the STATEs, later `t_us`) | documented |
+| ring record → log | `rx` is the browser's drain-block parse time (≤ 100 ms late, up to seconds when the bridge refuses rows); ordering by `seq` is exact; a CMD is appended AFTER its handler's STATE records (lower seq for the STATEs, later `t_us`) | documented |
 
 ## 4. How to determine round-trip latency (recipe for the review)
 
@@ -168,7 +170,7 @@ light. Options, cheapest first:
 - FRAME records exist only for displayed CHANGES; held frames and superseded loads are invisible except via
   `superseded` and the per-trial `sd_reads`.
 - `sd_slow_ctx` is sticky last-error context, not per-read evidence; `sd_slow` is a threshold event (10 ms).
-- The bridge log's `rx` for ring rows can lag by the drain period (100 ms) or more when the bridge refuses rows.
+- `rx` for ring rows (stamped by the browser at block parse) can lag by the drain period (100 ms) or more when the bridge refuses rows.
 - Ring capacity ≈ 5–6 s of Mode-3 traffic; drops are counted (`dropped`, seq gaps) — the trial-quality module marks
   such trials `unknown`.
 - No log carries which physical card served runs before 2026-09-13 11:44 ET (0xCD did not exist).

From d578868f48d9408256d8499f406dab9aeb9a3f32 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 20:13:50 -0400
Subject: [PATCH 56/67] =?UTF-8?q?docs(bench=20log):=20clean=20drill=20run?=
 =?UTF-8?q?=20=E2=80=94=20coverage=20200/200,=20verdict=20correct,=20no=20?=
 =?UTF-8?q?stall=20in=20this=20window?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/development/mode3-wedge-soak-plan.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/docs/development/mode3-wedge-soak-plan.md b/docs/development/mode3-wedge-soak-plan.md
index ec3ba71c..69e39273 100644
--- a/docs/development/mode3-wedge-soak-plan.md
+++ b/docs/development/mode3-wedge-soak-plan.md
@@ -578,6 +578,11 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   ignored.** Also fixed: simulator field 22 written in ms instead of ns (every sim log's `ft` was 1000× too small;
   found by the telemetry-review session) — sim restarted 19:55 with the fix; a footer stamp mangled by `sed -E`.
   `pixi run test` green. Retrying the drill with a single start.
+- **2026-09-13 20:09–20:13 ET — drill, single start, arm 3, pattern 36, 180 s:** 34,821 reads over **200/200
+  frames**, legacy arm applied, −1 step at the legacy cost; **0 stalls this time** (max read 3.4 ms); verdict 1 trial
+  `pass`, `trial_quality` after the last controller row, counts reconciled (34,820 cc / 34,822 a). The Studio banner
+  for a real stall therefore remains unexercised (the 19:49 run had the stall but the overlapping-run bug ate it).
+  20:14: arm back to 0 (production); watchdog drill next.
 
 ## 11. T4 as built (2026-09-12) — soak with ring-buffer logging
 

From ddbf721f5dc83be04760afa3d565c463fc3a2a27 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 20:17:45 -0400
Subject: [PATCH 57/67] =?UTF-8?q?fix(studio):=20link-drop=20fault=20classi?=
 =?UTF-8?q?fication=20also=20when=20the=20terminal=20event=20precedes=20th?=
 =?UTF-8?q?e=20disconnect=20listener=20(session=20already=20down)=20?=
 =?UTF-8?q?=E2=80=94=20v0.79?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 arena_studio.html                              | 8 ++++++--
 docs/development/arena-studio-release-notes.md | 2 ++
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/arena_studio.html b/arena_studio.html
index 5448aa73..b86f4e66 100644
--- a/arena_studio.html
+++ b/arena_studio.html
@@ -2959,7 +2959,7 @@ <h2 id="modalTitle">Import error</h2>
 </div>
 
 <footer id="footer">
-  <span class="foot-left">Arena Studio v0.79 | 2026-09-13 19:55 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.79 | 2026-09-13 20:17 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)">
@@ -3201,7 +3201,11 @@ <h2 id="modalTitle">Import error</h2>
             // runSteps also does, as a fallback) left the stored outcome ABORTED_BY_USER and
             // skipped the auto-commit (whole-stack review, 2026-09-13).
             const sm = s && s.summary;
-            if (sm && !sm.fault && sm.aborted && Studio._linkDropped && !Studio._userStopRequested) {
+            // `_linkDropped` is set by the Studio's own disconnect listener, which can run AFTER the
+            // broker has already aborted the runner (bench 2026-09-13, forced watchdog reset: the
+            // terminal event arrived with fault null). The link being down at the terminal event
+            // of an abort nobody requested is the same evidence — use either.
+            if (sm && !sm.fault && sm.aborted && !Studio._userStopRequested && (Studio._linkDropped || !(Studio.session && Studio.session.connected))) {
                 sm.fault = 'link_dropped';
                 sm.faultDetail = { kind: 'link_dropped', note: 'controller re-enumerated mid-run (watchdog self-reset?)' };
             }
diff --git a/docs/development/arena-studio-release-notes.md b/docs/development/arena-studio-release-notes.md
index 078ba03a..fc04f9dd 100644
--- a/docs/development/arena-studio-release-notes.md
+++ b/docs/development/arena-studio-release-notes.md
@@ -14,6 +14,8 @@ history lives here. Newest first. (Per-session engineering detail stays in
 - **Frame counts come from the card.** After the SD listing the Studio reads every pattern's header
   (`GET_PATTERN_INFO`), so the closed-loop heading→index modulus is right for patterns whose thumbnail
   was never rendered (an 8 MB pattern used to fall back to 200 frames and wrap).
+- **A link drop mid-run is a controller fault even when the runner's terminal event beats the disconnect
+  listener** (the link being down at an abort nobody requested is the evidence; forced-watchdog drill, bench).
 - **The stimulus-quality verdict is bound to its run.** A late terminal event from a previous, aborted run
   can no longer finalize the next run's trials (it did once on the bench, one second into a drill, and
   the real stall went unjudged).

From 8df0b680e7f2ed9678ca0ff6c2fd8980bd609663 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 20:17:48 -0400
Subject: [PATCH 58/67] =?UTF-8?q?docs(bench=20log):=20forced=20watchdog=20?=
 =?UTF-8?q?drill=20=E2=80=94=20full=20recovery=20chain,=20reconnect=20with?=
 =?UTF-8?q?out=20picker,=20two=20lit=20panels,=20outcome-classification=20?=
 =?UTF-8?q?fix?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/development/mode3-wedge-soak-plan.md | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/docs/development/mode3-wedge-soak-plan.md b/docs/development/mode3-wedge-soak-plan.md
index 69e39273..1928a421 100644
--- a/docs/development/mode3-wedge-soak-plan.md
+++ b/docs/development/mode3-wedge-soak-plan.md
@@ -583,6 +583,17 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   `pass`, `trial_quality` after the last controller row, counts reconciled (34,820 cc / 34,822 a). The Studio banner
   for a real stall therefore remains unexercised (the 19:49 run had the stall but the overlapping-run bug ate it).
   20:14: arm back to 0 (production); watchdog drill next.
+- **2026-09-13 20:14–20:17 ET — drill step 2, forced watchdog reset (R2):** production arm, drill trial started
+  20:14:05; `SET_TELEMETRY` flags 0x31 (starve) sent 20:15:07 → controller reset ≈ 2 s later → link dropped →
+  runner aborted → **post-mortem `self-reset`**: quiet → confirm 0xC2 → HEALTH → ring dump (`survivedReboot: true`,
+  19 records, the last FRAMEs before the reset intact) → crash report (`present: false`, as expected for a watchdog
+  reset) → probes → firmware identity; ring rows include kind 1 `boot` and kind 8 `wdog_context`; **the Studio
+  reconnected WITHOUT a port picker** (the Web Serial grant survived the re-enumeration — the unattended night can
+  recover from a watchdog reset); soak iteration-end `outcome: fault, fault: link_dropped, postmortem: self-reset`;
+  the trial `unknown` (correct). Two findings: (1) **two panels stayed lit after the reset** (Michael) — the boot
+  blank's three dark frames did not reach them; all-off sent 20:17:08 to see whether the bus takes it now; (2) the
+  runner's terminal event carried `fault: null` because the disconnect listener ran after the broker's abort → the
+  run's stored outcome would read ABORTED_BY_USER — fixed in v0.79 (link down at an unrequested abort ⇒ fault).
 
 ## 11. T4 as built (2026-09-12) — soak with ring-buffer logging
 

From a03d3c721c130fcd761332600f04a6b68a412107 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 20:20:14 -0400
Subject: [PATCH 59/67] docs: USB-unplug drill (controller does not reset;
 Studio recovers), boot-blank fix note; lab plan test D expectation corrected

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/development/lab-test-day-windows-2026-09-14.md | 2 +-
 docs/development/mode3-wedge-soak-plan.md           | 8 ++++++++
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/docs/development/lab-test-day-windows-2026-09-14.md b/docs/development/lab-test-day-windows-2026-09-14.md
index 852176cd..ab468d3e 100644
--- a/docs/development/lab-test-day-windows-2026-09-14.md
+++ b/docs/development/lab-test-day-windows-2026-09-14.md
@@ -63,7 +63,7 @@ Studio: File ▾ → Open → `protocols/soak_mode3_stress.yaml`; rig `cshl_g6_2
 | A | **Soak, 3 iterations (~1 h):** File ▾ → Soak…, `iterations 3, gap 10 s, first fault halt, then reset-continue, max resets 3` | `soak ended (iterations) after 3 iteration(s), 0 fault(s), 0 reset(s)`; every iteration banner `… pass · 0 flagged · 0 unknown` | 0 faults, 0 resets, 60 of 60 trials pass |
 | B | **Injected stall** (checks the flagging path): in the browser console `await Studio.setSdDiag(3)`, open `protocols/mode3_drill_1trial.yaml` and run it as a 1-iteration Soak (File ▾ → Soak…, iterations 1), then `await Studio.setSdDiag(0)` | during the run: `display gap NN ms (sd_slow, body) in trial …` lines; at the end `⚠ stimulus quality: … flagged`; after `setSdDiag(0)`, Console identity shows `sd diag 0` | at least one trial flagged; the soak did NOT stop; switches back to 0 |
 | C | **Simulator kill:** during a Soak (start a 2-iteration soak), close the sim window for 30 s, restart it | `soak: no FicTrac frames — waiting for the simulator`, then the next iteration starts | soak resumes by itself; no fault counted |
-| D | **Link drop:** during a trial pull the controller's USB cable, wait 5 s, plug it back | `run ended by a link drop … treating as a controller event`; post-mortem lines (`confirm`, `probe`, `reconnect`); the run's outcome `CONTROLLER_FAULT`; the arena goes **dark** on replug and stays dark until the next trial | reconnects without a page reload; next iteration runs |
+| D | **Link drop:** during a trial pull the controller's USB cable, wait 5 s, plug it back | `run ended by a link drop … treating as a controller event`; post-mortem lines (`confirm`, `probe`, `reconnect`); the run's outcome `CONTROLLER_FAULT`. The controller is powered from the arena supply, so it does NOT reset: the panels keep the last stimulus until the next trial or an all-off (bench 2026-09-13). If the Studio asks for the port again, pick the Teensy — on the bench it reconnected by itself | reconnects; next iteration runs |
 | F | **An old course protocol runs unchanged:** sign in to the course repo (Settings), open rig1 `p3-heisenberg-ts-full.yaml`, run it once as a Test run (simulator running) | it runs to the end exactly as in July; banner `… pass`; the run log has `trial_quality` and `run_metadata.firmware` = `488d5b9b …` | completes, all trials pass |
 | E | **Panel firmware update still works with the watchdog** (5 min, only if a spare panel/known-good image is at hand): Console → Firmware → program one panel | progress completes; no controller reboot mid-update (the Console would show a disconnect) | update completes |
 
diff --git a/docs/development/mode3-wedge-soak-plan.md b/docs/development/mode3-wedge-soak-plan.md
index 1928a421..91bd7b2e 100644
--- a/docs/development/mode3-wedge-soak-plan.md
+++ b/docs/development/mode3-wedge-soak-plan.md
@@ -594,6 +594,14 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   blank's three dark frames did not reach them; all-off sent 20:17:08 to see whether the bus takes it now; (2) the
   runner's terminal event carried `fault: null` because the disconnect listener ran after the broker's abort → the
   run's stored outcome would read ABORTED_BY_USER — fixed in v0.79 (link down at an unrequested abort ⇒ fault).
+- **2026-09-13 20:17 ET — all-off from the Studio blanked the two panels** (bus fine; the boot blank was too early for
+  them) → one-line firmware fix: a second `blankPanelsAtBoot()` at the END of setup (`f736cae` in the port worktree,
+  built; Codex pass running; flash before the overnight with Michael's OK).
+- **2026-09-13 20:18–20:21 ET — drill step 3, USB cable pulled 5 s during a trial (Michael):** link dropped → runner
+  aborted → post-mortem `self-reset` path → ring dump `survivedReboot: true`, **no boot record: the controller never
+  rebooted** (it is powered from the arena supply; USB is data only) → crash report read → probes → **reconnected
+  without a port picker**; soak iteration-end `fault: link_dropped, postmortem: self-reset`. Panels kept the running
+  stimulus through the unplug (no reset, no blank) — expected; only a controller reset blanks them.
 
 ## 11. T4 as built (2026-09-12) — soak with ring-buffer logging
 

From 9fee4c72ca23d29650cf838f8dbd4396aa82b071 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 20:23:04 -0400
Subject: [PATCH 60/67] =?UTF-8?q?docs(bench=20log):=20power-cycle=20drill?=
 =?UTF-8?q?=20=E2=80=94=20fresh-ring=20recovery=20path=20works;=20boot-bla?=
 =?UTF-8?q?nk=20retry=20build=20781efe2?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/development/mode3-wedge-soak-plan.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/development/mode3-wedge-soak-plan.md b/docs/development/mode3-wedge-soak-plan.md
index 91bd7b2e..933fd72c 100644
--- a/docs/development/mode3-wedge-soak-plan.md
+++ b/docs/development/mode3-wedge-soak-plan.md
@@ -602,6 +602,12 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   rebooted** (it is powered from the arena supply; USB is data only) → crash report read → probes → **reconnected
   without a port picker**; soak iteration-end `fault: link_dropped, postmortem: self-reset`. Panels kept the running
   stimulus through the unplug (no reset, no blank) — expected; only a controller reset blanks them.
+- **2026-09-13 20:20–20:23 ET — drill step 4, arena power pulled ~10 s during a trial (Michael):** the controller
+  is on the arena supply → full power-on: link dropped → post-mortem `self-reset` → **fresh ring** (`survivedReboot:
+  false`, bootCount 0, records `boot`, `state_change ALL_OFF` from the boot blank), drainer incarnations 1 → 2
+  (old cursor discarded, not trusted), crash report read, probes, identity, reconnected; soak ended on the fault.
+  Codex on the boot-blank one-liner: no defect, "an unverified retry" — comment reworded, rebuilt `781efe2`;
+  verification = one forced reset with Michael counting dark panels after the flash.
 
 ## 11. T4 as built (2026-09-12) — soak with ring-buffer logging
 

From 6f6979b851641ab835619260f6ba9f64d718272b Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 20:35:55 -0400
Subject: [PATCH 61/67] docs: overnight started 20:35 ET on 781efe2 + Studio
 v0.79 (stress protocol, 10 h); drill results, panel observation, identities
 updated

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../development/lab-test-day-windows-2026-09-14.md |  8 ++++----
 .../mode3-reliability-handoff-2026-09-14.md        |  7 ++++---
 docs/development/mode3-wedge-soak-plan.md          | 14 ++++++++++++++
 .../overnight-soak-test-plan-2026-09-13.md         |  4 ++--
 4 files changed, 24 insertions(+), 9 deletions(-)

diff --git a/docs/development/lab-test-day-windows-2026-09-14.md b/docs/development/lab-test-day-windows-2026-09-14.md
index ab468d3e..bcdcadc3 100644
--- a/docs/development/lab-test-day-windows-2026-09-14.md
+++ b/docs/development/lab-test-day-windows-2026-09-14.md
@@ -9,7 +9,7 @@ what changed and why: `mode3-reliability-handoff-2026-09-14.md`.
 - [x] Firmware branch **`feat/mode3-reliability`** pushed (18:55 ET) — merge-candidate PR
       [reiserlab/LED-Display_G6_Firmware_Arena#56](https://github.com/reiserlab/LED-Display_G6_Firmware_Arena/pull/56)
       against `main` (Frank's per-board scheme + a 2×10 variant); the lab builds the SAME identity from it
-      (`488d5b9` is compiled in from git).
+      (`781efe2` is compiled in from git).
 - [ ] The CSHL 2×10 controller + its bench card (patterns 36 = bar, 46 = sine already on it) travel to the lab PC,
       or plan 10 extra minutes to upload the two patterns (step 3).
 - [ ] Overnight results from the Mac pasted into §6 of the hand-off document (the reference numbers for §5 below).
@@ -35,9 +35,9 @@ pio run -e teensy41-2-10-performance -t upload --upload-port COM5   # 2×10 vari
 Windows gotchas (fw PR #49 notes): the **first upload attempt often fails — run it again**; the arena must be powered;
 if the port vanishes, unplug/replug once. Then in Chrome: `pixi run python -m http.server 8092` in the webDisplayTools
 checkout → `http://localhost:8092/arena_studio.html?advanced=1&soak=1` → **Connect** → pick the Teensy port.
-**Look for**, in the Console log: `firmware 488d5b9b 2x10 2026-09-13 feat/mode3-reliability freerun sdfast`, then
+**Look for**, in the Console log: `firmware 781efe2b 2x10 2026-09-14 feat/mode3-reliability freerun sdfast`, then
 `session rig follows the controller: cshl_g6_2x10_ball (2×10)` (v0.79) and an `sd card: … SD8GB … FAT32 4 KiB
-clusters` line. If the label is not `488d5b9b`, stop: wrong build.
+clusters` line. If the label is not `781efe2b`, stop: wrong build. After ANY controller reset (flash, watchdog, power) glance at the arena: it should be dark; if a panel shows a glyph or the arena re-lights, send all-off from the Console (panel-side behaviour seen once on the bench).
 
 ## 3. Card check (2 min, or 10 with uploads)
 
@@ -64,7 +64,7 @@ Studio: File ▾ → Open → `protocols/soak_mode3_stress.yaml`; rig `cshl_g6_2
 | B | **Injected stall** (checks the flagging path): in the browser console `await Studio.setSdDiag(3)`, open `protocols/mode3_drill_1trial.yaml` and run it as a 1-iteration Soak (File ▾ → Soak…, iterations 1), then `await Studio.setSdDiag(0)` | during the run: `display gap NN ms (sd_slow, body) in trial …` lines; at the end `⚠ stimulus quality: … flagged`; after `setSdDiag(0)`, Console identity shows `sd diag 0` | at least one trial flagged; the soak did NOT stop; switches back to 0 |
 | C | **Simulator kill:** during a Soak (start a 2-iteration soak), close the sim window for 30 s, restart it | `soak: no FicTrac frames — waiting for the simulator`, then the next iteration starts | soak resumes by itself; no fault counted |
 | D | **Link drop:** during a trial pull the controller's USB cable, wait 5 s, plug it back | `run ended by a link drop … treating as a controller event`; post-mortem lines (`confirm`, `probe`, `reconnect`); the run's outcome `CONTROLLER_FAULT`. The controller is powered from the arena supply, so it does NOT reset: the panels keep the last stimulus until the next trial or an all-off (bench 2026-09-13). If the Studio asks for the port again, pick the Teensy — on the bench it reconnected by itself | reconnects; next iteration runs |
-| F | **An old course protocol runs unchanged:** sign in to the course repo (Settings), open rig1 `p3-heisenberg-ts-full.yaml`, run it once as a Test run (simulator running) | it runs to the end exactly as in July; banner `… pass`; the run log has `trial_quality` and `run_metadata.firmware` = `488d5b9b …` | completes, all trials pass |
+| F | **An old course protocol runs unchanged:** sign in to the course repo (Settings), open rig1 `p3-heisenberg-ts-full.yaml`, run it once as a Test run (simulator running) | it runs to the end exactly as in July; banner `… pass`; the run log has `trial_quality` and `run_metadata.firmware` = `781efe2b …` | completes, all trials pass |
 | E | **Panel firmware update still works with the watchdog** (5 min, only if a spare panel/known-good image is at hand): Console → Firmware → program one panel | progress completes; no controller reboot mid-update (the Console would show a disconnect) | update completes |
 
 Never power-cycle the controller after something odd: the evidence is in RAM until the Studio's post-mortem has read it.
diff --git a/docs/development/mode3-reliability-handoff-2026-09-14.md b/docs/development/mode3-reliability-handoff-2026-09-14.md
index 425dfa67..7ea0c80e 100644
--- a/docs/development/mode3-reliability-handoff-2026-09-14.md
+++ b/docs/development/mode3-reliability-handoff-2026-09-14.md
@@ -11,8 +11,8 @@ numbers given); this is the narrative and the map.
 | A | **controller wedge**: ~1 in 10 Mode-3 runs the controller went 100–500 ms per command, power cycle only (fw #50) | a race in `IntervalTimer::end()`: SET_FRAME_POSITION disarmed/re-armed the refresh timer per command; a PIT interrupt landing between the two left the PIT firing with a null callback (an ISR storm) | **free-running refresh timer** — 0x70 never touches the PIT; plus an atomic `end()`; plus a hardware watchdog that resets and records the PC if anything like it ever recurs | 24 soak iterations, 5.15 M commands, 0 wedges (was 1 in 10 runs) |
 | B | **display freezes of 30–90 ms** every ~24.5k frame reads of a large pattern (fw #54) | firmware FAT access: SdFat re-walked the file's cluster chain on backward seeks and looked up the next cluster inside every read that crossed a 4 KB cluster boundary; those FAT-sector reads hammered one physical block of the card until its read-disturb maintenance paused the card | **contiguous O(1) seeks** (`FsFile` + `contiguousRange()`): the FAT is read once at pattern open and never during a trial | 4-arm causal test 2026-09-13: FAT touched → stalls at the old spacing; FAT untouched, same read count → 0; production: 0 in 482k + 72k commands + 1 h at 286 Hz |
 
-**Candidate build:** firmware **`feat/mode3-reliability` @ `488d5b9`** — the stack on `main` (Frank's per-board scheme,
-PR #48) with a 2×10 variant; build `pio run -e teensy41-2-10-performance`, label `488d5b9 2x10 … freerun sdfast`, 0xCB
+**Candidate build:** firmware **`feat/mode3-reliability` @ `781efe2`** (`488d5b9` + a second panel blank at the end of setup) — the stack on `main` (Frank's per-board scheme,
+PR #48) with a 2×10 variant; build `pio run -e teensy41-2-10-performance`, label `781efe2b 2x10 … freerun sdfast`, 0xCB
 flags `0x7C`; merge-candidate PR reiserlab/LED-Display_G6_Firmware_Arena#56. Studio v0.79 (PRs #198 + #202). **Run sheet for the bench:** `archive/mode3-2026-09/soak-handoff-2026-09-14.md`; **lab test day on Windows (no Claude):** `lab-test-day-windows-2026-09-14.md`; **what the overnight tests:** `overnight-soak-test-plan-2026-09-13.md`.
 
 ---
@@ -130,7 +130,8 @@ behaviour samples; `cf` rows have 8 or 11 fields; readers go through `js/runlog-
 | 2026-09-13 15:12–16:12 | `75405ee` | 1 h production at 286 Hz, bar | 1.04 M commands, 0 reads > 1.8 ms, req_age max 3.0 ms |
 | 2026-09-13 16:12–18:16 | `e59767e` (review fixes) | campaign: 13 × 10 min at 286 Hz, 8 MB sine ⇄ 813 KB bar | 2.2 M commands; one 19.4 ms + one 6.4 ms data read 12 ms apart on the sine (single event, no driver error); everything else ≤ 1.8 ms |
 | 2026-09-13 18:16–21:00 | `e59767e` | campaign at 200 Hz | *(running; see the bench log)* |
-| 2026-09-13 night | `feat/mode3-reliability` (this stack on main/#48, 2×10 variant) | recovery drill + overnight Studio soak per `overnight-soak-test-plan-2026-09-13.md` | *(to be filled in the morning)* |
+| 2026-09-13 19:17–20:30 | `488d5b9` → `781efe2` | recovery drill through the Studio: injected stall arm (200/200 frames, verdict path proven; the one real stall fell into an overlapping-run bug, fixed), forced watchdog reset ×2, USB unplug, arena power cycle | all three recovery paths complete in the log (fault → self-reset → ring dump → reconnect without a picker); found and fixed: stale 20-frame bridge modulus, run-bound verdict finalize, link-drop outcome timing, boot blank reaching 18/20 panels (retry added), sim `ft` units |
+| 2026-09-13 20:35 → 09-14 | `781efe2` + Studio v0.79 | **overnight Studio soak**, stress protocol (8 MB sine ⇄ 813 KB bar) at 200 Hz, 10 h, halt on first fault | *(to be filled in the morning)* |
 | offline, every commit | — | firmware `pytest tests/test_telemetry_codec.py tests/test_sd_stall_stats.py` (17), `soak_mode3_selftest.py`; web `pixi run test` (all suites incl. 25 trial-quality, 41 telemetry-report, 65 arena-telemetry, 280 wire), `format-check` | green |
 | HIL (port free) | each flash | `test_firmware_version.py`, `test_health.py`, `test_telemetry.py` subsets | green except two pre-existing flakes and one open item (`test_loop_max_1s_window_is_populated` at 3 s uptime on `e59767e`; re-run at the drill) |
 
diff --git a/docs/development/mode3-wedge-soak-plan.md b/docs/development/mode3-wedge-soak-plan.md
index 933fd72c..0ae2752b 100644
--- a/docs/development/mode3-wedge-soak-plan.md
+++ b/docs/development/mode3-wedge-soak-plan.md
@@ -608,6 +608,20 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   (old cursor discarded, not trusted), crash report read, probes, identity, reconnected; soak ended on the fault.
   Codex on the boot-blank one-liner: no defect, "an unverified retry" — comment reworded, rebuilt `781efe2`;
   verification = one forced reset with Michael counting dark panels after the flash.
+- **2026-09-13 20:23–20:30 ET — flashed `781efe2` (boot-blank retry); all 20 panels dark after the flash reboot;
+  the Studio reconnected by itself (grant survived the bootloader trip). Forced watchdog reset 20:28:34 on a trial:**
+  recovery chain complete again (fault, self-reset, boot + wdog_context records, reconnect); **panels: 19 dark, one
+  showed a panel-side error glyph ("02/03"), then the arena came back lit** — the ring holds NO frame transfer after
+  the reboot (only identity/header reads incl. 48 × 0x88 from the frame-count fill, which reads headers via
+  `readPatternInfo`, no display), so the re-lighting is panel-side (persistent panels restoring their last frame after
+  the glyph), not a controller command. Not blocking for the night; lab plan: after any reset, check the arena and
+  send all-off if lit. Steady state to be confirmed by Michael.
+- **2026-09-13 20:35 ET — OVERNIGHT STARTED** (Studio v0.79 build 20:17 with all of tonight's fixes, firmware
+  `781efe2`, `protocols/soak_mode3_stress.yaml` = sine idx 46 (2000 frames, gain 0.18) ⇄ bar idx 36 (200 frames,
+  gain 1.8), simulator 200 Hz seed 1 jumps 90°/100 (restarted 19:55 with the ft fix), bridge 3.1 logging behavior_v2,
+  `sdDiag` 0, rig `cshl_g6_2x10_ball` derived, `hours: 10, gapS: 10, firstFault: halt, policy: reset-continue,
+  maxResets: 3`). Michael: "super fast pattern movement" — the sine at 0.18°/frame, as designed. Judge in the morning
+  per `overnight-soak-test-plan-2026-09-13.md` (T1–T8, L1–L7, R1–R5).
 
 ## 11. T4 as built (2026-09-12) — soak with ring-buffer logging
 
diff --git a/docs/development/overnight-soak-test-plan-2026-09-13.md b/docs/development/overnight-soak-test-plan-2026-09-13.md
index 10e0e011..2a916869 100644
--- a/docs/development/overnight-soak-test-plan-2026-09-13.md
+++ b/docs/development/overnight-soak-test-plan-2026-09-13.md
@@ -1,4 +1,4 @@
-# Overnight soak — what exactly we are testing for (2026-09-13, candidate firmware `488d5b9` on `feat/mode3-reliability` + Studio v0.79)
+# Overnight soak — what exactly we are testing for (2026-09-13, candidate firmware `781efe2` on `feat/mode3-reliability` + Studio v0.79; started 20:35 ET)
 
 Three questions, each with the metric, where it comes from in the log, the pass line, and the command that checks it.
 The overnight run goes through the **Studio** (soak driver + bridge + simulator), not the browser-free harness:
@@ -27,7 +27,7 @@ iterations, ≈ 560 trials, ≈ 6 M frame commands.
 
 | # | claim | metric | source | pass | check |
 |---|---|---|---|---|---|
-| L1 | **Every iteration produced one committed run log** with the tail (v0.78 ordering fix) | per file: `run_metadata` (firmware label `488d5b9b … freerun sdfast`, `sd_card`, `sd_diag` 0), `stream_schema`, `trial_quality` event present, and it comes AFTER the last `cc`/`cf`/`cs` row | run-log `.jsonl(.gz)` | 28 of 28 files; `trial_quality` last among controller rows in every file | `runlog-check.py` (below) |
+| L1 | **Every iteration produced one committed run log** with the tail (v0.78 ordering fix) | per file: `run_metadata` (firmware label `781efe2b … freerun sdfast`, `sd_card`, `sd_diag` 0), `stream_schema`, `trial_quality` event present, and it comes AFTER the last `cc`/`cf`/`cs` row | run-log `.jsonl(.gz)` | 28 of 28 files; `trial_quality` last among controller rows in every file | `runlog-check.py` (below) |
 | L2 | **Nothing lost in the drain** | drainer stats at iteration end: `dropped`, `gaps`, `notStored`, `errors`; `cc` accepted 0x70 count vs `a` accepted count | soak `iteration-end.telemetry`; row counts | all four 0; counts equal ±1 per file | `runlog-check.py` |
 | L3 | **Sequence continuity** across the night | ring `seq` of `cc`/`cf`/`cs` monotonic, no gap between files except at the ring's version/incarnation boundary (none expected) | rows field 3 | 0 gaps | `wedge-scan.py` `seq gaps` |
 | L4 | **Per-trial read accounting closes** | `sd_reads` (kind 13) present for every trial and ≈ index changes + 1 | `cs` kind 13, `cc` rows | every trial has it; |reads − (index changes + 1)| ≤ 2 | `telemetry-report.py` per-trial table (`reads_fw`) |

From 1252bf3b51012b664a766f3edbbbb0a0e84a1d39 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 21:36:38 -0400
Subject: [PATCH 62/67] =?UTF-8?q?docs(bench=20log):=20overnight=201=20h=20?=
 =?UTF-8?q?summary=20=E2=80=94=202=20iterations,=2040/40=20pass,=200=20sta?=
 =?UTF-8?q?lls,=20req=5Fage=20max=204.83=20ms?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/development/mode3-wedge-soak-plan.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/development/mode3-wedge-soak-plan.md b/docs/development/mode3-wedge-soak-plan.md
index 0ae2752b..6c740389 100644
--- a/docs/development/mode3-wedge-soak-plan.md
+++ b/docs/development/mode3-wedge-soak-plan.md
@@ -622,6 +622,12 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   `sdDiag` 0, rig `cshl_g6_2x10_ball` derived, `hours: 10, gapS: 10, firstFault: halt, policy: reset-continue,
   maxResets: 3`). Michael: "super fast pattern movement" — the sine at 0.18°/frame, as designed. Judge in the morning
   per `overnight-soak-test-plan-2026-09-13.md` (T1–T8, L1–L7, R1–R5).
+- **2026-09-13 21:36 ET — overnight, 1 h in: 2 iterations complete (1238 s each, ~231.7k commands each), 40/40
+  trials pass, 0 reads > 10 ms, req_age p50 1.68 / max 4.83 ms (under the 5 ms target), drainer dropped/gaps/
+  notStored/errors 0/0/0/0, both files contiguous; per-read cost sine 1.385 ms p50 random (max 1.80) vs bar 1.459
+  (max 1.80); superseded share 3.6 % (200 Hz commands vs 300 Hz refresh); `trial_quality` after the last controller
+  row in both files. Only checker complaint: host-accepted exceeds controller-recorded 0x70 by 21 per file (0.01 %,
+  the last ~100 ms before the file rolls) — tolerance question for `runlog-check`, morning item.
 
 ## 11. T4 as built (2026-09-12) — soak with ring-buffer logging
 

From cd5cb402dd544c9e6032522dfe543b577e1b2134 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 22:36:30 -0400
Subject: [PATCH 63/67] =?UTF-8?q?docs(bench=20log):=20overnight=202=20h=20?=
 =?UTF-8?q?summary=20=E2=80=94=205=20iterations,=20100/100=20pass,=200=20s?=
 =?UTF-8?q?talls?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/development/mode3-wedge-soak-plan.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/development/mode3-wedge-soak-plan.md b/docs/development/mode3-wedge-soak-plan.md
index 6c740389..fce39965 100644
--- a/docs/development/mode3-wedge-soak-plan.md
+++ b/docs/development/mode3-wedge-soak-plan.md
@@ -628,6 +628,8 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   (max 1.80); superseded share 3.6 % (200 Hz commands vs 300 Hz refresh); `trial_quality` after the last controller
   row in both files. Only checker complaint: host-accepted exceeds controller-recorded 0x70 by 21 per file (0.01 %,
   the last ~100 ms before the file rolls) — tolerance question for `runlog-check`, morning item.
+- **2026-09-13 22:36 ET — overnight, 2 h in: 5 iterations complete, 100/100 trials pass, 0 reads > 10 ms, req_age max
+  4.83 ms in every iteration, drainer 0/0/0/0 throughout, ~1.16 M commands; bridge + simulator alive.**
 
 ## 11. T4 as built (2026-09-12) — soak with ring-buffer logging
 

From bcc5aa49a974b8934be8bf51157b549d88a197c4 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 13 Sep 2026 23:46:19 -0400
Subject: [PATCH 64/67] =?UTF-8?q?docs(bench=20log):=20overnight=2023:45=20?=
 =?UTF-8?q?=E2=80=94=20one=2026=20ms=20sine=20read,=20trial=20flagged=20by?=
 =?UTF-8?q?=20the=20Studio,=20soak=20continues?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/development/mode3-wedge-soak-plan.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/development/mode3-wedge-soak-plan.md b/docs/development/mode3-wedge-soak-plan.md
index fce39965..8ec95f1f 100644
--- a/docs/development/mode3-wedge-soak-plan.md
+++ b/docs/development/mode3-wedge-soak-plan.md
@@ -630,6 +630,12 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   the last ~100 ms before the file rolls) — tolerance question for `runlog-check`, morning item.
 - **2026-09-13 22:36 ET — overnight, 2 h in: 5 iterations complete, 100/100 trials pass, 0 reads > 10 ms, req_age max
   4.83 ms in every iteration, drainer 0/0/0/0 throughout, ~1.16 M commands; bridge + simulator alive.**
+- **2026-09-13 23:45 ET — overnight event: one 26 ms body-phase read on the 8 MB sine (pattern 46, frame 1942,
+  trial 3 of iteration 9, no driver error) → the Studio emitted `display_gap` (sd_slow 26 ms + frame_age 26.2 ms) and
+  will flag the trial — the real-stall verdict path exercised for the first time; the soak continues (a stall is not
+  a fault).** Second data-region event of the day on the sine (17:40: 19.5 + 6.4 ms), none on the bar; both on the
+  contiguous fast path with no FAT access → card-internal, rate ≈ 1 per 2–3 M reads of the large file (≈ one per
+  3 h at 200 Hz). Below Michael's 30 ms "detectable" line, above the 10 ms flag line.
 
 ## 11. T4 as built (2026-09-12) — soak with ring-buffer logging
 

From decdcb6c3b3e574044a000fa54bcf5ce0a903b96 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Mon, 14 Sep 2026 06:43:49 -0400
Subject: [PATCH 65/67] fix(runlog-check): count host-accepted 0x70 rows only
 when reconciling with the controller's 0x70 count

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 scripts/runlog-check.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/scripts/runlog-check.py b/scripts/runlog-check.py
index cd4322bc..4a122b6a 100644
--- a/scripts/runlog-check.py
+++ b/scripts/runlog-check.py
@@ -35,7 +35,8 @@ def check_file(path):
             if isinstance(k, (int, float)):
                 fictrac += 1
             elif k == "a":
-                if o[4] == 0: a_ok += 1
+                # host-accepted FRAME commands only (hex "03 70 …"): the controller-side count below is 0x70-only too
+                if o[4] == 0 and isinstance(o[3], str) and o[3].startswith("03 70"): a_ok += 1
             elif k in ("cc", "cf", "cs"):
                 last_ctl_line = n
                 if k == "cc" and len(o) > 5 and o[4] == 0x70 and o[5] == 0: cc70 += 1

From a4203fccb74e5670340a647f687cd5bbd1000e43 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Mon, 14 Sep 2026 06:46:54 -0400
Subject: [PATCH 66/67] fix(runlog-check): accept both a-row hex spellings
 (Studio compact, harness spaced) for the 0x70 reconciliation

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 scripts/runlog-check.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/runlog-check.py b/scripts/runlog-check.py
index 4a122b6a..ebf62a2d 100644
--- a/scripts/runlog-check.py
+++ b/scripts/runlog-check.py
@@ -36,7 +36,7 @@ def check_file(path):
                 fictrac += 1
             elif k == "a":
                 # host-accepted FRAME commands only (hex "03 70 …"): the controller-side count below is 0x70-only too
-                if o[4] == 0 and isinstance(o[3], str) and o[3].startswith("03 70"): a_ok += 1
+                if o[4] == 0 and isinstance(o[3], str) and o[3].replace(" ", "").lower().startswith("0370"): a_ok += 1  # Studio "0370…", harness "03 70 …"
             elif k in ("cc", "cf", "cs"):
                 last_ctl_line = n
                 if k == "cc" and len(o) > 5 and o[4] == 0x70 and o[5] == 0: cc70 += 1

From eac5a78c832b8967082565f1a8b21d36590ccdc9 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Mon, 14 Sep 2026 06:53:49 -0400
Subject: [PATCH 67/67] =?UTF-8?q?docs:=20overnight=20benchmark=20results?=
 =?UTF-8?q?=20(29=20iterations,=200=20faults,=20579/1/0,=20one=2026=20ms?=
 =?UTF-8?q?=20read)=20in=20the=20hand-off,=20test=20plan=20=C2=A76,=20lab?=
 =?UTF-8?q?=20plan=20macOS=20column,=20bench=20log?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../lab-test-day-windows-2026-09-14.md        | 16 +++++-----
 .../mode3-reliability-handoff-2026-09-14.md   | 29 +++++++++++++++++--
 docs/development/mode3-wedge-soak-plan.md     |  6 ++++
 .../overnight-soak-test-plan-2026-09-13.md    | 21 ++++++++++++++
 4 files changed, 61 insertions(+), 11 deletions(-)

diff --git a/docs/development/lab-test-day-windows-2026-09-14.md b/docs/development/lab-test-day-windows-2026-09-14.md
index bcdcadc3..d27230fc 100644
--- a/docs/development/lab-test-day-windows-2026-09-14.md
+++ b/docs/development/lab-test-day-windows-2026-09-14.md
@@ -12,7 +12,7 @@ what changed and why: `mode3-reliability-handoff-2026-09-14.md`.
       (`781efe2` is compiled in from git).
 - [ ] The CSHL 2×10 controller + its bench card (patterns 36 = bar, 46 = sine already on it) travel to the lab PC,
       or plan 10 extra minutes to upload the two patterns (step 3).
-- [ ] Overnight results from the Mac pasted into §6 of the hand-off document (the reference numbers for §5 below).
+- [x] Overnight results from the Mac in §6 of the hand-off document (the reference numbers for §7 below).
 - [ ] Studio: PRs #198 + #202 merged to `main` first thing in the morning if the night is clean (Michael 17:30 ET:
       no separate review; the lab tests main; revert if anything is wrong). Until then the lab can serve the branch.
 
@@ -92,13 +92,13 @@ numbers must NOT change with the host; the host-side ones may — that differenc
 
 | metric | source | macOS (2026-09-13 night) | Windows lab PC | expect |
 |---|---|---|---|---|
-| host round trip `a`-row dt p50 / p99 | `wedge-scan.py` | fill in from the overnight | | Windows USB-CDC often +1–3 ms; p99 must stay ≤ 11 ms |
-| request→display `req_age_us` p50 / p99 / max | `telemetry-report.py` | 1.7 / 2.6 / ~3 ms | | same on both (controller-side) |
-| SD read cost +1 / random (p50, max) | `telemetry-report.py` | 0.62 / 1.46 ms, max 1.8 | | same on both |
-| drainer dropped / gaps / notStored | `runlog-check.py` (`drainer:`) | | | 0 / 0 / 0; Chrome background-tab throttling is the usual culprit — keep the Studio tab visible |
-| FicTrac rows per command | `runlog-check.py` (`fictrac_per_cmd`) | ≈ 1.0 during trials | | ≈ 1.0 |
-| commands accepted per iteration | `runlog-check.py` (`a_ok`) | ≈ 240 k | | within 2 % |
-| trials pass / flagged / unknown | banner / `trial_quality` | 20 / 0 / 0 | | 20 / 0 / 0 |
+| host round trip `a`-row dt p50 / p99 | `wedge-scan.py` | 3 / 4–11 ms (29 iterations; one 271 ms browser outlier) | | Windows USB-CDC often +1–3 ms; p99 must stay ≤ 11 ms |
+| request→display `req_age_us` p50 / p99 / max | `telemetry-report.py` | 1.75 / 2.56 / 4.83 ms | | same on both (controller-side) |
+| SD read cost +1 / random (p50, max) | `telemetry-report.py` | 0.62 / 1.39–1.46 ms, max 1.8 (sine / bar) | | same on both |
+| drainer dropped / gaps / notStored | `runlog-check.py` (`drainer:`) | 0 / 0 / 0 (29 iterations) | | 0 / 0 / 0; Chrome background-tab throttling is the usual culprit — keep the Studio tab visible |
+| FicTrac rows per command | `runlog-check.py` (`fictrac_per_cmd`) | 1.32 (includes the 10 s gaps) | | ≈ 1.0–1.3 |
+| commands accepted per iteration | `runlog-check.py` (`a_ok`) | 231–241 k | | within 2 % |
+| trials pass / flagged / unknown | banner / `trial_quality` | 20 / 0 / 0 (one iteration 19 / 1 / 0) | | 20 / 0 / 0 |
 
 Write the Windows column into this file and commit it on the branch (no Prettier on HTML; this is Markdown).
 
diff --git a/docs/development/mode3-reliability-handoff-2026-09-14.md b/docs/development/mode3-reliability-handoff-2026-09-14.md
index 7ea0c80e..78584313 100644
--- a/docs/development/mode3-reliability-handoff-2026-09-14.md
+++ b/docs/development/mode3-reliability-handoff-2026-09-14.md
@@ -131,7 +131,7 @@ behaviour samples; `cf` rows have 8 or 11 fields; readers go through `js/runlog-
 | 2026-09-13 16:12–18:16 | `e59767e` (review fixes) | campaign: 13 × 10 min at 286 Hz, 8 MB sine ⇄ 813 KB bar | 2.2 M commands; one 19.4 ms + one 6.4 ms data read 12 ms apart on the sine (single event, no driver error); everything else ≤ 1.8 ms |
 | 2026-09-13 18:16–21:00 | `e59767e` | campaign at 200 Hz | *(running; see the bench log)* |
 | 2026-09-13 19:17–20:30 | `488d5b9` → `781efe2` | recovery drill through the Studio: injected stall arm (200/200 frames, verdict path proven; the one real stall fell into an overlapping-run bug, fixed), forced watchdog reset ×2, USB unplug, arena power cycle | all three recovery paths complete in the log (fault → self-reset → ring dump → reconnect without a picker); found and fixed: stale 20-frame bridge modulus, run-bound verdict finalize, link-drop outcome timing, boot blank reaching 18/20 panels (retry added), sim `ft` units |
-| 2026-09-13 20:35 → 09-14 | `781efe2` + Studio v0.79 | **overnight Studio soak**, stress protocol (8 MB sine ⇄ 813 KB bar) at 200 Hz, 10 h, halt on first fault | *(to be filled in the morning)* |
+| 2026-09-13 20:35 → 09-14 06:52 | `781efe2` + Studio v0.79 | **overnight Studio soak**, stress protocol (8 MB sine ⇄ 813 KB bar) at 200 Hz, 29 iterations / 10.3 h, halt on first fault | **0 faults, 0 resets, 6.9 M commands; 579 trials pass, 1 flagged (one 26 ms read on the 8 MB sine at 23:45), 0 unknown; every other read ≤ 1.8 ms; req_age max 4.83 ms in 28 of 29 iterations; drainer 0/0/0/0 throughout; every log complete** |
 | offline, every commit | — | firmware `pytest tests/test_telemetry_codec.py tests/test_sd_stall_stats.py` (17), `soak_mode3_selftest.py`; web `pixi run test` (all suites incl. 25 trial-quality, 41 telemetry-report, 65 arena-telemetry, 280 wire), `format-check` | green |
 | HIL (port free) | each flash | `test_firmware_version.py`, `test_health.py`, `test_telemetry.py` subsets | green except two pre-existing flakes and one open item (`test_loop_max_1s_window_is_populated` at 3 s uptime on `e59767e`; re-run at the drill) |
 
@@ -157,8 +157,31 @@ same-index skip does not affect the stalls (it saves 24 % of reads). Arm 3 also
 (see the bench log for the numbers). **Per-read cost on the production build:** +1 step 0.62 ms; random/backward
 1.39–1.46 ms median, 1.8 ms max; request→display age 1.7 ms median, 2.9 ms max at 200 Hz.
 
-**Overnight benchmark (candidate build):** *to be filled in the morning from `telemetry-report.py` over the campaign
-segments — stalls, clusters, per-file read cost, request ages, reboots.*
+**Overnight benchmark (candidate `781efe2` + Studio v0.79, 2026-09-13 20:35 → 09-14 06:52 ET, 29 iterations,
+10.3 h, `soak_mode3_stress.yaml` at 200 Hz, simulator seed 1 with 90° jumps every 100 samples):**
+
+| metric | result | pass line |
+|---|---|---|
+| controller faults / resets / watchdog | 0 / 0 / 0 | 0 |
+| commands accepted | 6,853,000 (≈ 238k per 21-min iteration) | — |
+| trials pass / flagged / unknown | 579 / 1 / 0 | 0 unknown |
+| SD reads over 10 ms | 1 (26.0 ms, sine frame 1942, body phase, no driver error, followed 2 frames later by 6.6 ms) | report |
+| every other read | ≤ 1.8 ms (2 reads over 3 ms in 5.86 M) | — |
+| per-read cost, sine (8 MB) | +1 0.62 ms · random 1.39 ms p50 / 1.77 p99 / 1.80 max | ≤ 1.5 p50, ≤ 1.8 max |
+| per-read cost, bar (813 KB) | +1 0.62 ms · random 1.46 ms p50 / 1.75 p99 / 1.80 max | same |
+| request→display age | 1.75 ms p50 · 2.56 p99 · 4.83 max (26.2 in the event iteration) | p99 < 5, max < 10 |
+| superseded loads | 1.39 % of frames (200 Hz commands vs 300 Hz refresh) | < 2 % |
+| index coverage per iteration | bar 200/200, sine 2000/2000 | ≥ 95 % |
+| host round trip (`a` rows) | 3 ms median every file · p99 4–11 ms · one 271 ms outlier (browser) | p99 ≤ 11 |
+| drainer dropped / gaps / refused / errors | 0 / 0 / 0 / 0 in all 29 iterations | 0 |
+| log completeness (`runlog-check`) | 29 / 29 complete (the flagged file is complete and correctly flagged); controller vs host 0x70 counts equal; `trial_quality` after the last controller row | all |
+| ring incarnations / boot count | unchanged all night (2 / 2) | unchanged |
+
+Interpretation: problem A did not recur in 6.9 M commands; problem B's FAT stalls did not recur in 5.9 M reads. The
+one 26 ms event (and the 19.5 + 6.4 ms pair at 17:40 the same day) are on the 8 MB file only, on the contiguous
+path with no FAT access — a card-internal data-region episode at roughly one per 3 M reads of the large file (one
+flagged trial per ~4 h at 200 Hz). Course-sized patterns saw nothing all day. Remedies if that rate matters: the
+read-free RAM path for large patterns (§7) or a card comparison with `sd_stall_test.py`.
 
 ## 7. Known limits and open items
 
diff --git a/docs/development/mode3-wedge-soak-plan.md b/docs/development/mode3-wedge-soak-plan.md
index 8ec95f1f..85d2cc37 100644
--- a/docs/development/mode3-wedge-soak-plan.md
+++ b/docs/development/mode3-wedge-soak-plan.md
@@ -636,6 +636,12 @@ count (#199). Logs: `soak-logs/arena-log-20260912-001625-545.jsonl` (wedge) and
   a fault).** Second data-region event of the day on the sine (17:40: 19.5 + 6.4 ms), none on the bar; both on the
   contiguous fast path with no FAT access → card-internal, rate ≈ 1 per 2–3 M reads of the large file (≈ one per
   3 h at 200 Hz). Below Michael's 30 ms "detectable" line, above the 10 ms flag line.
+- **2026-09-14 06:52 ET — OVERNIGHT COMPLETE: 29 iterations / 10.3 h (reason `hours`), 0 faults, 0 resets,
+  6.85 M commands, 579 trials pass / 1 flagged / 0 unknown; the only event the 23:45 26 ms read; every other read
+  ≤ 1.8 ms; req_age p50 1.75 / p99 2.56 / max 4.83 ms; superseded 1.39 %; host RTT 3 ms median every file, p99
+  4–11 ms; drainer 0/0/0/0 in every iteration; `runlog-check` 29/29 complete (after correcting its host-side count to
+  0x70 rows in both hex spellings); `wedge-scan` 0 onsets. Full table: hand-off §6. Next: Studio #198 → #202 to
+  `main` (squash), lab day on PR #56's `781efe2`.**
 
 ## 11. T4 as built (2026-09-12) — soak with ring-buffer logging
 
diff --git a/docs/development/overnight-soak-test-plan-2026-09-13.md b/docs/development/overnight-soak-test-plan-2026-09-13.md
index 2a916869..3bade197 100644
--- a/docs/development/overnight-soak-test-plan-2026-09-13.md
+++ b/docs/development/overnight-soak-test-plan-2026-09-13.md
@@ -84,3 +84,24 @@ pixi run python scripts/runlog-check.py soak-logs/arena-log-*.jsonl*      # L1,
 ```
 Fill the tables above with numbers, then §6 of `mode3-reliability-handoff-2026-09-14.md` ("Overnight benchmark").
 Anything red → the log excerpt goes into the bench log with its ET time before anyone touches the controller.
+
+## 6. Results (2026-09-14 06:52 ET; details in `mode3-reliability-handoff-2026-09-14.md` §6)
+
+| # | pass? | measured |
+|---|---|---|
+| T1 | ✅ | 0 faults, 0 resets, 0 timeouts in 29 iterations (`wedge-scan`: 0 onsets) |
+| T2 | ✅ (1 flagged) | 1 read > 10 ms in 5.86 M (26 ms, sine); 579 pass / 1 flagged / 0 unknown |
+| T3 | ✅ | req_age p50 1.75 · p99 2.56 · max 4.83 ms (26.2 in the event iteration); no drift |
+| T4 | ✅ | host RTT median 3 ms in every file, p99 4–11 ms; one 271 ms browser outlier |
+| T5 | ✅ | superseded 1.39 %; 0 `timer_fail` |
+| T6 | ✅ | sine 1.39 / bar 1.46 ms p50 random, both max 1.80; +1 0.62 ms |
+| T7 | ✅ | boot count and incarnations unchanged all night |
+| T8 | ✅ | 200/200 and 2000/2000 distinct indices in every iteration |
+| L1–L7 | ✅ | 29/29 files complete; counts equal; verdict after the last controller row; drainer 0/0/0/0; 46 MB raw per iteration |
+| R1 | — | no wedge occurred |
+| R2 | ✅ (drill) | forced watchdog reset ×2: full chain, panels blanked (retry build), reconnect without picker |
+| R3 | ✅ (live) | the 26 ms read → `display_gap` events, trial flagged, soak continued |
+| R4 | ✅ (drill 09-11) | not exercised tonight |
+| R5 | ✅ | no drops; the coverage path was exercised by the drills' drain errors → `unknown` |
+Drills also covered a USB unplug (link drop without reset) and an arena power cycle (fresh ring recognised).
+Untested list in §4 unchanged.