From afbb5cc9aeb878823d452197fbdb7e712e82bbd9 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Thu, 24 Sep 2026 00:15:05 -0400
Subject: [PATCH 1/3] feat(studio): assert sticky controller settings before
 every run; controller: block, rig defaults, run header (v0.88)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Design: docs/development/controller-settings-strategy.md (Codex-reviewed). Wiring lives in the rig
YAML, experiment semantics in the protocol, and every sticky setting a run depends on is asserted
(GET → SET → GET) before the run, refused on mismatch, and recorded in the run header. No
restore-at-end.

- js/controller-settings.js (new): pure planner — normalizeControllerBlock, planAssertions (rig
  identity, panel mode + capability, refresh derived from pattern grayscale + rig cap, panel
  firmware footer + fleet verify), formatSnapshot. tests/test-controller-settings.js (42 checks).
- js/plugin-registry.js: parseRigIo → defaults.panel_mode, limits.max_refresh_hz,
  requires.panel_firmware, strict, name.
- js/protocol-yaml-v3.js: top-level controller: block (extractControllerBlock; malformed values are
  blocking errors; missing requires token warns); WEB_RUNNER_CAPABILITIES = [controller_block].
- arena_studio.html: rig defaults.panel_mode applied at connect; Studio.assertControllerSettings
  runs in runOnce for Run AND Test, blocks with a banner; readControllerSnapshot → run header
  meta.controller + transcript line; run gate shows the planned verdict; Settings → Controller
  card with live snapshot and Verify panels (fleet 0xC9); batch flasher stores its verify result.
- validate-protocol.mjs: prints the block, cross-checks the rig file (cap, policy, firmware).
- configs/rigs: bergamo_g6_2x10_2p.yaml (triggered, 300 Hz cap, firmware 2p, strict) + index;
  course rigs gain defaults.panel_mode: persistent.
- protocols: both 2P protocols point at the Bergamo rig and carry the controller block.
- docs: controller-settings.md (user), strategy (implemented), SKILL.md section, rig checklist,
  release notes v0.88; pixi test list.

Tests: full pixi run test green (one legacy assertion updated for the new capability token);
every inline Studio script parses.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .agents/skills/protocol-yaml/SKILL.md         |  33 ++
 .../scripts/validate-protocol.mjs             |  40 +++
 arena_studio.html                             | 311 +++++++++++++++++-
 configs/rigs/bergamo_g6_2x10_2p.yaml          |  55 ++++
 configs/rigs/cshl_g6_2x10.yaml                |   5 +
 configs/rigs/cshl_g6_2x10_ball.yaml           |   5 +
 configs/rigs/cshl_g6_2x8.yaml                 |   5 +
 configs/rigs/g6_3x10.yaml                     |   5 +
 configs/rigs/g6_4x10.yaml                     |   5 +
 configs/rigs/index.json                       |   6 +
 .../development/2p-line-sync-rig-checklist.md |  10 +-
 .../controller-settings-strategy.md           | 106 ++++++
 docs/development/controller-settings.md       | 124 +++++++
 js/controller-settings.js                     | 272 +++++++++++++++
 js/plugin-registry.js                         |  53 +++
 js/protocol-yaml-v3.js                        |  95 +++++-
 protocols/g6_2x10_2p_diagnostics.yaml         |  15 +-
 protocols/g6_2x10_2p_duty_sweep.yaml          |  18 +-
 tests/fixtures/v3_controller_block.yaml       |  54 +++
 tests/test-controller-settings.js             | 117 +++++++
 tests/test-protocol-roundtrip-v3.js           |  41 +++
 tests/test-studio-runtime-vars.js             |   2 +-
 22 files changed, 1367 insertions(+), 10 deletions(-)
 create mode 100644 configs/rigs/bergamo_g6_2x10_2p.yaml
 create mode 100644 docs/development/controller-settings-strategy.md
 create mode 100644 docs/development/controller-settings.md
 create mode 100644 js/controller-settings.js
 create mode 100644 tests/fixtures/v3_controller_block.yaml
 create mode 100644 tests/test-controller-settings.js

diff --git a/.agents/skills/protocol-yaml/SKILL.md b/.agents/skills/protocol-yaml/SKILL.md
index 04670c18..8324f96b 100644
--- a/.agents/skills/protocol-yaml/SKILL.md
+++ b/.agents/skills/protocol-yaml/SKILL.md
@@ -314,6 +314,39 @@ changes may tune a trial, never restructure it. Web-only; MATLAB ignores `runtim
 to run it** until the web runner implements that capability; MATLAB may run it. Leave it out
 otherwise.
 
+### `controller:` — sticky controller settings the run must assert (Studio v0.93)
+
+The controller keeps a few **sticky** settings across runs (panel display mode, refresh rate,
+Digital IO roles…). Wiring belongs in the rig YAML; what the *experiment* needs goes in a
+top-level `controller:` block, and the Studio asserts it before every run (GET → SET → GET,
+refuse on mismatch) and writes the before/after snapshot into the run header. Design:
+`docs/development/controller-settings-strategy.md`; user doc: `docs/development/controller-settings.md`.
+
+```yaml
+rig: "./configs/rigs/bergamo_g6_2x10_2p.yaml"
+requires: [controller_block]        # a runner without this feature REFUSES the file instead of ignoring the block
+controller:
+  panel_mode: triggered             # 0 oneshot | 1 persistent | 2 triggered | 3 gated (names or numbers)
+  refresh_policy: line_sync_safe    # cap the re-stream rate at the rig's limits.max_refresh_hz — OR refresh_hz: <int>
+  panel_firmware: "2p"              # SD footer version (or prefix) the panel image must match; "2p" = the line-sync build
+```
+
+- **Most protocols do not need the block.** A course protocol inherits the rig's
+  `defaults.panel_mode` (persistent); the Studio asserts that too. Only declare a mode when the
+  experiment depends on it (imaging: `triggered`).
+- **A protocol with a `controller:` block is strict**: rig mismatch (its `rig:` vs the session
+  rig), an unreadable setting, or the wrong panel firmware **blocks the run** (green and blue
+  buttons). On rigs with `strict: true` in the rig YAML this holds for every protocol.
+- `refresh_hz` and `refresh_policy` are mutually exclusive. Prefer the policy: the refresh a
+  pattern needs follows its grayscale (GS2 streams at 1000 Hz by default, GS16 at 300), so the
+  Studio derives it from the referenced patterns and the rig cap; a bare number is for refresh
+  experiments only and must not exceed the rig's `limits.max_refresh_hz`.
+- Panel firmware is checked against the SD footer (what image was uploaded) **and** the
+  session's fleet verify (which panels actually run it). Unverified panels only warn; a failed
+  verify blocks. Settings → Controller → *Verify panels* runs the fleet check (~1 s per panel).
+- The validator prints the block and cross-checks it against the rig file when that is in the repo.
+- MATLAB does not implement the block yet; the `requires` token is what makes it refuse.
+
 ## Plugins
 
 `plugins:` normally comes from the rig (the Studio pre-fills New protocols from the rig
diff --git a/.agents/skills/protocol-yaml/scripts/validate-protocol.mjs b/.agents/skills/protocol-yaml/scripts/validate-protocol.mjs
index 7a9ec9f6..effc7bd8 100644
--- a/.agents/skills/protocol-yaml/scripts/validate-protocol.mjs
+++ b/.agents/skills/protocol-yaml/scripts/validate-protocol.mjs
@@ -71,6 +71,46 @@ if (Array.isArray(exp.requires) && exp.requires.length) {
     console.log('ℹ requires: [' + exp.requires.join(', ') + ']' +
         (missing.length ? ' — the WEB runner refuses to run this (missing: ' + missing.join(', ') + ')' : ''));
 }
+// ── controller: block (sticky controller settings asserted before the run) ──────
+// docs/development/controller-settings-strategy.md. Malformed values are already in
+// `blocking` (collectBlockingErrors); here: what it declares, the capability token, and a
+// cross-check against the rig file when it is readable from the repo root.
+const cb = exp.controller;
+if (cb && cb.declared) {
+    const parts = [];
+    if (cb.panel_mode != null) parts.push('panel_mode ' + cb.panel_mode + ' (' + ['oneshot', 'persistent', 'triggered', 'gated'][cb.panel_mode] + ')');
+    if (cb.refresh_hz != null) parts.push('refresh_hz ' + cb.refresh_hz);
+    if (cb.refresh_policy) parts.push('refresh_policy ' + cb.refresh_policy);
+    if (cb.panel_firmware) parts.push('panel_firmware "' + cb.panel_firmware + '"');
+    console.log('ℹ controller: ' + (parts.join(', ') || '(empty block)') + ' — asserted by the Studio before every run, recorded in the run header');
+    const rigPath = String(exp.rig_path || '');
+    const rigFile = rigPath.startsWith('./') || rigPath.startsWith('configs/') ? resolve(rigPath) : null;
+    if (rigFile && existsSync(rigFile)) {
+        try {
+            const { createRequire } = await import('node:module');
+            const Registry = createRequire(import.meta.url)(resolve('js/plugin-registry.js'));
+            const rig = Registry.parseRigIo(v3.parseRigYAMLText(readFileSync(rigFile, 'utf8')));
+            const notes = [];
+            if (rig.defaults.panel_mode != null && cb.panel_mode != null && rig.defaults.panel_mode !== cb.panel_mode) {
+                notes.push('protocol panel_mode ' + cb.panel_mode + ' overrides the rig default ' + rig.defaults.panel_mode + ' (allowed; the run asserts the protocol\'s value)');
+            }
+            if (cb.refresh_hz != null && rig.limits.max_refresh_hz != null && cb.refresh_hz > rig.limits.max_refresh_hz) {
+                console.error('✗ BLOCKING: controller.refresh_hz ' + cb.refresh_hz + ' exceeds the rig limit max_refresh_hz ' + rig.limits.max_refresh_hz + ' (' + rigPath + ')');
+                process.exitCode = 1;
+            }
+            if (cb.refresh_policy === 'line_sync_safe' && rig.limits.max_refresh_hz == null) {
+                console.warn('⚠ controller: refresh_policy line_sync_safe but the rig ' + rigPath + ' declares no limits.max_refresh_hz — nothing to cap at');
+            }
+            if (rig.requires.panel_firmware && cb.panel_firmware && rig.requires.panel_firmware !== cb.panel_firmware) {
+                notes.push('protocol requires panel firmware "' + cb.panel_firmware + '", rig requires "' + rig.requires.panel_firmware + '" — both are checked');
+            }
+            for (const w of rig.warnings || []) console.warn('⚠ rig ' + rigPath + ': ' + w);
+            for (const n of notes) console.log('ℹ ' + n);
+            console.log('ℹ rig ' + rigPath + ': defaults.panel_mode ' + rig.defaults.panel_mode + ', limits.max_refresh_hz ' + rig.limits.max_refresh_hz +
+                ', requires.panel_firmware ' + JSON.stringify(rig.requires.panel_firmware) + ', strict ' + rig.strict);
+        } catch (e) { console.warn('⚠ rig ' + rigPath + ' could not be cross-checked: ' + (e && e.message ? e.message : e)); }
+    }
+}
 const rcNames = Object.keys(exp.runtime_controls || {});
 if (rcNames.length) {
     const { createRequire } = await import('node:module');
diff --git a/arena_studio.html b/arena_studio.html
index 0cd898fb..6c4aecbf 100644
--- a/arena_studio.html
+++ b/arena_studio.html
@@ -3360,6 +3360,7 @@ <h2 id="modalTitle">Import error</h2>
 <!-- (1) CLASSIC SUBSTRATE — window globals, dodges ES-import gotcha -->
 <!-- ============================================================ -->
 <script src="js/arena-wire-g6.js"></script>
+<script src="js/controller-settings.js"></script>
 <script src="js/studio-analog-in.js"></script>
 <script src="js/studio-panel-inventory.js"></script>
 <script src="js/arena-link.js"></script>
@@ -4151,6 +4152,16 @@ <h2 id="modalTitle">Import error</h2>
                     ' matches multiple SD files — delete or rename the extra copy (Console → Patterns)'
             };
         }
+        // Sticky controller state (panel mode / refresh / panel firmware) — the planned verdict
+        // from the last dry preflight; recomputed when protocol, rig or controller changed.
+        const ctlKey = Studio._controllerGateKey ? Studio._controllerGateKey() : '';
+        if (Studio.refreshControllerGate && Studio.session && Studio.session.connected && doc &&
+            (!Studio._controllerGate || Studio._controllerGate.key !== ctlKey)) {
+            Studio.refreshControllerGate(); // async; calls back into updateRunGate
+        }
+        const ctlBlocked = (Studio._controllerGate && !Studio._controllerGate.ok) ? Studio._controllerGate.reason
+            : Studio.rigStrictFault ? 'rig (strict): ' + Studio.rigStrictFault : null;
+        if (gate.ok && ctlBlocked) gate = { ok: false, reason: ctlBlocked };
         const runBtn = $('btnRunExp');
         runBtn.disabled = !gate.ok;
         // Show the experiment length up front (steps + estimated wall-clock) so you
@@ -4160,7 +4171,9 @@ <h2 id="modalTitle">Import error</h2>
         const estTxt = est ? est.steps + ' step' + (est.steps === 1 ? '' : 's') + ' · ~' + fmtEstClock(est.sec) : '';
         $('runHint').textContent = gate.ok ? estTxt : (estTxt ? estTxt + ' · ' + gate.reason : gate.reason);
         const testBtn = $('btnTestExp');
-        testBtn.disabled = !(Studio.session && Studio.session.connected && doc);
+        // A wrong panel mode ruins a TEST run as much as an experiment: the controller gate applies to both.
+        testBtn.disabled = !(Studio.session && Studio.session.connected && doc) || !!ctlBlocked;
+        if (ctlBlocked && !gate.ok) $('runHint').textContent = (estTxt ? estTxt + ' · ' : '') + ctlBlocked;
         // Non-blocking warning: a pattern NAME doesn't match the SD but a
         // pattern_ID fallback resolves — the run proceeds playing that index,
         // NOT the named pattern (silent-wrong-pattern footgun). Distinct from
@@ -6444,6 +6457,7 @@ <h2 id="modalTitle">Import error</h2>
         const fi = Wire.decodeFirmwareInfo(await q(Wire.encodeGetFirmwareInfo()));
         if (fi && fi.version) { $('cFwName').textContent = 'on SD: ' + fi.version; got.push('SD fw «' + fi.version + '»'); }
         if (got.length) clog('init from controller: ' + got.join(' · '), 'info');
+        if (Studio.refreshControllerGate) Studio.refreshControllerGate(); // sticky-state verdict for the run gate
     }
     function downloadBlob(bytes, name, mime) {
         const blob = new Blob([bytes], { type: mime || 'application/octet-stream' });
@@ -7409,6 +7423,7 @@ <h2 id="modalTitle">Import error</h2>
     };
     invalidateRigIo();
     renderRigIoMenu();
+    Studio._controllerGate = null; // rig changed → the sticky-state verdict must be recomputed
     updateIspShowUI(); // the batch progress map needs a 20-panel layout
     if (window.Scope && window.Scope.applyRigBallDiameter) window.Scope.applyRigBallDiameter(); // scope forward-velocity calibration
     Studio.refreshState(); // device line + mismatch chip
@@ -7596,6 +7611,16 @@ <h2 id="modalTitle">Import error</h2>
     if (roleOf('cIoRoleAi', io.ai.role) === 'in') {
         clog('rig io: AI "in" not applied — Mode-4 front-end calibration TBD (bench)', 'warn');
     }
+    // Sticky panel display mode default (rig `defaults.panel_mode`): GET → SET → GET, logged.
+    // On a strict rig a failure here blocks the run gate until it is resolved.
+    const CSm = window.ControllerSettings;
+    const wantMode = CSm && io.defaults ? CSm.normalizePanelMode(io.defaults.panel_mode) : null;
+    Studio.rigStrictFault = null;
+    if (wantMode !== null) {
+        const r = await Studio.assertPanelMode(wantMode, { source: 'rig default' });
+        if (r.applied) applied.push('panel mode→' + CSm.panelModeName(wantMode));
+        if (!r.ok && io.strict) Studio.rigStrictFault = r.message;
+    }
     if (applied.length) {
         clog('rig io defaults applied (' + (Studio.currentRig && Studio.currentRig.name) + '): ' + applied.join(' · '), 'info');
     } else if (manual) {
@@ -7603,6 +7628,207 @@ <h2 id="modalTitle">Import error</h2>
     }
 };
 
+// ---- controller settings: assert before run, snapshot into the run header ----
+// docs/development/controller-settings-strategy.md. The planner (js/controller-settings.js)
+// is pure; this block is the hardware side: GET → SET → GET with logging, the snapshot the
+// run header carries, the run-gate reason, and the fleet firmware verify.
+Studio.panelVerify = null; // {at, footer, ok, verified, total, mismatched[]} — batch flasher / Verify panels
+Studio.controllerSnapshot = null; // last readControllerSnapshot()
+Studio._controllerGate = null; // {ok, reason, key} — consulted by updateRunGate
+Studio.rigStrictFault = null; // connect-time rig-default failure on a strict rig
+async function ctlSend(bytes, timeoutMs) {
+    try {
+        return await Studio.session.send(bytes, { timeoutMs: timeoutMs || 2000, silent: true });
+    } catch (_) {
+        return null;
+    }
+}
+Studio.assertPanelMode = async function (want, opts) {
+    const CS = window.ControllerSettings;
+    const clog = Studio.clog || Studio.rawLog;
+    const src = (opts && opts.source) || 'protocol';
+    const before = Wire.decodePanelDisplayMode(await ctlSend(Wire.encodeGetPanelDisplayMode()));
+    if (before === want) {
+        clog('panel mode: ' + CS.panelModeName(want) + ' (' + want + ') already set — ' + src, 'info');
+        return { ok: true, applied: false, before, after: before, message: '' };
+    }
+    await ctlSend(Wire.encodeSetPanelDisplayMode(want));
+    const after = Wire.decodePanelDisplayMode(await ctlSend(Wire.encodeGetPanelDisplayMode()));
+    const ok = after === want;
+    const message = 'panel mode: ' + (before == null ? '?' : CS.panelModeName(before)) + ' → ' + CS.panelModeName(want) +
+        (ok ? ' (verified — ' + src + ')' : ' FAILED (read back ' + (after == null ? 'nothing' : CS.panelModeName(after)) + ') — ' + src);
+    clog(message, ok ? 'info' : 'err');
+    if ($('cPanelMode') && after != null) $('cPanelMode').value = String(after);
+    return { ok, applied: ok, before, after, message };
+};
+Studio.assertRefreshHz = async function (want, opts) {
+    const clog = Studio.clog || Studio.rawLog;
+    const src = (opts && opts.source) || 'protocol';
+    const before = Wire.decodeRefreshRate(await ctlSend(Wire.encodeGetRefreshRate()));
+    if (before === want) {
+        clog('refresh: ' + want + ' Hz already set — ' + src, 'info');
+        return { ok: true, applied: false, before, after: before, message: '' };
+    }
+    await ctlSend(Wire.encodeSetRefreshRate(want));
+    const after = Wire.decodeRefreshRate(await ctlSend(Wire.encodeGetRefreshRate()));
+    const ok = after === want;
+    const message = 'refresh: ' + (before == null ? '?' : before + ' Hz') + ' → ' + want + ' Hz' +
+        (ok ? ' (verified — ' + src + ')' : ' FAILED (read back ' + (after == null ? 'nothing' : after + ' Hz') + ') — ' + src);
+    clog(message, ok ? 'info' : 'err');
+    if ($('cRrHz') && after != null) $('cRrHz').value = String(after);
+    return { ok, applied: ok, before, after, message };
+};
+// Everything readable about the controller's sticky state, in one object. ~7 round-trips.
+Studio.readControllerSnapshot = async function () {
+    if (!Studio.session || !Studio.session.connected) return null;
+    await ensureCapabilities();
+    const snap = {
+        at: new Date().toISOString(),
+        panel_mode: Wire.decodePanelDisplayMode(await ctlSend(Wire.encodeGetPanelDisplayMode())),
+        refresh_hz: Wire.decodeRefreshRate(await ctlSend(Wire.encodeGetRefreshRate())),
+        spi_mhz: Wire.decodeSpiClock(await ctlSend(Wire.encodeGetSpiClock())),
+        ao_mv: Wire.decodeAoVoltage(await ctlSend(Wire.encodeGetAoVoltage())),
+        dio_roles: hasIoExt() ? Wire.decodeDioRole(await ctlSend(Wire.encodeGetDioRole())) : null,
+        panel_firmware: Wire.decodeFirmwareInfo(await ctlSend(Wire.encodeGetFirmwareInfo())),
+        controller_firmware: Studio.firmware || null,
+        controller_id: Studio.controllerId || null,
+        capabilities: Array.isArray(Studio.capabilities) ? Studio.capabilities.slice() : [],
+        verified: Studio.panelVerify
+    };
+    Studio.controllerSnapshot = snap;
+    return snap;
+};
+// Grayscale of every pattern the sequence references, from the SD listing's cached
+// pattern info (fillPatternFramesFromCard) or a direct GET_PATTERN_INFO. Best effort.
+Studio.referencedPatternInfo = async function (exp) {
+    const names = new Set();
+    for (const c of (exp && exp.conditions) || []) {
+        for (const cmd of c.commands || []) {
+            if (cmd && cmd.type === 'controller' && cmd.command_name === 'trialParams' && cmd.pattern) names.add(String(cmd.pattern));
+        }
+    }
+    const out = [];
+    const m = Studio.patternSet || null; // the SD listing (patEntry uses the same object)
+    for (const name of names) {
+        let gsVal = null;
+        const p = m && m.patterns ? Object.values(m.patterns).find((x) => x && x.name === name) : null;
+        if (p && p.preview && (p.preview.gsVal === 1 || p.preview.gsVal === 2)) gsVal = p.preview.gsVal;
+        else if (p && Number.isFinite(p.index) && Studio.session && Studio.session.connected && !Studio.session.running) {
+            const info = Wire.decodePatternInfo(await ctlSend(Wire.encodeGetPatternInfo(p.index), 1500));
+            if (info) {
+                gsVal = info.gsVal;
+                p.preview = Object.assign(p.preview || {}, { gsVal: info.gsVal, frames: info.frameCount });
+            }
+        }
+        out.push({ name, gsVal });
+    }
+    return out;
+};
+function rigNameForProtocol(exp) {
+    const rp = exp && exp.rig_path ? String(exp.rig_path) : '';
+    if (!rp) return null;
+    const base = rp.split('/').pop().replace(/\.ya?ml$/i, '');
+    const entry = (rigIndex || []).find((r) => r && (r.path === rp || String(r.path || '').split('/').pop().replace(/\.ya?ml$/i, '') === base));
+    return entry ? entry.name : null; // unknown (MATLAB-side) rig paths are not compared
+}
+/**
+ * The run preflight for sticky controller state. dry=true only plans (for the run gate);
+ * otherwise executes the SETs and returns the header the run log carries.
+ * @returns {{ok:boolean, header:object, plan:object}}
+ */
+Studio.assertControllerSettings = async function (exp, opts) {
+    const CS = window.ControllerSettings;
+    const clog = Studio.clog || Studio.rawLog;
+    const dry = !!(opts && opts.dry);
+    if (!Studio.session || !Studio.session.connected) return { ok: false, header: null, plan: null };
+    const rig = (await fetchRigIo()) || parseRigIo(null);
+    const snap = await Studio.readControllerSnapshot();
+    const patterns = await Studio.referencedPatternInfo(exp);
+    const sessionRig = Studio.currentRig && Studio.currentRig.name;
+    const plan = CS.planAssertions({ block: exp.controller, rig, snapshot: snap, patterns, protocolRig: rigNameForProtocol(exp), sessionRig });
+    const src = exp.controller && exp.controller.declared ? 'protocol controller: block' : 'rig default';
+    const header = {
+        rig: rig.name || sessionRig || null,
+        strict: plan.strict,
+        intended: plan.intended,
+        before: snap,
+        actions: [],
+        after: null,
+        blocking: plan.blocking.slice(),
+        warnings: plan.warnings.slice()
+    };
+    if (!dry) {
+        for (const w of plan.warnings) clog('controller preflight: ' + w, 'warn');
+        for (const b of plan.blocking) clog('controller preflight: ' + b, 'err');
+        if (plan.ok) {
+            for (const act of plan.actions) {
+                const r = act.setting === 'panel_mode'
+                    ? await Studio.assertPanelMode(act.to, { source: src })
+                    : await Studio.assertRefreshHz(act.to, { source: src });
+                header.actions.push({ setting: act.setting, from: act.from, to: act.to, ok: r.ok });
+                if (!r.ok) header.blocking.push(r.message || (act.setting + ' could not be set'));
+            }
+            header.after = plan.actions.length ? await Studio.readControllerSnapshot() : snap;
+        }
+        clog('controller: ' + CS.formatSnapshot(header.after || snap), 'info');
+    }
+    const ok = header.blocking.length === 0;
+    if (!ok && !dry) Studio.showBanner('Run refused — controller preflight: ' + header.blocking.join('; '));
+    Studio._controllerGate = { ok, reason: ok ? '' : 'controller preflight: ' + header.blocking[0], key: Studio._controllerGateKey() };
+    return { ok, header, plan };
+};
+Studio._controllerGateKey = function () {
+    const doc = Studio.currentDoc;
+    return [doc ? doc.filename : '', doc ? doc.sha256 : '', Studio.currentRig ? Studio.currentRig.name : '', Studio.controllerSnapshot ? Studio.controllerSnapshot.at : '', Studio.panelVerify ? Studio.panelVerify.at : ''].join('|');
+};
+// Recompute the run-gate verdict (plan only, no SETs) when the protocol, rig or controller
+// changed. Debounced single-flight; calls updateRunGate when done.
+let ctlGateBusy = false;
+Studio.refreshControllerGate = async function () {
+    const doc = Studio.currentDoc;
+    if (!doc || !Studio.session || !Studio.session.connected || Studio.session.running) {
+        Studio._controllerGate = null;
+        return;
+    }
+    if (ctlGateBusy) return;
+    ctlGateBusy = true;
+    try {
+        await Studio.assertControllerSettings(doc.experiment, { dry: true });
+    } catch (e) {
+        Studio._controllerGate = { ok: false, reason: 'controller preflight failed: ' + (e && e.message ? e.message : e), key: Studio._controllerGateKey() };
+    } finally {
+        ctlGateBusy = false;
+    }
+    if (Studio.updateRunGate) Studio.updateRunGate();
+    if (Studio.renderSettingsCard) Studio.renderSettingsCard();
+};
+// Fleet firmware verify: CRC every panel's running app flash against the SD footer
+// (G6_VERIFY_PANEL 0xC9). Stops the display first. ~1 s per panel. Result feeds the
+// snapshot / run header and the gate.
+Studio.verifyPanels = async function () {
+    const clog = Studio.clog || Studio.rawLog;
+    if (!Studio.session || !Studio.session.connected) return null;
+    const cfgName = Studio.currentRig && Studio.currentRig.arenaConfig;
+    const cfg = cfgName ? getConfig(cfgName) : null;
+    const arena = cfg && cfg.arena;
+    const total = arena && arena.num_rows && arena.num_cols ? Number(arena.num_rows) * Number(arena.num_cols) : 20;
+    if (Studio.quiesceDisplay) await Studio.quiesceDisplay();
+    const footer = Wire.decodeFirmwareInfo(await ctlSend(Wire.encodeGetFirmwareInfo()));
+    const res = { at: new Date().toISOString(), footer: footer ? footer.version : null, ok: false, verified: 0, total, mismatched: [] };
+    clog('verify panels: checking ' + total + ' panels against SD footer «' + (res.footer || '?') + '»…', 'info');
+    for (let p = 1; p <= total; p++) {
+        const r = await ctlSend(Wire.encodeG6VerifyPanel(p), 10000);
+        const v = r && Wire.decodeProgramPanelResponse(r);
+        if (v && v.ok) res.verified++;
+        else res.mismatched.push(p);
+    }
+    res.ok = res.mismatched.length === 0;
+    Studio.panelVerify = res;
+    clog('verify panels: ' + res.verified + '/' + total + ' match' + (res.ok ? '' : ' — MISMATCH on panels ' + res.mismatched.join(', ')), res.ok ? 'info' : 'err');
+    Studio.refreshControllerGate();
+    return res;
+};
+
 // ---- metadata controlled vocabularies ----
 async function loadVocab(path, key) {
     try {
@@ -8752,6 +8978,18 @@ <h2 id="modalTitle">Import error</h2>
         if (sum) sum.textContent = 'flash · verify · batch';
         ispLog('isp batch — ' + summary, nBad ? 'err' : 'info');
         isp.reportText = buildIspReportText(states, summary);
+        // Fleet verify result → controller snapshot / run header / gate (controller-settings).
+        if (verify) {
+            Studio.panelVerify = {
+                at: new Date().toISOString(),
+                footer: Studio.controllerSnapshot && Studio.controllerSnapshot.panel_firmware ? Studio.controllerSnapshot.panel_firmware.version : null,
+                ok: nBad === 0 && nVerified === panels.length,
+                verified: nVerified,
+                total: panels.length,
+                mismatched: states.filter((s) => s.state === 'mismatch' || s.state === 'skipped').map((s) => s.panel)
+            };
+            if (Studio.refreshControllerGate) Studio.refreshControllerGate();
+        }
         // Batch over — leave the final report map lit (nothing guarded follows;
         // All off / Stop clears it).
         await pushIspStatus(states, { final: true });
@@ -9185,6 +9423,14 @@ <h2 id="modalTitle">Import error</h2>
     if (!doc || !Studio.session || !Studio.session.connected) return null;
     const exp = doc.experiment;
     if (refuseUnsupportedRequires(exp)) return null;
+    // Sticky controller state (panel mode, refresh, panel firmware) — assert before the run,
+    // refuse on mismatch, and keep the before/after snapshot for the run header.
+    Studio._controllerHeader = null;
+    if (Studio.assertControllerSettings) {
+        const cs = await Studio.assertControllerSettings(exp);
+        if (!cs.ok) return null;
+        Studio._controllerHeader = cs.header;
+    }
     const { steps } = RunnerLib.flattenStructure(exp, { shuffle: shuffleInPlace });
     const conditionsByName = new Map((exp.conditions || []).map((c) => [c.name, c]));
     // Run-start snapshot of the panel fleet (0xD1 is a pure read, ~10 ms per page):
@@ -9726,6 +9972,19 @@ <h2 id="modalTitle">Import error</h2>
         build: Studio.build
     });
     Studio.activeRunLog = RunLog.createRunLog({ intent: isExperiment ? 'experiment' : 'test', meta });
+    // Controller snapshot (intended / before / actions / after) — the run header that makes a
+    // run interpretable afterwards (docs/development/controller-settings-strategy.md § 5).
+    if (Studio._controllerHeader) {
+        Studio.activeRunLog.meta.controller = Studio._controllerHeader;
+        const CS = window.ControllerSettings;
+        const h = Studio._controllerHeader;
+        Studio.activeRunLog.event('log', {
+            level: h.warnings && h.warnings.length ? 'WARN' : 'INFO',
+            message: 'controller: ' + (CS ? CS.formatSnapshot(h.after || h.before) : JSON.stringify(h.after || h.before)) +
+                (h.actions && h.actions.length ? ' · set ' + h.actions.map((a) => a.setting + ' ' + a.from + '→' + a.to + (a.ok ? '' : ' FAILED')).join(', ') : ' · nothing to set') +
+                (h.warnings && h.warnings.length ? ' · warnings: ' + h.warnings.join('; ') : '')
+        });
+    }
     // Arena Studio Alt may attach the proposal's narrowly scoped runtime
     // controls to this immutable YAML/run identity. The original Studio has no
     // hook and therefore behaves exactly as before.
@@ -12317,6 +12576,56 @@ <h2 id="modalTitle">Import error</h2>
             }
             root.appendChild(rigBox);
 
+            // ── Controller (sticky settings asserted before every run) ─────────────
+            // docs/development/controller-settings-strategy.md — the protocol's controller:
+            // block (read-only here; edit the YAML), the rig's defaults, what the controller
+            // reports now, and the fleet firmware verify.
+            const ctlBox = el('div', { class: 'settings-section' });
+            ctlBox.appendChild(el('h3', {}, 'Controller'));
+            {
+                const CS = window.ControllerSettings;
+                const cb = experiment.controller || { declared: false, errors: [], warnings: [] };
+                const parts = [];
+                if (cb.declared) {
+                    if (cb.panel_mode != null) parts.push('panel mode ' + (CS ? CS.panelModeName(cb.panel_mode) : cb.panel_mode));
+                    if (cb.refresh_hz != null) parts.push('refresh ' + cb.refresh_hz + ' Hz');
+                    if (cb.refresh_policy) parts.push('refresh policy ' + cb.refresh_policy);
+                    if (cb.panel_firmware) parts.push('panel firmware "' + cb.panel_firmware + '"');
+                }
+                const ro = el('div', { class: 'set-ro' + (cb.errors && cb.errors.length ? ' set-warn' : cb.declared ? ' set-ok' : '') },
+                    cb.declared
+                        ? 'protocol declares: ' + (parts.join(' · ') || '(empty controller: block)')
+                        : 'no controller: block — this protocol inherits the rig defaults (panel mode) and is asserted against them');
+                ro.setAttribute('data-help', 'Sticky controller settings the Studio asserts before every run (GET → SET → GET) and records in the run header. Declared under controller: in the YAML (panel_mode, refresh_hz | refresh_policy, panel_firmware) — edit the YAML to change them. A protocol with a controller: block also needs requires: [controller_block].');
+                ctlBox.appendChild(ro);
+                for (const e of cb.errors || []) ctlBox.appendChild(el('div', { class: 'set-ro set-warn' }, '✗ ' + e));
+                for (const w of cb.warnings || []) ctlBox.appendChild(el('div', { class: 'set-ro set-warn' }, '⚠ ' + w));
+                const req = Array.isArray(experiment.requires) ? experiment.requires : [];
+                if (cb.declared && !req.includes('controller_block')) {
+                    ctlBox.appendChild(el('div', { class: 'set-ro set-warn' }, '⚠ add `requires: [controller_block]` so a runner without this feature refuses instead of ignoring the block'));
+                }
+                const snap = window.Studio && window.Studio.controllerSnapshot;
+                const st = el('div', { class: 'set-ro' }, snap && CS ? 'controller now: ' + CS.formatSnapshot(snap) : 'controller now: not read yet (connect)');
+                st.setAttribute('data-help', 'What the controller reports right now: panel display mode, refresh rate, SPI clock, Digital IO roles, analog-out level, the panel-firmware footer on the SD card, and the last fleet verify.');
+                ctlBox.appendChild(st);
+                const gate = window.Studio && window.Studio._controllerGate;
+                if (gate && !gate.ok) ctlBox.appendChild(el('div', { class: 'set-ro set-warn' }, '✗ ' + gate.reason));
+                else if (gate && gate.ok && snap) ctlBox.appendChild(el('div', { class: 'set-ro set-ok' }, '✓ controller preflight would pass'));
+                const row = el('div', { class: 'set-row' });
+                const vb = el('button', { class: 'zone-head-btn', title: 'CRC-check every panel\'s running firmware against the SD footer (G6_VERIFY_PANEL 0xC9). Stops the display first; about 1 s per panel. The result goes into the run header and the run gate.' }, 'Verify panels');
+                vb.disabled = !(window.Studio && window.Studio.session && window.Studio.session.connected && window.Studio.verifyPanels);
+                vb.addEventListener('click', async () => {
+                    vb.disabled = true;
+                    try { await window.Studio.verifyPanels(); } finally { renderSettings(); }
+                });
+                row.appendChild(vb);
+                const pv = window.Studio && window.Studio.panelVerify;
+                row.appendChild(el('span', { class: 'set-ro' }, pv ? (pv.ok ? '✓ ' : '✗ ') + pv.verified + '/' + pv.total + ' panels match «' + (pv.footer || '?') + '» (' + pv.at.slice(11, 19) + ')' : 'panels not verified this session'));
+                ctlBox.appendChild(row);
+            }
+            root.appendChild(ctlBox);
+            window.Studio.renderSettingsCard = renderSettings; // re-render when the gate / snapshot changes
+
             // ── Pattern set ─────────────────────────────────────────────────
             const psBox = el('div', { class: 'settings-section' });
             psBox.appendChild(el('h3', {}, 'Pattern set'));
diff --git a/configs/rigs/bergamo_g6_2x10_2p.yaml b/configs/rigs/bergamo_g6_2x10_2p.yaml
new file mode 100644
index 00000000..ccd9e242
--- /dev/null
+++ b/configs/rigs/bergamo_g6_2x10_2p.yaml
@@ -0,0 +1,55 @@
+# Bergamo two-photon rig — G6 2x10 arena, line-synchronised to the resonant scanner.
+#
+# This file describes the WIRING and the bench's safety limits; the experiment's own
+# needs (panel mode, refresh policy) live in the protocol's `controller:` block. Both are
+# asserted by Arena Studio before every run and written into the run header
+# (docs/development/controller-settings-strategy.md).
+#
+# Cabling (rig checklist docs/development/2p-line-sync-rig-checklist.md):
+#   Digital IO 1 (J3)  → vDAQ free digital input (D2.1), ScanImage "Aux trigger 1":
+#                        one 5 V pulse per 300 Hz frame transfer, stamped into every TIFF header.
+#   Digital IO 2 (J4)  ← ScanImage line clock (HIGH while pixels are recorded, LOW in the
+#                        turnaround) = the panels' EINT trigger route (J30 shunt installed).
+#   Analog out (J27)   → optional condition marker into a vDAQ AI; idles at 0 V here.
+
+format_version: "1.0"
+name: "Bergamo G6 2x10 (2P line-sync)"
+description: "Bergamo two-photon rig — G6 2x10 arena, panels flash only in the line-clock LOW gap"
+
+arena: "G6_2x10"
+
+controller:
+  host: "0.0.0.0" # USB/serial via the browser port picker; host/port unused
+  port: 62222
+
+plugins: {}
+
+io:
+  dio:
+    - port: 1
+      role: out_debug_framescan # J3: frame-transfer pulse → ScanImage aux trigger
+      default: 0
+    - port: 2
+      role: in_trigger # J4: line clock in. Declared explicitly — `off` would mean "don't touch"
+      default: 0
+  ai:
+    role: off
+  ao:
+    role: programmable
+    default: 0.0 # idle at 0 V so protocol markers (0.5–3 V) start from a clean baseline
+
+# Sticky controller settings this bench needs at connect and at every run start.
+defaults:
+  panel_mode: triggered # 2 — LEDs only inside the line-clock gap. Course rigs use persistent (1).
+
+# Safety limits the Studio enforces on every protocol run here.
+limits:
+  max_refresh_hz: 300 # a GS2 pattern would default to 1000 Hz; every re-streamed frame costs the panels a line edge
+
+# Installed state a run needs but cannot set. Checked against the SD footer (GET_FIRMWARE_INFO)
+# and the session's panel-verify result before the run; mismatch blocks.
+requires:
+  panel_firmware: "2p" # footer version "2p-<sha8>[-d]" = the eintlow_2p line-sync variant
+
+# strict: mismatches (rig identity, unreadable settings) BLOCK the run instead of warning.
+strict: true
diff --git a/configs/rigs/cshl_g6_2x10.yaml b/configs/rigs/cshl_g6_2x10.yaml
index 13aef345..b19b445b 100644
--- a/configs/rigs/cshl_g6_2x10.yaml
+++ b/configs/rigs/cshl_g6_2x10.yaml
@@ -54,3 +54,8 @@ io:
   ao:
     role: programmable # off | programmable (0xA0) | frame_number (bench-pending)
     default: 5.0 # volts at connect — this hardware idles at 5 V
+
+# Sticky controller default, asserted at connect and before every run (docs/development/controller-settings-strategy.md).
+# A protocol may override it with its own controller: block; a 2P (line-sync) protocol refuses to run here.
+defaults:
+  panel_mode: persistent # 1 — free-running panels; this bench has no line clock
diff --git a/configs/rigs/cshl_g6_2x10_ball.yaml b/configs/rigs/cshl_g6_2x10_ball.yaml
index f3f6540a..656e6313 100644
--- a/configs/rigs/cshl_g6_2x10_ball.yaml
+++ b/configs/rigs/cshl_g6_2x10_ball.yaml
@@ -56,3 +56,8 @@ io:
   ao:
     role: programmable # driven to `default` at connect (SET_AO_VOLTAGE 0xA0)
     default: 5.0 # volts — this hardware idles at 5 V
+
+# Sticky controller default, asserted at connect and before every run (docs/development/controller-settings-strategy.md).
+# A protocol may override it with its own controller: block; a 2P (line-sync) protocol refuses to run here.
+defaults:
+  panel_mode: persistent # 1 — free-running panels; this bench has no line clock
diff --git a/configs/rigs/cshl_g6_2x8.yaml b/configs/rigs/cshl_g6_2x8.yaml
index 626ac6ff..19758cf0 100644
--- a/configs/rigs/cshl_g6_2x8.yaml
+++ b/configs/rigs/cshl_g6_2x8.yaml
@@ -42,3 +42,8 @@ io:
   ao:
     role: programmable # off | programmable (0xA0) | frame_number (bench-pending)
     default: 5.0 # volts at connect — this hardware idles at 5 V
+
+# Sticky controller default, asserted at connect and before every run (docs/development/controller-settings-strategy.md).
+# A protocol may override it with its own controller: block; a 2P (line-sync) protocol refuses to run here.
+defaults:
+  panel_mode: persistent # 1 — free-running panels; this bench has no line clock
diff --git a/configs/rigs/g6_3x10.yaml b/configs/rigs/g6_3x10.yaml
index 0de2d3cf..b4bf0bc7 100644
--- a/configs/rigs/g6_3x10.yaml
+++ b/configs/rigs/g6_3x10.yaml
@@ -31,3 +31,8 @@ io:
   ao:
     role: programmable
     default: 5.0 # volts — this hardware idles at 5 V
+
+# Sticky controller default, asserted at connect and before every run (docs/development/controller-settings-strategy.md).
+# A protocol may override it with its own controller: block; a 2P (line-sync) protocol refuses to run here.
+defaults:
+  panel_mode: persistent # 1 — free-running panels; this bench has no line clock
diff --git a/configs/rigs/g6_4x10.yaml b/configs/rigs/g6_4x10.yaml
index 7c988963..5ce08995 100644
--- a/configs/rigs/g6_4x10.yaml
+++ b/configs/rigs/g6_4x10.yaml
@@ -31,3 +31,8 @@ io:
   ao:
     role: programmable
     default: 5.0 # volts — this hardware idles at 5 V
+
+# Sticky controller default, asserted at connect and before every run (docs/development/controller-settings-strategy.md).
+# A protocol may override it with its own controller: block; a 2P (line-sync) protocol refuses to run here.
+defaults:
+  panel_mode: persistent # 1 — free-running panels; this bench has no line clock
diff --git a/configs/rigs/index.json b/configs/rigs/index.json
index 5a7b8da0..8aee7738 100644
--- a/configs/rigs/index.json
+++ b/configs/rigs/index.json
@@ -33,6 +33,12 @@
       "label": "CSHL G6 — 2×8 of 10 (288°)",
       "path": "./configs/rigs/cshl_g6_2x8.yaml",
       "arena": "G6_2x8of10"
+    },
+    {
+      "name": "bergamo_g6_2x10_2p",
+      "label": "Bergamo G6 — 2×10 two-photon line-sync (strict)",
+      "path": "./configs/rigs/bergamo_g6_2x10_2p.yaml",
+      "arena": "G6_2x10"
     }
   ]
 }
diff --git a/docs/development/2p-line-sync-rig-checklist.md b/docs/development/2p-line-sync-rig-checklist.md
index 6ddee06c..24342d33 100644
--- a/docs/development/2p-line-sync-rig-checklist.md
+++ b/docs/development/2p-line-sync-rig-checklist.md
@@ -59,10 +59,12 @@ path are unchanged.
 
 | Item | Setting | Wire (Debug ▾ → unlock → Send raw hex) |
 |---|---|---|
-| panel display mode | 2 (Triggered) | `02 1B 02` |
-| Digital IO 1 (BNC **J3**) | out_debug_framescan — HIGH during every SPI frame transfer | `03 AC 01 03` (read back: `01 AD`) |
-| Digital IO 2 (BNC **J4**) | in_trigger (boot default) — the line-clock input | leave |
-| refresh rate | 300 Hz (Gray_16 default) | `03 16 2C 01` |
+| **session rig** (top bar) | **Bergamo G6 — 2×10 two-photon line-sync (strict)** | — the protocols' `rig:` must match it or the run is refused |
+| panel display mode | 2 (Triggered) — **asserted automatically** by the rig default at connect and by the protocols' `controller:` block before every run; the log shows `panel mode: persistent → triggered (verified …)` | manual fallback `02 1B 02` |
+| Digital IO 1 (BNC **J3**) | out_debug_framescan — HIGH during every SPI frame transfer (applied from the rig at connect) | read back: `01 AD` |
+| Digital IO 2 (BNC **J4**) | in_trigger — the line-clock input (applied from the rig at connect) | read back: `01 AD` |
+| refresh rate | ≤ 300 Hz — **asserted automatically** (rig `limits.max_refresh_hz` + protocol `refresh_policy: line_sync_safe`) | manual fallback `03 16 2C 01` |
+| panel firmware | footer `2p-…` **checked automatically**; run Settings → Controller → **Verify panels** once per session (~20 s) so the run header carries a fleet verify | — |
 | telemetry ring | on (default) | — |
 | pattern | `frame2_h_ccw_200f`, SD index 4 (built-in g6_2x10 set) — or any **Gray_16** pattern on the card | edit the two anchors at the top of the YAML |
 
diff --git a/docs/development/controller-settings-strategy.md b/docs/development/controller-settings-strategy.md
new file mode 100644
index 00000000..5586f4d1
--- /dev/null
+++ b/docs/development/controller-settings-strategy.md
@@ -0,0 +1,106 @@
+# Controller settings: what lives in the rig config, what lives in the protocol (plan, 2026-09-23)
+
+Status: **Phase 1 implemented** (Studio v0.88, branch claude/controller-settings-block; user doc
+`docs/development/controller-settings.md`). Reviewed adversarially before implementation (Claude proposal → Codex GPT-5.5
+review → reconciled here). Phases 2 (firmware) and 3 (MATLAB) are open. Raw review: `Bergamo_testing/092226_SNR/analysis/codex_review_raw/codex_strategy_review.md`.
+
+## 1. The problem
+
+The G6 controller has about a dozen *sticky* session settings (set over the wire, kept until changed or
+rebooted). They are controlled by four unrelated mechanisms: firmware boot defaults, the rig YAML `io:` block
+applied at connect, protocol commands, and the Studio's locked Controller ▾ menu. The panel display mode, the
+single most consequential setting for two-photon imaging, is menu-only: set by hand, not recorded with the
+data, not checked before a run (arena firmware issue #60).
+
+## 2. The rule
+
+> Wiring goes in the rig config. Experiment semantics go in the protocol. Installed state the protocol needs
+> but cannot set goes in `requires:`. **Every sticky setting a run depends on is asserted before the run starts,
+> verified after setting, and recorded in the run header.** Cleanup afterwards is best-effort, never the safety
+> mechanism.
+
+The last sentence is the main change from the first draft. "Restore the previous value at the end of the run"
+looked tidy but is a trap: a closed browser tab, an unplugged USB cable or a controller reboot skips it, and a
+clean 2P run would "restore" persistent mode on a rig still wired for imaging. Assert-before-run makes every
+run safe on its own and makes back-to-back protocols independent.
+
+## 3. Classification
+
+| setting | sticky | home | mechanism |
+|---|---|---|---|
+| DIO 1/2 roles, AO mode, AO/DO idle levels | yes | **rig** (wiring) | applied at connect (exists); on the 2P rig DIO 2 must be declared `in_trigger`, not `off` (`off` = don't touch) |
+| panel display mode | yes | **rig default + protocol requirement** | rig `defaults.panel_mode` applied at connect (course rigs: 1, 2P: 2); a protocol that *needs* a mode declares `controller.panel_mode`; runner GET → SET → GET before the first condition, refuses on mismatch. Course protocols omit it and inherit the rig default, so a copied 2P protocol cannot damage a course bench silently: it refuses to run there |
+| refresh rate | yes | **derived** | not hand-authored. The runner reads the grayscale of every referenced pattern (SD header, 0x88) and picks the firmware default for it, capped by the rig's `limits.max_refresh_hz` (2P: 300). A protocol may declare `controller.refresh_policy: line_sync_safe` to insist on the cap; a bare number is only for explicit refresh experiments |
+| per-trial pattern, mode 2/3/4, frame_rate, frame_index, gain, duty | no | **protocol trialParams** | unchanged (frame_rate is already per trial; it is the *refresh* rate that is sticky) |
+| AO / DO changes during a run (markers) | yes | **protocol commands** | unchanged (`setAnalogOut`, `setDigitalOut`); preflight verifies AO mode is `programmable` when a protocol uses AO markers |
+| panel firmware variant | persistent | **protocol `requires`** | `requires.panel_firmware: "eintlow_2p"` matched against the SD footer version (0xE3) **and** the flasher's per-panel verify status (0xC9); footer alone only proves what was uploaded |
+| rig identity | – | **protocol `rig:` must match the session rig** | today the 2P protocols point at the course rig file; a mismatch becomes a blocking preflight error |
+| pattern files | persistent | protocol preflight by name (exists) | 2P runs additionally log each pattern's SD header (GS mode, frames, default duty) |
+| telemetry ring, SPI clock, diag/SD-diag flags | yes | **console only** | protocols never touch them; the run header snapshots what is readable |
+| line-clock presence | – | **firmware follow-up** (issue #60: EINT edge counter in health) | until then a manual confirmation step in the 2P preflight |
+
+## 4. Mechanism: declaration block, not a command
+
+A `setPanelDisplayMode` *command* inside a condition was the first idea. It fails in exactly the ways that
+matter: it is buried where preflight cannot see it, it leaks into the next protocol, and a copied protocol
+puts a course bench into triggered mode with no line clock. The declarative block fixes all three:
+
+```yaml
+rig: "./configs/rigs/bergamo_g6_2x10_2p.yaml"
+requires: [controller_block]       # capability token: a runner without the block refuses the file
+controller:
+  panel_mode: triggered            # 0 oneshot | 1 persistent | 2 triggered | 3 gated (names or numbers)
+  refresh_policy: line_sync_safe   # cap at the rig's max_refresh_hz, derived per pattern grayscale
+  panel_firmware: "2p"             # SD footer version/prefix + the session's fleet verify
+```
+(As implemented: `requires:` stays the list of capability tokens; the installed-state requirement lives
+inside `controller:` and the rig may carry its own `requires.panel_firmware`.)
+
+Runner behaviour: after connect-time rig apply, before the first condition: GET each declared setting, SET if
+different, GET again; log "panel mode 1 → 2 (verified)"; refuse to run if a SET cannot be verified, a
+capability is missing, or a `requires` fails. On clean completion and on cancel: best-effort `allOff` and rig
+idle outputs. No "restore previous".
+
+Known gap: the MATLAB runner ignores unknown top-level keys, so a protocol with a `controller:` block looks
+safe but is not enforced there. Until MATLAB implements the block, 2P protocols are Studio-only and say so in
+their header (and `requires:` with an unknown key must be *blocking* in every runner that understands
+`requires` at all).
+
+## 5. Run header
+
+Every run log gets a header with intended / observed-before / SET result / observed-after for each declared
+setting, plus a snapshot of: protocol hash, rig file and hash, Studio version, controller firmware and
+capability bitmap (0xCB/0xC2), panel mode (0x1C), refresh (0x17), SPI clock (0xC6), DIO roles (0xAD), AO
+level (0xA1), panel firmware footer (0xE3) and verify status, pattern headers. Post-run / abort state is
+appended best-effort. This alone would have made the 22 Sept data interpretable and needs no schema change,
+so it is the first thing to build.
+
+## 6. Ordered plan (smallest set that fixes 2P without creating a course problem)
+
+Phase 1, webDisplayTools only, no firmware change:
+1. **Run header snapshot** in the web runner (§ 5). Files: `js/arena-runner-g6.js`, `js/studio-runlog-adapter.js`.
+2. **2P rig config** `configs/rigs/bergamo_g6_2x10_2p.yaml`: DIO 1 `out_debug_framescan`, DIO 2 `in_trigger`,
+   AO programmable idle 0 V, `defaults.panel_mode: 2`, `limits.max_refresh_hz: 300`, `requires.panel_firmware`.
+   Course rigs gain `defaults.panel_mode: 1`. Entry in `configs/rigs/index.json`.
+3. **Rig parser + connect-time apply** for `defaults.panel_mode` (GET/SET/GET, logged; blocking when the rig
+   sets `strict: true`). Files: `js/plugin-registry.js` (parseRigIo), `arena_studio.html` (applyRigIo).
+4. **Protocol `controller:` block**: parser + validator + editor "Controller" card + runner preflight
+   (§ 4). Files: `js/protocol-yaml-v3.js`, `.claude/skills/protocol-yaml/bin/validate-protocol.mjs`,
+   `js/plugin-registry.js`, `js/arena-runner-g6.js`, `arena_studio.html`; tests in `tests/`.
+5. **`requires:` extension** for `panel_firmware` and rig identity; preflight blocks on mismatch.
+6. **Refresh derivation** from pattern grayscale + rig cap (`refresh_policy`).
+7. **Point both 2P protocols** at the new rig and add the block; update the rig checklist so "set panel mode 2
+   by hand" becomes "connect and read the log line"; document Studio-only.
+
+Phase 2, arena firmware (issue #60): per-trial `panel_mode` in TRIAL_PARAMS; mode in GET_HEALTH and telemetry;
+EINT edge counter → preflight "line clock present".
+
+Phase 3: MATLAB runner support for `controller:` and `requires:`.
+
+## 7. What the review changed (for the record)
+
+Codex agreed with the rule and with the declaration block, and changed four things: dropped restore-at-end in
+favour of assert-before-run; made refresh derived rather than authored; kept course protocols silent on panel
+mode (rig default) instead of having every protocol declare it; and added rig identity, per-panel firmware
+verification, AO-mode verification and the MATLAB gap to the inventory. Claude's items that survived
+unchanged: the rule itself, the run header, `requires:` for installed state, console-only for bench knobs.
diff --git a/docs/development/controller-settings.md b/docs/development/controller-settings.md
new file mode 100644
index 00000000..b116cfbc
--- /dev/null
+++ b/docs/development/controller-settings.md
@@ -0,0 +1,124 @@
+# Controller settings: rig defaults, the protocol `controller:` block, the run header
+
+*User documentation for Studio v0.88+. Design and history: `controller-settings-strategy.md`.*
+
+The G6 controller keeps a handful of **sticky** settings across runs: the panel display mode
+(0 oneshot / 1 persistent / 2 triggered / 3 gated), the re-transmit ("refresh") rate, the Digital IO
+roles, the analog-out level, the SPI clock. Before v0.88 they were set by hand in the Controller ▾
+menu and nothing recorded them with the data. Now:
+
+1. the **rig YAML** declares the bench's wiring and defaults,
+2. a **protocol** declares what the experiment needs in a `controller:` block,
+3. Arena Studio **asserts** both before every run (read → set if needed → read back), **refuses** to
+   run on a mismatch it cannot fix, and writes a **controller snapshot** into the run header.
+
+## 1. Rig YAML
+
+```yaml
+io:
+  dio:
+    - port: 1
+      role: out_debug_framescan   # J3
+    - port: 2
+      role: in_trigger            # J4 — declare it; `off` means "don't touch"
+  ao:
+    role: programmable
+    default: 0.0
+defaults:
+  panel_mode: triggered           # asserted at connect and at every run start (course rigs: persistent)
+limits:
+  max_refresh_hz: 300             # protocols may not exceed this; line_sync_safe pins to it
+requires:
+  panel_firmware: "2p"            # the SD footer must match (prefix / dash-token match)
+strict: true                      # mismatches BLOCK instead of warn (default false)
+```
+
+`io:` is applied at connect as before (needs io_ext firmware). `defaults.panel_mode` is applied at
+connect the same way, GET → SET → GET, and logged (`panel mode: persistent → triggered (verified —
+rig default)`). On a strict rig a failure there disables the run buttons until it is resolved.
+
+Built-in rigs: `bergamo_g6_2x10_2p` (triggered, 300 Hz cap, "2p" firmware, strict); all course rigs
+(`cshl_*`, `g6_3x10`, `g6_4x10`) now carry `defaults.panel_mode: persistent`, so a bench left in
+triggered mode by a previous session is put back before the next run.
+
+## 2. Protocol `controller:` block
+
+```yaml
+rig: "./configs/rigs/bergamo_g6_2x10_2p.yaml"
+requires: [controller_block]
+controller:
+  panel_mode: triggered
+  refresh_policy: line_sync_safe    # or refresh_hz: 300 (not both)
+  panel_firmware: "2p"
+```
+
+| key | meaning | if absent |
+|---|---|---|
+| `panel_mode` | the mode the experiment needs; overrides the rig default | the rig default is asserted |
+| `refresh_policy: line_sync_safe` | pin the refresh at the rig's `limits.max_refresh_hz` when the current rate or the referenced patterns' default (GS2 → 1000 Hz, GS16 → 300 Hz) would exceed it | with a rig cap the same derivation runs anyway; without one nothing is touched |
+| `refresh_hz` | an explicit rate (refresh experiments); must not exceed the rig cap | — |
+| `panel_firmware` | SD footer version or prefix the panel image must match; also checked against the session's fleet verify | the rig's `requires.panel_firmware`, if any |
+
+Declaring a block makes the protocol **strict**: its `rig:` must be the session rig, every setting it
+depends on must be readable, and the panel firmware must match. `requires: [controller_block]` is
+what makes a runner *without* this feature (MATLAB today) refuse the file rather than run it in the
+wrong mode; the validator and the Settings → Controller card warn when it is missing.
+
+Most protocols need no block. Course protocols inherit `persistent` from their rig.
+
+## 3. What happens at run time
+
+Green **Run experiment** and blue **Test experiment** both go through the preflight:
+
+1. Read the controller: panel mode (0x1C), refresh (0x17), SPI clock (0xC6), DIO roles (0xAD), AO
+   level (0xA1), panel-firmware footer (0xE3), controller firmware and capabilities, the last fleet
+   verify. Read the grayscale of every referenced pattern (0x88).
+2. Plan (`js/controller-settings.js` `planAssertions`): rig identity, panel mode (needs the
+   `v3_triggered` / `v3_gated` capability for modes 2/3), refresh, panel firmware.
+3. Execute the SETs, each followed by a read-back. Every step is a line in the Studio log:
+   `panel mode: persistent → triggered (verified — protocol controller: block)`.
+4. If anything blocks: banner *Run refused — controller preflight: …*, nothing runs.
+5. The run header (`meta.controller` in the run log JSON, one `controller:` line in the .txt)
+   carries `intended`, `before`, `actions` (from → to, ok), `after`, `warnings`, `blocking`, `strict`,
+   `rig`. `before`/`after` are full snapshots (mode, refresh, SPI, DIO roles, AO, footer, controller
+   firmware/id/capabilities, fleet verify).
+
+The run gate shows the planned verdict before you press anything (the hint under the run
+buttons and Settings → Controller). It is recomputed when the protocol, the session rig or the
+controller changes. After the run, the runner's best-effort STOP/allOff is unchanged; there is no
+"restore previous mode" — every run asserts what it needs.
+
+## 4. Panel firmware verification
+
+Three layers, from cheap to conclusive:
+
+| when | what | logged where |
+|---|---|---|
+| every connect and run | **SD footer** (0xE3): which image was last uploaded to the controller (`2p-9014b5bb-d`, `panel-fw-v1.2.0`, …) | Studio log at connect; run header `before.panel_firmware` |
+| after a batch flash with *verify* on, or **Settings → Controller → Verify panels** | **fleet verify** (0xC9 per panel): CRC of each panel's running app flash vs the footer; ~1 s per panel, display stopped | Studio log; `Studio.panelVerify`; run header `before.verified` `{at, footer, ok, verified, total, mismatched[]}` |
+| planned (firmware) | per-panel version report at boot, host-readable | — |
+
+Rules: a required firmware that does not match the footer **blocks**; a failed fleet verify
+**blocks** and names the panels; "not verified this session" **warns** (strongly worded on strict
+rigs). Verification is per session because the answer can change only when someone flashes, and
+a flash goes through the same Studio, which records the result.
+
+## 5. Staging
+
+- **Phase 1 (this release)**: everything above. Studio-only; MATLAB refuses protocols that carry the
+  `controller_block` token.
+- **Phase 2 (arena firmware, issue reiserlab/LED-Display_G6_Firmware_Arena#60)**: per-trial
+  `panel_mode` in TRIAL_PARAMS; mode in GET_HEALTH / telemetry; an EINT edge counter so the
+  preflight can also check "line clock present"; a boot-time per-panel firmware report so the fleet
+  check needs no display stop (coordinated with the panel boot-up work).
+- **Phase 3 (MATLAB runner)**: implement `controller:` and `requires:`; until then 2P protocols are
+  Studio-only.
+
+## 6. Files
+
+`js/controller-settings.js` (planner, tested in `tests/test-controller-settings.js`),
+`js/plugin-registry.js` (`parseRigIo` → defaults/limits/requires/strict), `js/protocol-yaml-v3.js`
+(`extractControllerBlock`, blocking errors, `controller_block` capability), `arena_studio.html`
+(`Studio.assertControllerSettings`, `readControllerSnapshot`, `verifyPanels`, run gate, Settings card),
+`.claude/skills/protocol-yaml/bin/validate-protocol.mjs`, `configs/rigs/*.yaml`,
+`protocols/g6_2x10_2p_*.yaml`.
diff --git a/js/controller-settings.js b/js/controller-settings.js
new file mode 100644
index 00000000..e2209cd5
--- /dev/null
+++ b/js/controller-settings.js
@@ -0,0 +1,272 @@
+/**
+ * controller-settings.js — the "assert before run" logic for sticky controller settings.
+ *
+ * Design: docs/development/controller-settings-strategy.md. A protocol may declare a
+ * top-level `controller:` block (panel_mode, refresh_hz | refresh_policy, panel_firmware);
+ * a rig YAML may declare `defaults:` (panel_mode), `limits:` (max_refresh_hz),
+ * `requires:` (panel_firmware) and `strict:`. Before every run the Studio reads a snapshot
+ * of the controller, asks planAssertions() what to SET, what to BLOCK on and what to WARN
+ * about, executes the SETs (GET → SET → GET), and writes intended / before / after into
+ * the run header. Nothing here touches hardware: the planner is pure so it can be tested.
+ *
+ * LOADING: classic <script src> (window-global + CommonJS dual-export, no ES `export`).
+ */
+(function (global) {
+    'use strict';
+
+    // Wire value === index. `persist` is the firmware's own word for mode 1; `persistent`
+    // is what people write.
+    const PANEL_MODE_NAMES = ['oneshot', 'persistent', 'triggered', 'gated'];
+    const PANEL_MODE_ALIASES = { oneshot: 0, persist: 1, persistent: 1, triggered: 2, gated: 3 };
+    // Controller capability bit a panel mode needs (arena-wire-g6 CAPABILITY_BITS).
+    const PANEL_MODE_CAPABILITY = { 2: 'v3_triggered', 3: 'v3_gated' };
+
+    const REFRESH_POLICIES = ['line_sync_safe'];
+    // Firmware default re-transmit rate per pattern grayscale (the .pat header gs code:
+    // 1 = GS2, 2 = GS16). A GS2 pattern on an unmodified controller streams at 1000 Hz.
+    const DEFAULT_REFRESH_HZ = { 1: 1000, 2: 300 };
+    const REFRESH_HZ_MIN = 1;
+    const REFRESH_HZ_MAX = 2000;
+
+    function normalizePanelMode(v) {
+        if (v === undefined || v === null || v === '') return null;
+        if (typeof v === 'string') {
+            const s = v.trim().toLowerCase();
+            if (Object.prototype.hasOwnProperty.call(PANEL_MODE_ALIASES, s)) return PANEL_MODE_ALIASES[s];
+            if (/^[0-3]$/.test(s)) return Number(s);
+            return null;
+        }
+        if (typeof v === 'number' && Number.isInteger(v) && v >= 0 && v <= 3) return v;
+        return null;
+    }
+
+    function panelModeName(m) {
+        return m === null || m === undefined ? '?' : PANEL_MODE_NAMES[m] || 'mode' + m;
+    }
+
+    /**
+     * Does a panel-firmware footer version satisfy a requirement string?
+     * The SD footer version is `<tag>` for tagged builds (e.g. "panel-fw-v1.2.0") or
+     * `<abbrev>-<sha8>[-d]` for variants (e.g. "2p-9014b5bb-d"). A requirement matches when
+     * the version starts with it or contains it as a dash/underscore-delimited token
+     * (case-insensitive). So `panel_firmware: "2p"` accepts "2p-9014b5bb-d" and
+     * "panel-fw-v1.2.0" accepts exactly that tag.
+     */
+    function firmwareMatches(footerVersion, required) {
+        if (!required) return true;
+        if (!footerVersion) return false;
+        const v = String(footerVersion).trim().toLowerCase();
+        const r = String(required).trim().toLowerCase();
+        if (!r) return true;
+        if (v === r || v.startsWith(r)) return true;
+        return v.split(/[-_ ]+/).includes(r);
+    }
+
+    /**
+     * Normalize a protocol's raw `controller:` block. Never throws; reports problems in
+     * `errors` (blocking) and `warnings`. `declared` is false when the block is absent.
+     */
+    function normalizeControllerBlock(raw) {
+        const out = {
+            declared: false,
+            panel_mode: null,
+            refresh_hz: null,
+            refresh_policy: null,
+            panel_firmware: null,
+            errors: [],
+            warnings: []
+        };
+        if (raw === undefined || raw === null) return out;
+        out.declared = true;
+        if (typeof raw !== 'object' || Array.isArray(raw)) {
+            out.errors.push('controller: must be a mapping (panel_mode / refresh_hz / refresh_policy / panel_firmware)');
+            return out;
+        }
+        const known = ['panel_mode', 'refresh_hz', 'refresh_policy', 'panel_firmware'];
+        for (const k of Object.keys(raw)) {
+            if (!known.includes(k)) out.warnings.push('controller: unknown key "' + k + '" is ignored (known: ' + known.join(', ') + ')');
+        }
+        if (raw.panel_mode !== undefined && raw.panel_mode !== null) {
+            const m = normalizePanelMode(raw.panel_mode);
+            if (m === null) {
+                out.errors.push('controller.panel_mode ' + JSON.stringify(raw.panel_mode) + ' is not 0–3 or one of ' + PANEL_MODE_NAMES.join('/'));
+            } else {
+                out.panel_mode = m;
+            }
+        }
+        if (raw.refresh_hz !== undefined && raw.refresh_hz !== null) {
+            const hz = Number(raw.refresh_hz);
+            if (!Number.isInteger(hz) || hz < REFRESH_HZ_MIN || hz > REFRESH_HZ_MAX) {
+                out.errors.push('controller.refresh_hz ' + JSON.stringify(raw.refresh_hz) + ' must be an integer ' + REFRESH_HZ_MIN + '–' + REFRESH_HZ_MAX);
+            } else {
+                out.refresh_hz = hz;
+            }
+        }
+        if (raw.refresh_policy !== undefined && raw.refresh_policy !== null) {
+            const p = String(raw.refresh_policy).trim();
+            if (!REFRESH_POLICIES.includes(p)) {
+                out.errors.push('controller.refresh_policy ' + JSON.stringify(raw.refresh_policy) + ' must be one of ' + REFRESH_POLICIES.join('/'));
+            } else {
+                out.refresh_policy = p;
+            }
+        }
+        if (out.refresh_hz !== null && out.refresh_policy !== null) {
+            out.errors.push('controller: declare refresh_hz OR refresh_policy, not both');
+        }
+        if (raw.panel_firmware !== undefined && raw.panel_firmware !== null) {
+            if (typeof raw.panel_firmware !== 'string' || !raw.panel_firmware.trim()) {
+                out.errors.push('controller.panel_firmware must be a non-empty string (a footer version or its prefix, e.g. "2p")');
+            } else {
+                out.panel_firmware = raw.panel_firmware.trim();
+            }
+        }
+        return out;
+    }
+
+    /**
+     * Decide what a run must do about the controller's sticky state.
+     *
+     * @param {object} a
+     * @param {object} [a.block]        normalizeControllerBlock() result (or raw block)
+     * @param {object} [a.rig]          parseRigIo() result: {name, defaults:{panel_mode}, limits:{max_refresh_hz},
+     *                                  requires:{panel_firmware}, strict}
+     * @param {object} [a.snapshot]     {panel_mode, refresh_hz, capabilities[], panel_firmware:{version}|null,
+     *                                  verified:{ok, verified, total, at}|null}; fields null when unreadable
+     * @param {Array}  [a.patterns]     [{name, gsVal}] for the patterns the sequence references (gsVal 1|2|null)
+     * @param {string} [a.protocolRig]  rig name the protocol's `rig:` path resolves to (basename without .yaml)
+     * @param {string} [a.sessionRig]   the Studio's session rig name
+     * @returns {{ok:boolean, strict:boolean, actions:Array, blocking:string[], warnings:string[], intended:object}}
+     */
+    function planAssertions(a) {
+        a = a || {};
+        const block = a.block && typeof a.block === 'object' && 'declared' in a.block ? a.block : normalizeControllerBlock(a.block);
+        const rig = a.rig || {};
+        const rigDefaults = rig.defaults || {};
+        const rigLimits = rig.limits || {};
+        const rigRequires = rig.requires || {};
+        const snap = a.snapshot || {};
+        const caps = Array.isArray(snap.capabilities) ? snap.capabilities : null;
+        const patterns = Array.isArray(a.patterns) ? a.patterns : [];
+        const strict = !!rig.strict || !!block.declared;
+        const actions = [];
+        const blocking = [];
+        const warnings = [];
+        const intended = {};
+        const problem = (msg) => (strict ? blocking : warnings).push(msg);
+
+        for (const e of block.errors || []) blocking.push(e);
+        for (const w of block.warnings || []) warnings.push(w);
+
+        // 1. Rig identity — the protocol's rig and the bench's rig must agree.
+        if (a.protocolRig && a.sessionRig && a.protocolRig !== a.sessionRig) {
+            problem('protocol is written for rig "' + a.protocolRig + '" but the session rig is "' + a.sessionRig + '"' +
+                (strict ? ' — pick the right rig in the top bar or fix the protocol\'s rig: path' : ''));
+        }
+
+        // 2. Panel display mode: protocol wins, else the rig default. Nothing declared → record only.
+        const wantMode = block.panel_mode !== null && block.panel_mode !== undefined ? block.panel_mode : normalizePanelMode(rigDefaults.panel_mode);
+        if (wantMode !== null) {
+            intended.panel_mode = wantMode;
+            const needCap = PANEL_MODE_CAPABILITY[wantMode];
+            if (needCap && caps && !caps.includes(needCap)) {
+                blocking.push('panel mode ' + panelModeName(wantMode) + ' needs controller capability "' + needCap + '", which this controller does not report');
+            } else if (snap.panel_mode === null || snap.panel_mode === undefined) {
+                problem('cannot read the panel display mode (GET_PANEL_DISPLAY_MODE 0x1C gave no reply) — wanted ' + panelModeName(wantMode));
+            } else if (snap.panel_mode !== wantMode) {
+                actions.push({ setting: 'panel_mode', from: snap.panel_mode, to: wantMode });
+            }
+        }
+
+        // 3. Refresh rate: explicit refresh_hz, else derived (rig cap + pattern grayscale).
+        const cap = Number.isInteger(rigLimits.max_refresh_hz) ? rigLimits.max_refresh_hz : null;
+        const gsList = patterns.map((p) => (p && (p.gsVal === 1 || p.gsVal === 2) ? p.gsVal : null));
+        const gsKnown = gsList.filter((g) => g !== null);
+        intended.pattern_gs = gsKnown.length ? Array.from(new Set(gsKnown)).map((g) => (g === 1 ? 'GS2' : 'GS16')) : null;
+        if (block.refresh_hz !== null) {
+            intended.refresh_hz = block.refresh_hz;
+            if (cap !== null && block.refresh_hz > cap) {
+                blocking.push('controller.refresh_hz ' + block.refresh_hz + ' exceeds the rig limit max_refresh_hz ' + cap);
+            } else if (snap.refresh_hz === null || snap.refresh_hz === undefined) {
+                problem('cannot read the refresh rate (GET_REFRESH_RATE 0x17 gave no reply) — wanted ' + block.refresh_hz + ' Hz');
+            } else if (snap.refresh_hz !== block.refresh_hz) {
+                actions.push({ setting: 'refresh_hz', from: snap.refresh_hz, to: block.refresh_hz });
+            }
+        } else if (block.refresh_policy === 'line_sync_safe' || cap !== null) {
+            if (cap === null) {
+                problem('controller.refresh_policy line_sync_safe needs the rig to declare limits.max_refresh_hz — nothing to cap at');
+            } else {
+                intended.refresh_hz_max = cap;
+                // The firmware default for the referenced patterns' grayscale is what the controller
+                // would stream at if nobody had set the rate; if that (or the current rate) is above the
+                // cap, pin the rate to the cap.
+                const wouldDefault = gsKnown.length ? Math.max.apply(null, gsKnown.map((g) => DEFAULT_REFRESH_HZ[g])) : null;
+                if (snap.refresh_hz === null || snap.refresh_hz === undefined) {
+                    problem('cannot read the refresh rate (GET_REFRESH_RATE 0x17 gave no reply) — rig caps it at ' + cap + ' Hz');
+                } else if (snap.refresh_hz > cap) {
+                    actions.push({ setting: 'refresh_hz', from: snap.refresh_hz, to: cap });
+                } else if (wouldDefault !== null && wouldDefault > cap && snap.refresh_hz !== cap) {
+                    // e.g. a GS2 pattern (default 1000 Hz) on a 300 Hz-capped rig: pin explicitly.
+                    actions.push({ setting: 'refresh_hz', from: snap.refresh_hz, to: cap });
+                }
+                if (gsKnown.length !== patterns.length && patterns.length) {
+                    warnings.push('grayscale unknown for ' + (patterns.length - gsKnown.length) + ' referenced pattern(s) — refresh derived from the readable ones only');
+                }
+            }
+        }
+
+        // 4. Panel firmware: protocol requirement wins, else the rig's. A declared requirement is hard.
+        const wantFw = block.panel_firmware || (typeof rigRequires.panel_firmware === 'string' ? rigRequires.panel_firmware : null);
+        if (wantFw) {
+            intended.panel_firmware = wantFw;
+            const ver = snap.panel_firmware && snap.panel_firmware.version ? snap.panel_firmware.version : null;
+            if (!ver) {
+                problem('cannot read the panel firmware footer (GET_FIRMWARE_INFO 0xE3) — required "' + wantFw + '"');
+            } else if (!firmwareMatches(ver, wantFw)) {
+                blocking.push('panel firmware on the SD card is "' + ver + '", required "' + wantFw + '" — flash the fleet (Console → Panel firmware) or change the requirement');
+            }
+            const v = snap.verified;
+            if (!v) {
+                warnings.push('panels not verified this session — the footer says which image is on the SD card, not which firmware every panel runs; run Verify panels (' + (strict ? 'strongly recommended on this rig' : 'optional') + ')');
+            } else if (v.ok === false) {
+                blocking.push('panel verify failed: ' + (v.total - v.verified) + ' of ' + v.total + ' panels do not match the SD footer "' + (v.footer || ver || '?') + '"' + (v.mismatched && v.mismatched.length ? ' (panels ' + v.mismatched.join(', ') + ')' : ''));
+            }
+        }
+
+        return { ok: blocking.length === 0, strict, actions, blocking, warnings, intended };
+    }
+
+    /** One line for the transcript / run header. */
+    function formatSnapshot(s) {
+        if (!s) return 'controller: (no snapshot)';
+        const parts = [];
+        parts.push('panel mode ' + (s.panel_mode === null || s.panel_mode === undefined ? '?' : panelModeName(s.panel_mode) + ' (' + s.panel_mode + ')'));
+        parts.push('refresh ' + (s.refresh_hz === null || s.refresh_hz === undefined ? '?' : s.refresh_hz + ' Hz'));
+        if (s.spi_mhz !== null && s.spi_mhz !== undefined) parts.push('SPI ' + s.spi_mhz + ' MHz');
+        if (s.dio_roles) parts.push('DIO ' + s.dio_roles.map((d, i) => (i + 1) + '=' + d.role).join(' '));
+        if (s.ao_mv !== null && s.ao_mv !== undefined) parts.push('AO ' + s.ao_mv + ' mV');
+        if (s.panel_firmware && s.panel_firmware.version) parts.push('panel fw «' + s.panel_firmware.version + '»');
+        if (s.verified) parts.push('verified ' + s.verified.verified + '/' + s.verified.total + (s.verified.ok ? '' : ' MISMATCH'));
+        if (s.controller_firmware) parts.push('controller ' + s.controller_firmware);
+        return parts.join(' · ');
+    }
+
+    const ControllerSettings = {
+        PANEL_MODE_NAMES,
+        PANEL_MODE_CAPABILITY,
+        REFRESH_POLICIES,
+        DEFAULT_REFRESH_HZ,
+        normalizePanelMode,
+        panelModeName,
+        firmwareMatches,
+        normalizeControllerBlock,
+        planAssertions,
+        formatSnapshot
+    };
+
+    if (typeof module !== 'undefined' && module.exports) {
+        module.exports = ControllerSettings;
+    }
+    if (typeof global !== 'undefined') {
+        global.ControllerSettings = ControllerSettings;
+    }
+})(typeof window !== 'undefined' ? window : this);
diff --git a/js/plugin-registry.js b/js/plugin-registry.js
index 50f75c81..1edcf7b1 100644
--- a/js/plugin-registry.js
+++ b/js/plugin-registry.js
@@ -1224,6 +1224,48 @@ function _rigIoRole(raw, allowed, label, warnings) {
  *   `default` in VOLTS (nullable; wire 0xA0 takes mV) — some hardware expects
  *   a 5 V idle, so an authored default is applied at connect.
  */
+// Panel display mode in a rig YAML: 0–3 or oneshot/persist(ent)/triggered/gated.
+var RIG_PANEL_MODES = { oneshot: 0, persist: 1, persistent: 1, triggered: 2, gated: 3 };
+function _rigPanelMode(raw, warnings) {
+    if (raw == null || raw === '') return null;
+    if (typeof raw === 'number' && Number.isInteger(raw) && raw >= 0 && raw <= 3) return raw;
+    var s = String(raw).trim().toLowerCase();
+    if (Object.prototype.hasOwnProperty.call(RIG_PANEL_MODES, s)) return RIG_PANEL_MODES[s];
+    if (/^[0-3]$/.test(s)) return Number(s);
+    warnings.push('unknown defaults.panel_mode "' + raw + '" — ignored (0–3 or oneshot/persistent/triggered/gated)');
+    return null;
+}
+
+// `defaults:` / `limits:` / `requires:` / `strict:` of a rig YAML (tolerant; bad values warn).
+function _parseRigSettings(rigData, result) {
+    var d = rigData.defaults;
+    if (d && typeof d === 'object' && !Array.isArray(d)) {
+        result.defaults.panel_mode = _rigPanelMode(d.panel_mode, result.warnings);
+    } else if (d != null) {
+        result.warnings.push('defaults: must be a mapping — ignored');
+    }
+    var l = rigData.limits;
+    if (l && typeof l === 'object' && !Array.isArray(l)) {
+        if (l.max_refresh_hz != null) {
+            var hz = Number(l.max_refresh_hz);
+            if (Number.isInteger(hz) && hz >= 1 && hz <= 2000) result.limits.max_refresh_hz = hz;
+            else result.warnings.push('limits.max_refresh_hz "' + l.max_refresh_hz + '" must be an integer 1–2000 — ignored');
+        }
+    } else if (l != null) {
+        result.warnings.push('limits: must be a mapping — ignored');
+    }
+    var r = rigData.requires;
+    if (r && typeof r === 'object' && !Array.isArray(r)) {
+        if (r.panel_firmware != null) {
+            if (typeof r.panel_firmware === 'string' && r.panel_firmware.trim()) result.requires.panel_firmware = r.panel_firmware.trim();
+            else result.warnings.push('requires.panel_firmware must be a non-empty string — ignored');
+        }
+    } else if (r != null) {
+        result.warnings.push('requires: must be a mapping — ignored');
+    }
+    if (rigData.strict != null) result.strict = rigData.strict === true || String(rigData.strict).toLowerCase() === 'true';
+}
+
 function parseRigIo(rigData) {
     var result = {
         dio: [
@@ -1232,9 +1274,20 @@ function parseRigIo(rigData) {
         ],
         ai: { role: 'off' },
         ao: { role: 'off', default: null },
+        // Sticky-setting policy (docs/development/controller-settings-strategy.md):
+        // defaults are asserted at connect and at every run start, limits cap what a
+        // protocol may ask for, requires names installed state a run needs, strict makes
+        // mismatches block instead of warn.
+        name: null,
+        defaults: { panel_mode: null },
+        limits: { max_refresh_hz: null },
+        requires: { panel_firmware: null },
+        strict: false,
         warnings: []
     };
     if (!rigData || typeof rigData !== 'object') return result;
+    if (typeof rigData.name === 'string' && rigData.name.trim()) result.name = rigData.name.trim();
+    _parseRigSettings(rigData, result);
     var io = rigData.io;
     if (!io || typeof io !== 'object' || Array.isArray(io)) return result;
 
diff --git a/js/protocol-yaml-v3.js b/js/protocol-yaml-v3.js
index d7f0e116..6185d30b 100644
--- a/js/protocol-yaml-v3.js
+++ b/js/protocol-yaml-v3.js
@@ -45,6 +45,7 @@ const KNOWN_TOP_LEVEL_KEYS = [
     'variables',
     'runtime_controls',
     'requires',
+    'controller',
     'plugins',
     'experiment',
     'conditions'
@@ -55,7 +56,9 @@ const KNOWN_TOP_LEVEL_KEYS = [
 // runner REFUSE to run rather than run wrong (a `repeat_until` block would otherwise flatten
 // into a plain block with its criterion silently ignored). `version:` stays 3 — capabilities
 // compose as a set; nothing here ever needs a version number.
-const WEB_RUNNER_CAPABILITIES = Object.freeze([]);
+// `controller_block`: the runner asserts a protocol's `controller:` block (panel_mode, refresh,
+// panel_firmware) before the run and records the controller snapshot in the run header.
+const WEB_RUNNER_CAPABILITIES = Object.freeze(['controller_block']);
 
 const KNOWN_EXPERIMENT_INFO_KEYS = ['name', 'date_created', 'author', 'pattern_library'];
 
@@ -215,6 +218,8 @@ function parseV3Protocol(yamlText) {
         // js/runtime-controls.js and never writes back into this YAML document.
         runtime_controls: extractRuntimeControls(data.runtime_controls),
         requires: extractRequires(data.requires),
+        // Sticky controller settings the run must assert (docs/development/controller-settings-strategy.md).
+        controller: extractControllerBlock(data.controller),
         plugins: Array.isArray(data.plugins) ? data.plugins.map(extractPlugin) : [],
         conditions: data.conditions.map(extractCondition),
         sequence: data.experiment.map(extractSequenceEntry),
@@ -295,6 +300,69 @@ function unsupportedRequires(experiment) {
     return req.filter((t) => !WEB_RUNNER_CAPABILITIES.includes(t));
 }
 
+/**
+ * `controller:` — sticky controller settings the run must assert before it starts
+ * (docs/development/controller-settings-strategy.md). Keys: panel_mode (0–3 or
+ * oneshot/persistent/triggered/gated), refresh_hz (int) XOR refresh_policy
+ * ("line_sync_safe" = cap at the rig's limits.max_refresh_hz), panel_firmware (footer
+ * version or prefix the SD's panel image must match). Tolerant on read so the Studio can
+ * open a malformed file; problems land in `errors` (blocking) / `warnings`.
+ * Mirrors js/controller-settings.js normalizeControllerBlock (that module is the runtime
+ * side and cannot be imported from this ESM module without a bundler).
+ */
+const CONTROLLER_PANEL_MODES = Object.freeze({ oneshot: 0, persist: 1, persistent: 1, triggered: 2, gated: 3 });
+const CONTROLLER_REFRESH_POLICIES = Object.freeze(['line_sync_safe']);
+function extractControllerBlock(raw) {
+    const out = {
+        declared: false,
+        panel_mode: null,
+        refresh_hz: null,
+        refresh_policy: null,
+        panel_firmware: null,
+        errors: [],
+        warnings: [],
+        raw: null
+    };
+    if (raw === undefined || raw === null) return out;
+    out.declared = true;
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        out.errors.push('controller: must be a mapping (panel_mode / refresh_hz / refresh_policy / panel_firmware)');
+        return out;
+    }
+    out.raw = JSON.parse(JSON.stringify(raw));
+    const known = ['panel_mode', 'refresh_hz', 'refresh_policy', 'panel_firmware'];
+    for (const k of Object.keys(raw)) {
+        if (!known.includes(k)) out.warnings.push('controller: unknown key "' + k + '" is ignored (known: ' + known.join(', ') + ')');
+    }
+    if (raw.panel_mode !== undefined && raw.panel_mode !== null) {
+        let m = null;
+        if (typeof raw.panel_mode === 'number' && Number.isInteger(raw.panel_mode) && raw.panel_mode >= 0 && raw.panel_mode <= 3) m = raw.panel_mode;
+        else if (typeof raw.panel_mode === 'string') {
+            const k = raw.panel_mode.trim().toLowerCase();
+            if (Object.prototype.hasOwnProperty.call(CONTROLLER_PANEL_MODES, k)) m = CONTROLLER_PANEL_MODES[k];
+            else if (/^[0-3]$/.test(k)) m = Number(k);
+        }
+        if (m === null) out.errors.push('controller.panel_mode ' + JSON.stringify(raw.panel_mode) + ' is not 0–3 or one of oneshot/persistent/triggered/gated');
+        else out.panel_mode = m;
+    }
+    if (raw.refresh_hz !== undefined && raw.refresh_hz !== null) {
+        const hz = Number(raw.refresh_hz);
+        if (!Number.isInteger(hz) || hz < 1 || hz > 2000) out.errors.push('controller.refresh_hz ' + JSON.stringify(raw.refresh_hz) + ' must be an integer 1–2000');
+        else out.refresh_hz = hz;
+    }
+    if (raw.refresh_policy !== undefined && raw.refresh_policy !== null) {
+        const pol = String(raw.refresh_policy).trim();
+        if (!CONTROLLER_REFRESH_POLICIES.includes(pol)) out.errors.push('controller.refresh_policy ' + JSON.stringify(raw.refresh_policy) + ' must be one of ' + CONTROLLER_REFRESH_POLICIES.join('/'));
+        else out.refresh_policy = pol;
+    }
+    if (out.refresh_hz !== null && out.refresh_policy !== null) out.errors.push('controller: declare refresh_hz OR refresh_policy, not both');
+    if (raw.panel_firmware !== undefined && raw.panel_firmware !== null) {
+        if (typeof raw.panel_firmware !== 'string' || !raw.panel_firmware.trim()) out.errors.push('controller.panel_firmware must be a non-empty string (a footer version or its prefix, e.g. "2p")');
+        else out.panel_firmware = raw.panel_firmware.trim();
+    }
+    return out;
+}
+
 /**
  * Extract the optional `variables:` section as an ordered list. Preserves
  * insertion order (matters for stable round-trip).
@@ -559,6 +627,11 @@ function collectBlockingErrors(experiment) {
     const base = validateReferences(experiment);
     const errors = base.ok ? [] : base.errors.slice();
 
+    // controller: block — a malformed declaration blocks (a wrong panel mode ruins data silently).
+    if (experiment && experiment.controller && Array.isArray(experiment.controller.errors)) {
+        for (const msg of experiment.controller.errors) errors.push({ kind: 'controller-block', message: msg });
+    }
+
     // The two anchor checks need the CST; skip gracefully when it's absent.
     if (experiment && experiment._doc && typeof YAML.visit === 'function') {
         // Re-parse the to-be-exported text with a LineCounter so error
@@ -674,6 +747,22 @@ function collectExportWarnings(experiment, arenaGeneration) {
                 '", which the web runner does not implement yet — the Studio will refuse to run it (MATLAB may run it).'
         });
     }
+    // 0b. controller: block declared without its capability token — a runner that does not
+    // implement the block (MATLAB today) would run with the wrong panel mode/refresh instead
+    // of refusing. Editing is fine; the validator and the Studio both say so.
+    if (experiment.controller && experiment.controller.declared) {
+        const req = Array.isArray(experiment.requires) ? experiment.requires : [];
+        if (!req.includes('controller_block')) {
+            warnings.push({
+                kind: 'controller-block-unrequired',
+                message:
+                    'Protocol declares a controller: block but not `requires: [controller_block]` — a runner without the block would run it with the wrong panel mode/refresh instead of refusing. Add the token.'
+            });
+        }
+        for (const w of experiment.controller.warnings || []) {
+            warnings.push({ kind: 'controller-block', message: w });
+        }
+    }
 
     // 1. Unused conditions
     const usedCondNames = new Set();
@@ -2308,6 +2397,8 @@ const ProtocolV3 = {
     parseRigYAMLText,
     WEB_RUNNER_CAPABILITIES,
     unsupportedRequires,
+    extractControllerBlock,
+    CONTROLLER_PANEL_MODES,
     generateV3Protocol,
     validateReferences,
     collectBlockingErrors,
@@ -2367,6 +2458,8 @@ export {
     parseRigYAMLText,
     WEB_RUNNER_CAPABILITIES,
     unsupportedRequires,
+    extractControllerBlock,
+    CONTROLLER_PANEL_MODES,
     generateV3Protocol,
     validateReferences,
     collectBlockingErrors,
diff --git a/protocols/g6_2x10_2p_diagnostics.yaml b/protocols/g6_2x10_2p_diagnostics.yaml
index a93d2b8d..5e4c4aaa 100644
--- a/protocols/g6_2x10_2p_diagnostics.yaml
+++ b/protocols/g6_2x10_2p_diagnostics.yaml
@@ -59,7 +59,20 @@ experiment_info:
   author: "mreiser"
   date_created: "2026-09-23"
 
-rig: "./configs/rigs/cshl_g6_2x10.yaml"
+rig: "./configs/rigs/bergamo_g6_2x10_2p.yaml"
+
+# The runner must implement the controller: block below (a runner that does not — MATLAB
+# today — refuses to run this file instead of running it in the wrong panel mode).
+requires: [controller_block]
+
+# Sticky controller settings asserted by Arena Studio before EVERY run and recorded in the
+# run header (docs/development/controller-settings-strategy.md). Replaces the manual
+# "set panel mode 2 by hand" step: the Studio reads the mode, sets it if needed, reads it
+# back, and refuses to run if it cannot.
+controller:
+  panel_mode: triggered            # 2 — LEDs only inside the line-clock LOW gap
+  refresh_policy: line_sync_safe   # cap the 300 Hz re-stream at the rig's limits.max_refresh_hz
+  panel_firmware: "2p"             # SD footer "2p-<sha8>[-d]" = the eintlow_2p line-sync build
 
 plugins: []
 
diff --git a/protocols/g6_2x10_2p_duty_sweep.yaml b/protocols/g6_2x10_2p_duty_sweep.yaml
index c2d9647a..2431a227 100644
--- a/protocols/g6_2x10_2p_duty_sweep.yaml
+++ b/protocols/g6_2x10_2p_duty_sweep.yaml
@@ -11,7 +11,8 @@ version: 3
 # dark-bar pattern if it is on the card (keep it Gray_16 — see note 3).
 #
 # BEFORE PRESSING RUN (Arena Studio, once per connection — not YAML-able):
-#   1. Controller ▾ → panel display mode = 2 (Triggered).  Wire: 02 1B 02
+#   1. Panel display mode 2 (Triggered) is now ASSERTED by the Studio from the controller:
+#      block below (and by the Bergamo rig default at connect) — no manual step. Wire: 02 1B 02
 #      NOT 3 (Gated): Gated restarts at row 0 on every gate drop and only the
 #      top rows of each panel ever light with a line-clock gate.
 #   2. Digital IO 1 role = out_debug_framescan.            Wire: 03 AC 01 03
@@ -85,7 +86,20 @@ experiment_info:
   author: "mreiser"
   date_created: "2026-09-22"
 
-rig: "./configs/rigs/cshl_g6_2x10.yaml"
+rig: "./configs/rigs/bergamo_g6_2x10_2p.yaml"
+
+# The runner must implement the controller: block below (a runner that does not — MATLAB
+# today — refuses to run this file instead of running it in the wrong panel mode).
+requires: [controller_block]
+
+# Sticky controller settings asserted by Arena Studio before EVERY run and recorded in the
+# run header (docs/development/controller-settings-strategy.md). Replaces the manual
+# "set panel mode 2 by hand" step: the Studio reads the mode, sets it if needed, reads it
+# back, and refuses to run if it cannot.
+controller:
+  panel_mode: triggered            # 2 — LEDs only inside the line-clock LOW gap
+  refresh_policy: line_sync_safe   # cap the 300 Hz re-stream at the rig's limits.max_refresh_hz
+  panel_firmware: "2p"             # SD footer "2p-<sha8>[-d]" = the eintlow_2p line-sync build
 
 plugins: []
 
diff --git a/tests/fixtures/v3_controller_block.yaml b/tests/fixtures/v3_controller_block.yaml
new file mode 100644
index 00000000..bab1b35e
--- /dev/null
+++ b/tests/fixtures/v3_controller_block.yaml
@@ -0,0 +1,54 @@
+version: 3
+
+# ============================================================================
+# controller: block fixture — a protocol that declares the sticky controller
+# settings it needs (panel display mode, refresh policy, panel firmware) and
+# the `controller_block` capability token so a runner that does not implement
+# the block refuses to run it instead of silently ignoring it.
+# ============================================================================
+
+experiment_info:
+  name: "v3 fixture — controller block"
+  date_created: "2026-09-24"
+  author: "webDisplayTools test fixture"
+
+rig: "./configs/rigs/bergamo_g6_2x10_2p.yaml"
+
+requires: [controller_block]
+
+controller:
+  panel_mode: triggered
+  refresh_policy: line_sync_safe
+  panel_firmware: "2p"
+
+plugins: []
+
+variables:
+  - &dur 2
+
+experiment:
+  - "blank"
+  - "show"
+  - "blank"
+
+conditions:
+  - name: "blank"
+    commands:
+      - type: "controller"
+        command_name: "allOff"
+      - type: "wait"
+        duration: *dur
+  - name: "show"
+    commands:
+      - type: "controller"
+        command_name: "trialParams"
+        pattern: "frame2_h_ccw_200f"
+        pattern_ID: 4
+        duration: *dur
+        mode: 2
+        frame_index: 0
+        frame_rate: 20
+        gain: 0
+        duty: 128
+      - type: "wait"
+        duration: *dur
diff --git a/tests/test-controller-settings.js b/tests/test-controller-settings.js
new file mode 100644
index 00000000..158bcefa
--- /dev/null
+++ b/tests/test-controller-settings.js
@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+/**
+ * Tests for js/controller-settings.js (the pure "assert before run" planner) and the rig
+ * YAML `defaults:` / `limits:` / `requires:` / `strict:` parsing in js/plugin-registry.js.
+ *
+ * Run: node tests/test-controller-settings.js   (wired into `pixi run test`)
+ */
+'use strict';
+
+const CS = require('../js/controller-settings.js');
+const Registry = require('../js/plugin-registry.js');
+
+let checks = 0;
+let failures = 0;
+function check(name, got, expected) {
+    checks++;
+    const g = JSON.stringify(got);
+    const e = JSON.stringify(expected);
+    const ok = g === e;
+    console.log(`  ${ok ? 'PASS' : 'FAIL'}  ${name}: got ${g}, expected ${e}`);
+    if (!ok) failures++;
+}
+function checkTrue(name, cond, info) {
+    checks++;
+    console.log(`  ${cond ? 'PASS' : 'FAIL'}  ${name}${info ? ' — ' + info : ''}`);
+    if (!cond) failures++;
+}
+
+console.log('normalizePanelMode');
+check('int 2', CS.normalizePanelMode(2), 2);
+check('"triggered"', CS.normalizePanelMode('triggered'), 2);
+check('"Persist"', CS.normalizePanelMode('Persist'), 1);
+check('"persistent"', CS.normalizePanelMode('persistent'), 1);
+check('"3"', CS.normalizePanelMode('3'), 3);
+check('7 → null', CS.normalizePanelMode(7), null);
+check('"fast" → null', CS.normalizePanelMode('fast'), null);
+check('null → null', CS.normalizePanelMode(null), null);
+
+console.log('firmwareMatches');
+checkTrue('2p matches 2p-9014b5bb-d', CS.firmwareMatches('2p-9014b5bb-d', '2p'));
+checkTrue('tag matches itself', CS.firmwareMatches('panel-fw-v1.2.0', 'panel-fw-v1.2.0'));
+checkTrue('2p does not match panel-fw-v1.2.0', !CS.firmwareMatches('panel-fw-v1.2.0', '2p'));
+checkTrue('empty requirement always matches', CS.firmwareMatches('anything', ''));
+checkTrue('no footer never matches a requirement', !CS.firmwareMatches(null, '2p'));
+
+console.log('normalizeControllerBlock');
+const nb = CS.normalizeControllerBlock({ panel_mode: 'triggered', refresh_policy: 'line_sync_safe', panel_firmware: '2p' });
+check('normalized', [nb.declared, nb.panel_mode, nb.refresh_hz, nb.refresh_policy, nb.panel_firmware, nb.errors.length], [true, 2, null, 'line_sync_safe', '2p', 0]);
+check('absent → undeclared', CS.normalizeControllerBlock(undefined).declared, false);
+check('bad mode → error', CS.normalizeControllerBlock({ panel_mode: 9 }).errors.length, 1);
+check('hz + policy → error', CS.normalizeControllerBlock({ refresh_hz: 300, refresh_policy: 'line_sync_safe' }).errors.length, 1);
+check('unknown key → warning', CS.normalizeControllerBlock({ foo: 1 }).warnings.length, 1);
+check('list → error', CS.normalizeControllerBlock([1]).errors.length, 1);
+
+console.log('rig YAML settings (parseRigIo)');
+const rig2p = Registry.parseRigIo({
+    name: 'Bergamo', io: { dio: [{ port: 1, role: 'out_debug_framescan' }, { port: 2, role: 'in_trigger' }], ao: { role: 'programmable', default: 0 } },
+    defaults: { panel_mode: 'triggered' }, limits: { max_refresh_hz: 300 }, requires: { panel_firmware: '2p' }, strict: true
+});
+check('rig defaults/limits/requires/strict', [rig2p.name, rig2p.defaults.panel_mode, rig2p.limits.max_refresh_hz, rig2p.requires.panel_firmware, rig2p.strict, rig2p.dio[1].role], ['Bergamo', 2, 300, '2p', true, 'in_trigger']);
+const rigCourse = Registry.parseRigIo({ io: { dio: [{ port: 1, role: 'out_debug_framescan' }] }, defaults: { panel_mode: 'persistent' } });
+check('course rig default persistent, not strict', [rigCourse.defaults.panel_mode, rigCourse.strict, rigCourse.limits.max_refresh_hz], [1, false, null]);
+const rigBad = Registry.parseRigIo({ defaults: { panel_mode: 'fast' }, limits: { max_refresh_hz: 99999 }, requires: { panel_firmware: 5 } });
+check('bad rig values → 3 warnings, all null', [rigBad.warnings.length, rigBad.defaults.panel_mode, rigBad.limits.max_refresh_hz, rigBad.requires.panel_firmware], [3, null, null, null]);
+check('parseRigIo(null) has the new fields', [Registry.parseRigIo(null).defaults.panel_mode, Registry.parseRigIo(null).strict], [null, false]);
+
+console.log('planAssertions — 2P protocol on the 2P rig');
+const block2p = CS.normalizeControllerBlock({ panel_mode: 2, refresh_policy: 'line_sync_safe', panel_firmware: '2p' });
+const snapOk = { panel_mode: 1, refresh_hz: 300, capabilities: ['g6_mode', 'v3_triggered', 'v3_gated', 'io_ext'], panel_firmware: { version: '2p-9014b5bb-d' }, verified: { ok: true, verified: 20, total: 20, at: 't' } };
+let plan = CS.planAssertions({ block: block2p, rig: rig2p, snapshot: snapOk, patterns: [{ name: 'a', gsVal: 2 }], protocolRig: 'bergamo_g6_2x10_2p', sessionRig: 'bergamo_g6_2x10_2p' });
+check('ok, strict, one action: mode 1→2', [plan.ok, plan.strict, plan.actions], [true, true, [{ setting: 'panel_mode', from: 1, to: 2 }]]);
+check('intended recorded', [plan.intended.panel_mode, plan.intended.refresh_hz_max, plan.intended.panel_firmware, plan.intended.pattern_gs], [2, 300, '2p', ['GS16']]);
+check('no warnings', plan.warnings, []);
+
+console.log('planAssertions — refresh derivation');
+plan = CS.planAssertions({ block: block2p, rig: rig2p, snapshot: Object.assign({}, snapOk, { panel_mode: 2, refresh_hz: 1000 }), patterns: [{ name: 'a', gsVal: 2 }] });
+check('refresh above cap → set to cap', plan.actions, [{ setting: 'refresh_hz', from: 1000, to: 300 }]);
+plan = CS.planAssertions({ block: block2p, rig: rig2p, snapshot: Object.assign({}, snapOk, { panel_mode: 2, refresh_hz: 250 }), patterns: [{ name: 'gs2', gsVal: 1 }] });
+check('GS2 pattern (default 1000) on capped rig → pin to cap', plan.actions, [{ setting: 'refresh_hz', from: 250, to: 300 }]);
+plan = CS.planAssertions({ block: block2p, rig: rig2p, snapshot: Object.assign({}, snapOk, { panel_mode: 2, refresh_hz: 300 }), patterns: [{ name: 'a', gsVal: null }] });
+check('unknown grayscale → warning, no action', [plan.actions.length, plan.warnings.length], [0, 1]);
+const blockHz = CS.normalizeControllerBlock({ panel_mode: 2, refresh_hz: 500 });
+plan = CS.planAssertions({ block: blockHz, rig: rig2p, snapshot: snapOk, patterns: [] });
+check('explicit refresh_hz above rig cap → blocking', plan.ok, false);
+plan = CS.planAssertions({ block: CS.normalizeControllerBlock({ refresh_hz: 200 }), rig: rigCourse, snapshot: Object.assign({}, snapOk, { refresh_hz: 300 }), patterns: [] });
+check('explicit refresh_hz on an uncapped rig → set', plan.actions, [{ setting: 'refresh_hz', from: 300, to: 200 }]);
+
+console.log('planAssertions — course protocol inherits the rig default');
+plan = CS.planAssertions({ block: undefined, rig: rigCourse, snapshot: Object.assign({}, snapOk, { panel_mode: 2 }), patterns: [] });
+check('bench left in triggered → set back to persistent, not strict', [plan.ok, plan.strict, plan.actions], [true, false, [{ setting: 'panel_mode', from: 2, to: 1 }]]);
+plan = CS.planAssertions({ block: undefined, rig: Registry.parseRigIo({}), snapshot: snapOk, patterns: [] });
+check('nothing declared anywhere → record only', [plan.ok, plan.actions.length, Object.keys(plan.intended).filter((k) => plan.intended[k] != null).length], [true, 0, 0]);
+
+console.log('planAssertions — what refuses');
+plan = CS.planAssertions({ block: block2p, rig: rigCourse, snapshot: snapOk, patterns: [], protocolRig: 'bergamo_g6_2x10_2p', sessionRig: 'cshl_g6_2x10' });
+checkTrue('2P protocol on a course rig → rig mismatch blocks (protocol block makes it strict)', !plan.ok && plan.blocking.some((b) => /rig/.test(b)), plan.blocking.join(' | '));
+plan = CS.planAssertions({ block: block2p, rig: rig2p, snapshot: Object.assign({}, snapOk, { panel_firmware: { version: 'panel-fw-v1.2.0' } }), patterns: [] });
+checkTrue('wrong panel firmware → blocks', !plan.ok && plan.blocking.some((b) => /firmware/.test(b)), plan.blocking.join(' | '));
+plan = CS.planAssertions({ block: block2p, rig: rig2p, snapshot: Object.assign({}, snapOk, { verified: { ok: false, verified: 18, total: 20, mismatched: [7, 12] } }), patterns: [] });
+checkTrue('failed fleet verify → blocks and names the panels', !plan.ok && plan.blocking.some((b) => /panels 7, 12/.test(b)), plan.blocking.join(' | '));
+plan = CS.planAssertions({ block: block2p, rig: rig2p, snapshot: Object.assign({}, snapOk, { verified: null }), patterns: [] });
+checkTrue('unverified fleet → warning, not blocking', plan.ok && plan.warnings.some((w) => /not verified/.test(w)), plan.warnings.join(' | '));
+plan = CS.planAssertions({ block: block2p, rig: rig2p, snapshot: Object.assign({}, snapOk, { capabilities: ['g6_mode'] }), patterns: [] });
+checkTrue('mode 2 without v3_triggered capability → blocks', !plan.ok && plan.blocking.some((b) => /v3_triggered/.test(b)), plan.blocking.join(' | '));
+plan = CS.planAssertions({ block: block2p, rig: rig2p, snapshot: Object.assign({}, snapOk, { panel_mode: null }), patterns: [] });
+checkTrue('unreadable mode on a strict rig → blocks', !plan.ok && plan.blocking.some((b) => /cannot read the panel display mode/.test(b)), plan.blocking.join(' | '));
+plan = CS.planAssertions({ block: undefined, rig: rigCourse, snapshot: Object.assign({}, snapOk, { panel_mode: null }), patterns: [] });
+checkTrue('unreadable mode on a course rig → warning only', plan.ok && plan.warnings.length === 1, plan.warnings.join(' | '));
+plan = CS.planAssertions({ block: CS.normalizeControllerBlock({ panel_mode: 'nope' }), rig: rigCourse, snapshot: snapOk, patterns: [] });
+check('block errors are blocking', plan.ok, false);
+
+console.log('formatSnapshot');
+const line = CS.formatSnapshot(Object.assign({}, snapOk, { spi_mhz: 20, ao_mv: 0, dio_roles: [{ port: 1, role: 'out_debug_framescan' }, { port: 2, role: 'in_trigger' }], controller_firmware: 'v3' }));
+checkTrue('one line names mode, refresh, DIO roles, firmware', /persistent.*300 Hz.*SPI 20.*1=out_debug_framescan 2=in_trigger.*2p-9014b5bb-d.*verified 20\/20/.test(line), line);
+
+console.log(`\n${checks - failures}/${checks} checks passed`);
+process.exit(failures ? 1 : 0);
diff --git a/tests/test-protocol-roundtrip-v3.js b/tests/test-protocol-roundtrip-v3.js
index 5bc8f657..5095aad4 100644
--- a/tests/test-protocol-roundtrip-v3.js
+++ b/tests/test-protocol-roundtrip-v3.js
@@ -27,6 +27,7 @@ const {
     validateReferences,
     collectBlockingErrors,
     collectExportWarnings,
+    unsupportedRequires,
     V3ParseError,
     docSet,
     docDelete,
@@ -4771,6 +4772,46 @@ console.log('\n--- Suite 37: led_activation sub-fields by path (anchor binding)
 }
 
 // ─── Results ────────────────────────────────────────────────────────────────
+// ─── Test Suite 39: controller: block (sticky controller settings) ─────────
+console.log('\n--- Suite 39: controller: block ---');
+
+{
+    const exp = parseV3Protocol(readFixture('v3_controller_block.yaml'));
+    check('controller: declared', exp.controller.declared, true);
+    check('controller: panel_mode "triggered" → 2', exp.controller.panel_mode, 2);
+    check('controller: refresh_policy', exp.controller.refresh_policy, 'line_sync_safe');
+    check('controller: refresh_hz absent → null', exp.controller.refresh_hz, null);
+    check('controller: panel_firmware', exp.controller.panel_firmware, '2p');
+    check('controller: no errors', exp.controller.errors.length, 0);
+    check('controller: not an unknown top-level key', Object.keys(exp._unknownTopLevel || {}).includes('controller'), false);
+    check('requires: controller_block is a web-runner capability', unsupportedRequires(exp).length, 0);
+    check('controller: fixture has no blocking errors', collectBlockingErrors(exp).errors.length, 0);
+    checkTrue('controller: fixture has no export warnings', collectExportWarnings(exp).warnings.length === 0);
+    const regen = generateV3Protocol(exp);
+    checkTrue('controller: block survives regen', /controller:\s*\n\s+panel_mode: triggered/.test(regen));
+    const again = parseV3Protocol(regen);
+    check('controller: round-trip stable', again.controller.panel_mode, 2);
+}
+{
+    // absent block → undeclared, no warnings
+    const exp = parseV3Protocol(readFixture('v3_canonical_a.yaml'));
+    check('controller: absent → declared false', exp.controller.declared, false);
+    checkTrue('controller: absent adds no warnings', !collectExportWarnings(exp).warnings.some((w) => /controller/.test(w.kind)));
+}
+{
+    // malformed values block; a block without the capability token warns
+    const bad = readFixture('v3_controller_block.yaml')
+        .replace('panel_mode: triggered', 'panel_mode: warp')
+        .replace('refresh_policy: line_sync_safe', 'refresh_policy: line_sync_safe\n  refresh_hz: 300')
+        .replace('requires: [controller_block]', '');
+    const exp = parseV3Protocol(bad);
+    check('controller: bad mode + hz&policy → 2 errors', exp.controller.errors.length, 2);
+    check('controller: errors are blocking', collectBlockingErrors(exp).errors.filter((e) => e.kind === 'controller-block').length, 2);
+    checkTrue('controller: missing requires token → warning', collectExportWarnings(exp).warnings.some((w) => w.kind === 'controller-block-unrequired'));
+    const listy = parseV3Protocol(readFixture('v3_controller_block.yaml').replace(/controller:\n(  .*\n)+/, 'controller: [2]\n'));
+    check('controller: a list is an error', listy.controller.errors.length, 1);
+}
+
 console.log('\n=== Results: ' + passedTests + '/' + totalTests + ' passed ===');
 if (failedTests.length > 0) {
     console.log('\nFailed tests:');
diff --git a/tests/test-studio-runtime-vars.js b/tests/test-studio-runtime-vars.js
index 62a305e5..2755ba1e 100644
--- a/tests/test-studio-runtime-vars.js
+++ b/tests/test-studio-runtime-vars.js
@@ -132,7 +132,7 @@ checkBool(
     'collectExportWarnings flags it (soft: editing stays possible)',
     !!warn && /refuse to run/.test(warn.message)
 );
-check('WEB_RUNNER_CAPABILITIES is exported (empty today)', v3.WEB_RUNNER_CAPABILITIES, []);
+check('WEB_RUNNER_CAPABILITIES is exported (controller_block since v0.88)', v3.WEB_RUNNER_CAPABILITIES, ['controller_block']);
 checkBool('requires survives regeneration', /requires:/.test(v3.generateV3Protocol(reqExp)));
 
 console.log('\n=== opto protocol end to end through runtime-controls.js ===');

From ee2307dfe63db99f3fc38acba289dac9c1018493 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 18 Oct 2026 13:13:10 -0400
Subject: [PATCH 2/3] =?UTF-8?q?protocol:=20g6=5F2p=5Fcolor=5Fled=5Fsweep?=
 =?UTF-8?q?=20=E2=80=94=20Bergamo=20rig=20+=20controller:=20block;=20heade?=
 =?UTF-8?q?r=20no=20longer=20lists=20manual=20steps?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The 2P color LED-intensity sweep (first run on the Bergamo 2026-10-16, on PR #254's
branch) now points at configs/rigs/bergamo_g6_2x10_2p.yaml, declares
`requires: [controller_block]` and the `controller:` block (triggered, line_sync_safe,
panel firmware "2p"), and its header says that the Studio asserts the four Console
steps it used to ask the operator to do by hand (panel mode 2, DIO 1 role, 300 Hz,
panel firmware). What remains manual: pick the Bergamo session rig, Verify panels
once per session, telemetry on.

This file also exists on #254 (candidate 2026-10-20) with the old header and the cshl
rig; when that lands on main, resolve the add/add conflict in favor of this copy. The
pattern folder and the protocols/index.json entry stay with #254.

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

diff --git a/protocols/g6_2p_color_led_sweep.yaml b/protocols/g6_2p_color_led_sweep.yaml
new file mode 100644
index 00000000..449d02f5
--- /dev/null
+++ b/protocols/g6_2p_color_led_sweep.yaml
@@ -0,0 +1,608 @@
+version: 3
+
+# ============================================================================
+# 2P color LED-intensity sweep — G6 2x10 four-color arena on the Bergamo
+# (2026-10-16), ScanImage driven from the protocol through the bridge's
+# `scanimage` connector (ScanImage's built-in JSON server, LAB-303 / LAB-306).
+#
+# What it does: for each LED color (violet 405, blue 470, green 525,
+# yellow-orange 590 nm) ONE ScanImage GRAB, inside which the top-row one-color
+# grating rotates at `fps` frames/s through six panel duty levels (7 … 255),
+# `step_dur` s each, then the arena goes dark and the protocol waits for the
+# grab to finish. Four TIFF series ("<color>_sweep_<NNN>"), each holding the
+# six intensity steps of one color. Total ≈ 2.5 min.
+#
+# CHANGE THE EXPERIMENT ONLY IN `variables:` below — colors (pattern + SD slot),
+# duty levels, step length, speed, frames per grab, timeouts.
+#
+# PATTERNS: protocols/g6_2p_color_led_sweep_patterns/ — the four one-color
+# top-row gratings of g6_color_optomotor_test re-encoded as GS16 (lit pixels 15,
+# 20 frames; `node scripts/make-color-optomotor-patterns.js --gs16`). GS16 so the
+# controller re-streams at its 300 Hz default, as in the 22 Sept 2026 duty-sweep
+# runs — the GS2 set on the card (slots 1–4) would default to 1000 Hz, a refresh
+# confound the imaging comparison does not need. UPLOAD THE FOLDER ONCE before
+# Run (Console → Patterns → Add ▾ → the folder). The Studio resolves patterns by
+# NAME from the SD listing; the pattern_IDs below are only the fallback — check
+# the slots in the Console's SD listing after the upload and fix them if needed.
+# To fall back to the GS2 set, change the four pattern names/IDs in `variables:`
+# (the Studio caps the refresh at 300 Hz for it — see below).
+#
+# BEFORE PRESSING RUN (Arena Studio):
+#   The four manual Controller ▾ / Debug ▾ steps this header used to list (panel
+#   display mode 2, Digital IO 1 role, 300 Hz refresh, panel firmware) are now
+#   ASSERTED BY THE STUDIO before every Run or Test, from the rig file
+#   (configs/rigs/bergamo_g6_2x10_2p.yaml) and the `controller:` block below
+#   (docs/development/controller-settings.md): read → set if different → read
+#   back. The run is REFUSED if the arena cannot be put into the required state,
+#   and the before/after controller snapshot goes into the run header.
+#     · panel display mode 2 (Triggered)   rig defaults.panel_mode + controller.panel_mode.
+#       The 2P line-sync panel firmware free-runs one row per line-clock edge; NOT 3 (Gated).
+#       Wire, if ever needed by hand: 02 1B 02
+#     · Digital IO 1 (J3) = out_debug_framescan, Digital IO 2 (J4) = in_trigger
+#       rig io: at connect. DO1 is HIGH for every SPI frame transfer — THE alignment
+#       signal today (no analog marker yet): record it in ScanImage as an aux/AI
+#       channel. J4 is the line-clock → EINT route.
+#     · refresh rate ≤ 300 Hz              rig limits.max_refresh_hz + refresh_policy:
+#       line_sync_safe. 300 Hz is the GS16 default; the GS2 set (1000 Hz default,
+#       where every re-streamed frame costs the panel line edges) is capped to 300
+#       automatically — no Debug ▾ unlock.
+#     · panel firmware "2p-…"              rig requires.panel_firmware, checked against
+#       the SD footer and the session's panel verify; a mismatch blocks the run.
+#   Still yours, once per connection:
+#   1. ⚙ Settings → session rig = "Bergamo G6 — 2×10 two-photon line-sync (strict)".
+#      This protocol's rig: must be the session rig, or the run is refused.
+#   2. Settings → Controller → Verify panels (~1 s per panel) so the run header
+#      carries a fleet verify; the strict rig warns loudly without one.
+#   3. Telemetry ring: on (default).
+#   NEW ARENA CHECK (this arena has not been on the microscope before; 20 panels,
+#   top row on the bank-window firmware, bottom row v1.3.1 — all with the 2P
+#   timing): Console → Panel firmware → Inventory must show 20 present (repeat
+#   after every power cycle; the top-row builds have hung at boot before). With
+#   the line clock running and display mode 2, Console → Test → full-field at
+#   level ≤ 128 (the 5 A supply resets at all-on 255) must light every panel at
+#   about ⅓ of mode-1 brightness; with the line clock stopped every panel must
+#   go dark; DO1 must show one pulse per controller refresh tick on the scope /
+#   ScanImage AI, and the line clock must be seen on the loop-back channel.
+#
+# SCANIMAGE SETUP (operator, in the GUI; the protocol does not touch these):
+#   unidirectional scanning, both channels saved (channelSave = [1 2]),
+#   lasers ON (this is a data run, not a dark test),
+#   logging ON, logFilePath on the F: data disk (F:\ImagingData\<date>\…),
+#   detectors on. The protocol sets framesPerSlice (frames per grab)
+#   to `frames_per_grab` in pre_blank and the file stem per color; nothing else.
+#   ScanImage must record: DO1 (frame-transfer envelope) and the line clock
+#   loop-back on aux inputs or spare AI channels — see
+#   docs/development/2p-scanimage-signal-logging.md §0.
+#
+# Notes
+#   1. duty: 0 in trialParams means "pattern's stored duty", NOT off. Off is allOff.
+#   2. Each duty step is its own condition (one trialParams each; the pattern
+#      restarts at frame 0 with the new duty). The first condition of a color
+#      sets the file stem and starts the grab; the last ends with allOff and
+#      waits for the grab to finish (waitIdle). frames_per_grab must cover
+#      grab_settle + 6 × step_dur plus margin at the scan frame rate (29 Hz:
+#      6 × 3 + 1 = 19 s → 640 frames ≈ 22 s).
+#   3. End with allOff, not stopDisplay: on the free-running Triggered firmware
+#      a stopped controller leaves the last frame lit, one row per line.
+#   4. A plugin command waits for its reply (grab ≈ 1–3 s on the Bergamo PC);
+#      the condition durations shown in the Studio exclude that wait.
+# ============================================================================
+
+experiment_info:
+  name: "2P color LED-intensity sweep (G6 2x10 four-color, ScanImage grabs)"
+  author: "mreiser"
+  date_created: "2026-10-16"
+
+rig: "./configs/rigs/bergamo_g6_2x10_2p.yaml"
+
+# The runner must implement the controller: block below (a runner that does not — MATLAB
+# today — refuses to run this file instead of running it in the wrong panel mode).
+requires: [controller_block]
+
+# Sticky controller settings asserted by Arena Studio before EVERY run and recorded in the
+# run header (docs/development/controller-settings.md). Replaces the manual "set panel
+# mode 2 / refresh 300 Hz by hand" steps: the Studio reads each setting, sets it if needed,
+# reads it back, and refuses to run if it cannot.
+controller:
+  panel_mode: triggered            # 2 — LEDs only inside the line-clock LOW gap
+  refresh_policy: line_sync_safe   # cap the re-stream at the rig's limits.max_refresh_hz (300)
+  panel_firmware: "2p"             # SD footer "2p-<sha8>[-d]" = the eintlow_2p line-sync build
+
+plugins:
+  - name: "scanimage"
+    type: "class"
+    matlab:
+      class: "ScanImagePlugin"   # web runner only — MATLAB has no ScanImagePlugin
+
+variables:
+  # ── patterns (GS16 set; IDs = expected slots after uploading the folder onto a
+  #    card that already holds the GS2 set in 1–4 — verify in the SD listing) ──
+  - &pat_violet "G6_2x10_toprow_grat20_violet_gs16"
+  - &id_violet 7            # Bergamo card 2026-10-16: slots as resolved by name in the dry run
+  - &pat_blue "G6_2x10_toprow_grat20_blue_gs16"
+  - &id_blue 3
+  - &pat_green "G6_2x10_toprow_grat20_green_gs16"
+  - &id_green 5
+  - &pat_yellow "G6_2x10_toprow_grat20_yellow_gs16"
+  - &id_yellow 9
+  # ── timing ────────────────────────────────────────────────────────────────
+  - &fps 20                 # frames/s; 20-frame grating → one period per second
+  - &step_dur 3             # s per duty level
+  - &grab_settle 1          # s between the grab reply and the first stimulus
+  - &blank_dur 3            # s dark before the first and after the last color
+  - &frames_per_grab 800    # ScanImage framesPerSlice: ≥ (grab_settle + 6·step_dur) × scan frame rate
+                            #   Bergamo 2026-10-16: 29.1 Hz at 256×256 unidirectional. Host-timed steps ran
+                            #   ~3.6 s (not 3) for colors 2–4, so the stimulus spans ~24.4 s from the grab
+                            #   reply; 640 frames (22 s) cut the end of duty 255 → 800 (27.5 s, ~3 s margin).
+                            #   (at 512×512 it is 15.0 Hz → ~410)
+  - &wait_idle_s 45         # waitIdle timeout: frames_per_grab / frame rate + margin
+  # ── intensity = panel duty (0–255) ────────────────────────────────────────
+  - &duty_a 7
+  - &duty_b 15
+  - &duty_c 31
+  - &duty_d 63
+  - &duty_e 127
+  - &duty_f 255
+
+experiment:
+  - "pre_blank"
+  - "violet_d7"
+  - "violet_d15"
+  - "violet_d31"
+  - "violet_d63"
+  - "violet_d127"
+  - "violet_d255"
+  - "blue_d7"
+  - "blue_d15"
+  - "blue_d31"
+  - "blue_d63"
+  - "blue_d127"
+  - "blue_d255"
+  - "green_d7"
+  - "green_d15"
+  - "green_d31"
+  - "green_d63"
+  - "green_d127"
+  - "green_d255"
+  - "yellow_d7"
+  - "yellow_d15"
+  - "yellow_d31"
+  - "yellow_d63"
+  - "yellow_d127"
+  - "yellow_d255"
+  - "post_blank"
+
+conditions:
+  # Display dark; frames per grab set once for the whole run.
+  - name: "pre_blank"
+    commands:
+      - type: "controller"
+        command_name: "allOff"
+      - type: "plugin"
+        plugin_name: "scanimage"
+        command_name: "set"
+        params:
+          property: "hStackManager.framesPerSlice"
+          value: *frames_per_grab
+      - type: "wait"
+        duration: *blank_dur
+
+  # ── violet 405 nm ─────────────────────────────────────────────────────────
+  - name: "violet_d7"
+    commands:
+      - type: "plugin"
+        plugin_name: "scanimage"
+        command_name: "setFileStem"
+        params:
+          stem: "violet_sweep"
+      - type: "plugin"
+        plugin_name: "scanimage"
+        command_name: "grab"
+      - type: "wait"
+        duration: *grab_settle
+      - type: "controller"
+        command_name: "trialParams"
+        pattern: *pat_violet
+        pattern_ID: *id_violet
+        duration: *step_dur
+        mode: 2
+        frame_index: 0
+        frame_rate: *fps
+        gain: 0
+        duty: *duty_a
+      - type: "wait"
+        duration: *step_dur
+  - name: "violet_d15"
+    commands:
+      - type: "controller"
+        command_name: "trialParams"
+        pattern: *pat_violet
+        pattern_ID: *id_violet
+        duration: *step_dur
+        mode: 2
+        frame_index: 0
+        frame_rate: *fps
+        gain: 0
+        duty: *duty_b
+      - type: "wait"
+        duration: *step_dur
+  - name: "violet_d31"
+    commands:
+      - type: "controller"
+        command_name: "trialParams"
+        pattern: *pat_violet
+        pattern_ID: *id_violet
+        duration: *step_dur
+        mode: 2
+        frame_index: 0
+        frame_rate: *fps
+        gain: 0
+        duty: *duty_c
+      - type: "wait"
+        duration: *step_dur
+  - name: "violet_d63"
+    commands:
+      - type: "controller"
+        command_name: "trialParams"
+        pattern: *pat_violet
+        pattern_ID: *id_violet
+        duration: *step_dur
+        mode: 2
+        frame_index: 0
+        frame_rate: *fps
+        gain: 0
+        duty: *duty_d
+      - type: "wait"
+        duration: *step_dur
+  - name: "violet_d127"
+    commands:
+      - type: "controller"
+        command_name: "trialParams"
+        pattern: *pat_violet
+        pattern_ID: *id_violet
+        duration: *step_dur
+        mode: 2
+        frame_index: 0
+        frame_rate: *fps
+        gain: 0
+        duty: *duty_e
+      - type: "wait"
+        duration: *step_dur
+  - name: "violet_d255"
+    commands:
+      - type: "controller"
+        command_name: "trialParams"
+        pattern: *pat_violet
+        pattern_ID: *id_violet
+        duration: *step_dur
+        mode: 2
+        frame_index: 0
+        frame_rate: *fps
+        gain: 0
+        duty: *duty_f
+      - type: "wait"
+        duration: *step_dur
+      - type: "controller"
+        command_name: "allOff"
+      - type: "plugin"
+        plugin_name: "scanimage"
+        command_name: "waitIdle"
+        params:
+          timeout_s: *wait_idle_s
+
+  # ── blue 470 nm ───────────────────────────────────────────────────────────
+  - name: "blue_d7"
+    commands:
+      - type: "plugin"
+        plugin_name: "scanimage"
+        command_name: "setFileStem"
+        params:
+          stem: "blue_sweep"
+      - type: "plugin"
+        plugin_name: "scanimage"
+        command_name: "grab"
+      - type: "wait"
+        duration: *grab_settle
+      - type: "controller"
+        command_name: "trialParams"
+        pattern: *pat_blue
+        pattern_ID: *id_blue
+        duration: *step_dur
+        mode: 2
+        frame_index: 0
+        frame_rate: *fps
+        gain: 0
+        duty: *duty_a
+      - type: "wait"
+        duration: *step_dur
+  - name: "blue_d15"
+    commands:
+      - type: "controller"
+        command_name: "trialParams"
+        pattern: *pat_blue
+        pattern_ID: *id_blue
+        duration: *step_dur
+        mode: 2
+        frame_index: 0
+        frame_rate: *fps
+        gain: 0
+        duty: *duty_b
+      - type: "wait"
+        duration: *step_dur
+  - name: "blue_d31"
+    commands:
+      - type: "controller"
+        command_name: "trialParams"
+        pattern: *pat_blue
+        pattern_ID: *id_blue
+        duration: *step_dur
+        mode: 2
+        frame_index: 0
+        frame_rate: *fps
+        gain: 0
+        duty: *duty_c
+      - type: "wait"
+        duration: *step_dur
+  - name: "blue_d63"
+    commands:
+      - type: "controller"
+        command_name: "trialParams"
+        pattern: *pat_blue
+        pattern_ID: *id_blue
+        duration: *step_dur
+        mode: 2
+        frame_index: 0
+        frame_rate: *fps
+        gain: 0
+        duty: *duty_d
+      - type: "wait"
+        duration: *step_dur
+  - name: "blue_d127"
+    commands:
+      - type: "controller"
+        command_name: "trialParams"
+        pattern: *pat_blue
+        pattern_ID: *id_blue
+        duration: *step_dur
+        mode: 2
+        frame_index: 0
+        frame_rate: *fps
+        gain: 0
+        duty: *duty_e
+      - type: "wait"
+        duration: *step_dur
+  - name: "blue_d255"
+    commands:
+      - type: "controller"
+        command_name: "trialParams"
+        pattern: *pat_blue
+        pattern_ID: *id_blue
+        duration: *step_dur
+        mode: 2
+        frame_index: 0
+        frame_rate: *fps
+        gain: 0
+        duty: *duty_f
+      - type: "wait"
+        duration: *step_dur
+      - type: "controller"
+        command_name: "allOff"
+      - type: "plugin"
+        plugin_name: "scanimage"
+        command_name: "waitIdle"
+        params:
+          timeout_s: *wait_idle_s
+
+  # ── green 525 nm ──────────────────────────────────────────────────────────
+  - name: "green_d7"
+    commands:
+      - type: "plugin"
+        plugin_name: "scanimage"
+        command_name: "setFileStem"
+        params:
+          stem: "green_sweep"
+      - type: "plugin"
+        plugin_name: "scanimage"
+        command_name: "grab"
+      - type: "wait"
+        duration: *grab_settle
+      - type: "controller"
+        command_name: "trialParams"
+        pattern: *pat_green
+        pattern_ID: *id_green
+        duration: *step_dur
+        mode: 2
+        frame_index: 0
+        frame_rate: *fps
+        gain: 0
+        duty: *duty_a
+      - type: "wait"
+        duration: *step_dur
+  - name: "green_d15"
+    commands:
+      - type: "controller"
+        command_name: "trialParams"
+        pattern: *pat_green
+        pattern_ID: *id_green
+        duration: *step_dur
+        mode: 2
+        frame_index: 0
+        frame_rate: *fps
+        gain: 0
+        duty: *duty_b
+      - type: "wait"
+        duration: *step_dur
+  - name: "green_d31"
+    commands:
+      - type: "controller"
+        command_name: "trialParams"
+        pattern: *pat_green
+        pattern_ID: *id_green
+        duration: *step_dur
+        mode: 2
+        frame_index: 0
+        frame_rate: *fps
+        gain: 0
+        duty: *duty_c
+      - type: "wait"
+        duration: *step_dur
+  - name: "green_d63"
+    commands:
+      - type: "controller"
+        command_name: "trialParams"
+        pattern: *pat_green
+        pattern_ID: *id_green
+        duration: *step_dur
+        mode: 2
+        frame_index: 0
+        frame_rate: *fps
+        gain: 0
+        duty: *duty_d
+      - type: "wait"
+        duration: *step_dur
+  - name: "green_d127"
+    commands:
+      - type: "controller"
+        command_name: "trialParams"
+        pattern: *pat_green
+        pattern_ID: *id_green
+        duration: *step_dur
+        mode: 2
+        frame_index: 0
+        frame_rate: *fps
+        gain: 0
+        duty: *duty_e
+      - type: "wait"
+        duration: *step_dur
+  - name: "green_d255"
+    commands:
+      - type: "controller"
+        command_name: "trialParams"
+        pattern: *pat_green
+        pattern_ID: *id_green
+        duration: *step_dur
+        mode: 2
+        frame_index: 0
+        frame_rate: *fps
+        gain: 0
+        duty: *duty_f
+      - type: "wait"
+        duration: *step_dur
+      - type: "controller"
+        command_name: "allOff"
+      - type: "plugin"
+        plugin_name: "scanimage"
+        command_name: "waitIdle"
+        params:
+          timeout_s: *wait_idle_s
+
+  # ── yellow-orange 590 nm ──────────────────────────────────────────────────
+  - name: "yellow_d7"
+    commands:
+      - type: "plugin"
+        plugin_name: "scanimage"
+        command_name: "setFileStem"
+        params:
+          stem: "yellow_sweep"
+      - type: "plugin"
+        plugin_name: "scanimage"
+        command_name: "grab"
+      - type: "wait"
+        duration: *grab_settle
+      - type: "controller"
+        command_name: "trialParams"
+        pattern: *pat_yellow
+        pattern_ID: *id_yellow
+        duration: *step_dur
+        mode: 2
+        frame_index: 0
+        frame_rate: *fps
+        gain: 0
+        duty: *duty_a
+      - type: "wait"
+        duration: *step_dur
+  - name: "yellow_d15"
+    commands:
+      - type: "controller"
+        command_name: "trialParams"
+        pattern: *pat_yellow
+        pattern_ID: *id_yellow
+        duration: *step_dur
+        mode: 2
+        frame_index: 0
+        frame_rate: *fps
+        gain: 0
+        duty: *duty_b
+      - type: "wait"
+        duration: *step_dur
+  - name: "yellow_d31"
+    commands:
+      - type: "controller"
+        command_name: "trialParams"
+        pattern: *pat_yellow
+        pattern_ID: *id_yellow
+        duration: *step_dur
+        mode: 2
+        frame_index: 0
+        frame_rate: *fps
+        gain: 0
+        duty: *duty_c
+      - type: "wait"
+        duration: *step_dur
+  - name: "yellow_d63"
+    commands:
+      - type: "controller"
+        command_name: "trialParams"
+        pattern: *pat_yellow
+        pattern_ID: *id_yellow
+        duration: *step_dur
+        mode: 2
+        frame_index: 0
+        frame_rate: *fps
+        gain: 0
+        duty: *duty_d
+      - type: "wait"
+        duration: *step_dur
+  - name: "yellow_d127"
+    commands:
+      - type: "controller"
+        command_name: "trialParams"
+        pattern: *pat_yellow
+        pattern_ID: *id_yellow
+        duration: *step_dur
+        mode: 2
+        frame_index: 0
+        frame_rate: *fps
+        gain: 0
+        duty: *duty_e
+      - type: "wait"
+        duration: *step_dur
+  - name: "yellow_d255"
+    commands:
+      - type: "controller"
+        command_name: "trialParams"
+        pattern: *pat_yellow
+        pattern_ID: *id_yellow
+        duration: *step_dur
+        mode: 2
+        frame_index: 0
+        frame_rate: *fps
+        gain: 0
+        duty: *duty_f
+      - type: "wait"
+        duration: *step_dur
+      - type: "controller"
+        command_name: "allOff"
+      - type: "plugin"
+        plugin_name: "scanimage"
+        command_name: "waitIdle"
+        params:
+          timeout_s: *wait_idle_s
+
+  # Display dark after the last color.
+  - name: "post_blank"
+    commands:
+      - type: "controller"
+        command_name: "allOff"
+      - type: "wait"
+        duration: *blank_dur

From cb909526ef01b6b8d20602aa623f5dddeabf55e0 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Sun, 18 Oct 2026 13:19:28 -0400
Subject: [PATCH 3/3] style: Prettier over the controller-settings JS
 (format-check clean)

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 js/controller-settings.js           | 197 ++++++++++++++---
 js/plugin-registry.js               |  24 +-
 js/protocol-yaml-v3.js              |  61 +++++-
 tests/test-controller-settings.js   | 327 ++++++++++++++++++++++++----
 tests/test-protocol-roundtrip-v3.js |  56 ++++-
 tests/test-studio-runtime-vars.js   |   6 +-
 6 files changed, 565 insertions(+), 106 deletions(-)

diff --git a/js/controller-settings.js b/js/controller-settings.js
index e2209cd5..c329f625 100644
--- a/js/controller-settings.js
+++ b/js/controller-settings.js
@@ -32,7 +32,8 @@
         if (v === undefined || v === null || v === '') return null;
         if (typeof v === 'string') {
             const s = v.trim().toLowerCase();
-            if (Object.prototype.hasOwnProperty.call(PANEL_MODE_ALIASES, s)) return PANEL_MODE_ALIASES[s];
+            if (Object.prototype.hasOwnProperty.call(PANEL_MODE_ALIASES, s))
+                return PANEL_MODE_ALIASES[s];
             if (/^[0-3]$/.test(s)) return Number(s);
             return null;
         }
@@ -79,17 +80,31 @@
         if (raw === undefined || raw === null) return out;
         out.declared = true;
         if (typeof raw !== 'object' || Array.isArray(raw)) {
-            out.errors.push('controller: must be a mapping (panel_mode / refresh_hz / refresh_policy / panel_firmware)');
+            out.errors.push(
+                'controller: must be a mapping (panel_mode / refresh_hz / refresh_policy / panel_firmware)'
+            );
             return out;
         }
         const known = ['panel_mode', 'refresh_hz', 'refresh_policy', 'panel_firmware'];
         for (const k of Object.keys(raw)) {
-            if (!known.includes(k)) out.warnings.push('controller: unknown key "' + k + '" is ignored (known: ' + known.join(', ') + ')');
+            if (!known.includes(k))
+                out.warnings.push(
+                    'controller: unknown key "' +
+                        k +
+                        '" is ignored (known: ' +
+                        known.join(', ') +
+                        ')'
+                );
         }
         if (raw.panel_mode !== undefined && raw.panel_mode !== null) {
             const m = normalizePanelMode(raw.panel_mode);
             if (m === null) {
-                out.errors.push('controller.panel_mode ' + JSON.stringify(raw.panel_mode) + ' is not 0–3 or one of ' + PANEL_MODE_NAMES.join('/'));
+                out.errors.push(
+                    'controller.panel_mode ' +
+                        JSON.stringify(raw.panel_mode) +
+                        ' is not 0–3 or one of ' +
+                        PANEL_MODE_NAMES.join('/')
+                );
             } else {
                 out.panel_mode = m;
             }
@@ -97,7 +112,14 @@
         if (raw.refresh_hz !== undefined && raw.refresh_hz !== null) {
             const hz = Number(raw.refresh_hz);
             if (!Number.isInteger(hz) || hz < REFRESH_HZ_MIN || hz > REFRESH_HZ_MAX) {
-                out.errors.push('controller.refresh_hz ' + JSON.stringify(raw.refresh_hz) + ' must be an integer ' + REFRESH_HZ_MIN + '–' + REFRESH_HZ_MAX);
+                out.errors.push(
+                    'controller.refresh_hz ' +
+                        JSON.stringify(raw.refresh_hz) +
+                        ' must be an integer ' +
+                        REFRESH_HZ_MIN +
+                        '–' +
+                        REFRESH_HZ_MAX
+                );
             } else {
                 out.refresh_hz = hz;
             }
@@ -105,7 +127,12 @@
         if (raw.refresh_policy !== undefined && raw.refresh_policy !== null) {
             const p = String(raw.refresh_policy).trim();
             if (!REFRESH_POLICIES.includes(p)) {
-                out.errors.push('controller.refresh_policy ' + JSON.stringify(raw.refresh_policy) + ' must be one of ' + REFRESH_POLICIES.join('/'));
+                out.errors.push(
+                    'controller.refresh_policy ' +
+                        JSON.stringify(raw.refresh_policy) +
+                        ' must be one of ' +
+                        REFRESH_POLICIES.join('/')
+                );
             } else {
                 out.refresh_policy = p;
             }
@@ -115,7 +142,9 @@
         }
         if (raw.panel_firmware !== undefined && raw.panel_firmware !== null) {
             if (typeof raw.panel_firmware !== 'string' || !raw.panel_firmware.trim()) {
-                out.errors.push('controller.panel_firmware must be a non-empty string (a footer version or its prefix, e.g. "2p")');
+                out.errors.push(
+                    'controller.panel_firmware must be a non-empty string (a footer version or its prefix, e.g. "2p")'
+                );
             } else {
                 out.panel_firmware = raw.panel_firmware.trim();
             }
@@ -139,7 +168,10 @@
      */
     function planAssertions(a) {
         a = a || {};
-        const block = a.block && typeof a.block === 'object' && 'declared' in a.block ? a.block : normalizeControllerBlock(a.block);
+        const block =
+            a.block && typeof a.block === 'object' && 'declared' in a.block
+                ? a.block
+                : normalizeControllerBlock(a.block);
         const rig = a.rig || {};
         const rigDefaults = rig.defaults || {};
         const rigLimits = rig.limits || {};
@@ -159,19 +191,39 @@
 
         // 1. Rig identity — the protocol's rig and the bench's rig must agree.
         if (a.protocolRig && a.sessionRig && a.protocolRig !== a.sessionRig) {
-            problem('protocol is written for rig "' + a.protocolRig + '" but the session rig is "' + a.sessionRig + '"' +
-                (strict ? ' — pick the right rig in the top bar or fix the protocol\'s rig: path' : ''));
+            problem(
+                'protocol is written for rig "' +
+                    a.protocolRig +
+                    '" but the session rig is "' +
+                    a.sessionRig +
+                    '"' +
+                    (strict
+                        ? " — pick the right rig in the top bar or fix the protocol's rig: path"
+                        : '')
+            );
         }
 
         // 2. Panel display mode: protocol wins, else the rig default. Nothing declared → record only.
-        const wantMode = block.panel_mode !== null && block.panel_mode !== undefined ? block.panel_mode : normalizePanelMode(rigDefaults.panel_mode);
+        const wantMode =
+            block.panel_mode !== null && block.panel_mode !== undefined
+                ? block.panel_mode
+                : normalizePanelMode(rigDefaults.panel_mode);
         if (wantMode !== null) {
             intended.panel_mode = wantMode;
             const needCap = PANEL_MODE_CAPABILITY[wantMode];
             if (needCap && caps && !caps.includes(needCap)) {
-                blocking.push('panel mode ' + panelModeName(wantMode) + ' needs controller capability "' + needCap + '", which this controller does not report');
+                blocking.push(
+                    'panel mode ' +
+                        panelModeName(wantMode) +
+                        ' needs controller capability "' +
+                        needCap +
+                        '", which this controller does not report'
+                );
             } else if (snap.panel_mode === null || snap.panel_mode === undefined) {
-                problem('cannot read the panel display mode (GET_PANEL_DISPLAY_MODE 0x1C gave no reply) — wanted ' + panelModeName(wantMode));
+                problem(
+                    'cannot read the panel display mode (GET_PANEL_DISPLAY_MODE 0x1C gave no reply) — wanted ' +
+                        panelModeName(wantMode)
+                );
             } else if (snap.panel_mode !== wantMode) {
                 actions.push({ setting: 'panel_mode', from: snap.panel_mode, to: wantMode });
             }
@@ -179,29 +231,57 @@
 
         // 3. Refresh rate: explicit refresh_hz, else derived (rig cap + pattern grayscale).
         const cap = Number.isInteger(rigLimits.max_refresh_hz) ? rigLimits.max_refresh_hz : null;
-        const gsList = patterns.map((p) => (p && (p.gsVal === 1 || p.gsVal === 2) ? p.gsVal : null));
+        const gsList = patterns.map((p) =>
+            p && (p.gsVal === 1 || p.gsVal === 2) ? p.gsVal : null
+        );
         const gsKnown = gsList.filter((g) => g !== null);
-        intended.pattern_gs = gsKnown.length ? Array.from(new Set(gsKnown)).map((g) => (g === 1 ? 'GS2' : 'GS16')) : null;
+        intended.pattern_gs = gsKnown.length
+            ? Array.from(new Set(gsKnown)).map((g) => (g === 1 ? 'GS2' : 'GS16'))
+            : null;
         if (block.refresh_hz !== null) {
             intended.refresh_hz = block.refresh_hz;
             if (cap !== null && block.refresh_hz > cap) {
-                blocking.push('controller.refresh_hz ' + block.refresh_hz + ' exceeds the rig limit max_refresh_hz ' + cap);
+                blocking.push(
+                    'controller.refresh_hz ' +
+                        block.refresh_hz +
+                        ' exceeds the rig limit max_refresh_hz ' +
+                        cap
+                );
             } else if (snap.refresh_hz === null || snap.refresh_hz === undefined) {
-                problem('cannot read the refresh rate (GET_REFRESH_RATE 0x17 gave no reply) — wanted ' + block.refresh_hz + ' Hz');
+                problem(
+                    'cannot read the refresh rate (GET_REFRESH_RATE 0x17 gave no reply) — wanted ' +
+                        block.refresh_hz +
+                        ' Hz'
+                );
             } else if (snap.refresh_hz !== block.refresh_hz) {
-                actions.push({ setting: 'refresh_hz', from: snap.refresh_hz, to: block.refresh_hz });
+                actions.push({
+                    setting: 'refresh_hz',
+                    from: snap.refresh_hz,
+                    to: block.refresh_hz
+                });
             }
         } else if (block.refresh_policy === 'line_sync_safe' || cap !== null) {
             if (cap === null) {
-                problem('controller.refresh_policy line_sync_safe needs the rig to declare limits.max_refresh_hz — nothing to cap at');
+                problem(
+                    'controller.refresh_policy line_sync_safe needs the rig to declare limits.max_refresh_hz — nothing to cap at'
+                );
             } else {
                 intended.refresh_hz_max = cap;
                 // The firmware default for the referenced patterns' grayscale is what the controller
                 // would stream at if nobody had set the rate; if that (or the current rate) is above the
                 // cap, pin the rate to the cap.
-                const wouldDefault = gsKnown.length ? Math.max.apply(null, gsKnown.map((g) => DEFAULT_REFRESH_HZ[g])) : null;
+                const wouldDefault = gsKnown.length
+                    ? Math.max.apply(
+                          null,
+                          gsKnown.map((g) => DEFAULT_REFRESH_HZ[g])
+                      )
+                    : null;
                 if (snap.refresh_hz === null || snap.refresh_hz === undefined) {
-                    problem('cannot read the refresh rate (GET_REFRESH_RATE 0x17 gave no reply) — rig caps it at ' + cap + ' Hz');
+                    problem(
+                        'cannot read the refresh rate (GET_REFRESH_RATE 0x17 gave no reply) — rig caps it at ' +
+                            cap +
+                            ' Hz'
+                    );
                 } else if (snap.refresh_hz > cap) {
                     actions.push({ setting: 'refresh_hz', from: snap.refresh_hz, to: cap });
                 } else if (wouldDefault !== null && wouldDefault > cap && snap.refresh_hz !== cap) {
@@ -209,26 +289,60 @@
                     actions.push({ setting: 'refresh_hz', from: snap.refresh_hz, to: cap });
                 }
                 if (gsKnown.length !== patterns.length && patterns.length) {
-                    warnings.push('grayscale unknown for ' + (patterns.length - gsKnown.length) + ' referenced pattern(s) — refresh derived from the readable ones only');
+                    warnings.push(
+                        'grayscale unknown for ' +
+                            (patterns.length - gsKnown.length) +
+                            ' referenced pattern(s) — refresh derived from the readable ones only'
+                    );
                 }
             }
         }
 
         // 4. Panel firmware: protocol requirement wins, else the rig's. A declared requirement is hard.
-        const wantFw = block.panel_firmware || (typeof rigRequires.panel_firmware === 'string' ? rigRequires.panel_firmware : null);
+        const wantFw =
+            block.panel_firmware ||
+            (typeof rigRequires.panel_firmware === 'string' ? rigRequires.panel_firmware : null);
         if (wantFw) {
             intended.panel_firmware = wantFw;
-            const ver = snap.panel_firmware && snap.panel_firmware.version ? snap.panel_firmware.version : null;
+            const ver =
+                snap.panel_firmware && snap.panel_firmware.version
+                    ? snap.panel_firmware.version
+                    : null;
             if (!ver) {
-                problem('cannot read the panel firmware footer (GET_FIRMWARE_INFO 0xE3) — required "' + wantFw + '"');
+                problem(
+                    'cannot read the panel firmware footer (GET_FIRMWARE_INFO 0xE3) — required "' +
+                        wantFw +
+                        '"'
+                );
             } else if (!firmwareMatches(ver, wantFw)) {
-                blocking.push('panel firmware on the SD card is "' + ver + '", required "' + wantFw + '" — flash the fleet (Console → Panel firmware) or change the requirement');
+                blocking.push(
+                    'panel firmware on the SD card is "' +
+                        ver +
+                        '", required "' +
+                        wantFw +
+                        '" — flash the fleet (Console → Panel firmware) or change the requirement'
+                );
             }
             const v = snap.verified;
             if (!v) {
-                warnings.push('panels not verified this session — the footer says which image is on the SD card, not which firmware every panel runs; run Verify panels (' + (strict ? 'strongly recommended on this rig' : 'optional') + ')');
+                warnings.push(
+                    'panels not verified this session — the footer says which image is on the SD card, not which firmware every panel runs; run Verify panels (' +
+                        (strict ? 'strongly recommended on this rig' : 'optional') +
+                        ')'
+                );
             } else if (v.ok === false) {
-                blocking.push('panel verify failed: ' + (v.total - v.verified) + ' of ' + v.total + ' panels do not match the SD footer "' + (v.footer || ver || '?') + '"' + (v.mismatched && v.mismatched.length ? ' (panels ' + v.mismatched.join(', ') + ')' : ''));
+                blocking.push(
+                    'panel verify failed: ' +
+                        (v.total - v.verified) +
+                        ' of ' +
+                        v.total +
+                        ' panels do not match the SD footer "' +
+                        (v.footer || ver || '?') +
+                        '"' +
+                        (v.mismatched && v.mismatched.length
+                            ? ' (panels ' + v.mismatched.join(', ') + ')'
+                            : '')
+                );
             }
         }
 
@@ -239,13 +353,30 @@
     function formatSnapshot(s) {
         if (!s) return 'controller: (no snapshot)';
         const parts = [];
-        parts.push('panel mode ' + (s.panel_mode === null || s.panel_mode === undefined ? '?' : panelModeName(s.panel_mode) + ' (' + s.panel_mode + ')'));
-        parts.push('refresh ' + (s.refresh_hz === null || s.refresh_hz === undefined ? '?' : s.refresh_hz + ' Hz'));
+        parts.push(
+            'panel mode ' +
+                (s.panel_mode === null || s.panel_mode === undefined
+                    ? '?'
+                    : panelModeName(s.panel_mode) + ' (' + s.panel_mode + ')')
+        );
+        parts.push(
+            'refresh ' +
+                (s.refresh_hz === null || s.refresh_hz === undefined ? '?' : s.refresh_hz + ' Hz')
+        );
         if (s.spi_mhz !== null && s.spi_mhz !== undefined) parts.push('SPI ' + s.spi_mhz + ' MHz');
-        if (s.dio_roles) parts.push('DIO ' + s.dio_roles.map((d, i) => (i + 1) + '=' + d.role).join(' '));
+        if (s.dio_roles)
+            parts.push('DIO ' + s.dio_roles.map((d, i) => i + 1 + '=' + d.role).join(' '));
         if (s.ao_mv !== null && s.ao_mv !== undefined) parts.push('AO ' + s.ao_mv + ' mV');
-        if (s.panel_firmware && s.panel_firmware.version) parts.push('panel fw «' + s.panel_firmware.version + '»');
-        if (s.verified) parts.push('verified ' + s.verified.verified + '/' + s.verified.total + (s.verified.ok ? '' : ' MISMATCH'));
+        if (s.panel_firmware && s.panel_firmware.version)
+            parts.push('panel fw «' + s.panel_firmware.version + '»');
+        if (s.verified)
+            parts.push(
+                'verified ' +
+                    s.verified.verified +
+                    '/' +
+                    s.verified.total +
+                    (s.verified.ok ? '' : ' MISMATCH')
+            );
         if (s.controller_firmware) parts.push('controller ' + s.controller_firmware);
         return parts.join(' · ');
     }
diff --git a/js/plugin-registry.js b/js/plugin-registry.js
index 1edcf7b1..ecba05ea 100644
--- a/js/plugin-registry.js
+++ b/js/plugin-registry.js
@@ -1232,7 +1232,11 @@ function _rigPanelMode(raw, warnings) {
     var s = String(raw).trim().toLowerCase();
     if (Object.prototype.hasOwnProperty.call(RIG_PANEL_MODES, s)) return RIG_PANEL_MODES[s];
     if (/^[0-3]$/.test(s)) return Number(s);
-    warnings.push('unknown defaults.panel_mode "' + raw + '" — ignored (0–3 or oneshot/persistent/triggered/gated)');
+    warnings.push(
+        'unknown defaults.panel_mode "' +
+            raw +
+            '" — ignored (0–3 or oneshot/persistent/triggered/gated)'
+    );
     return null;
 }
 
@@ -1249,7 +1253,12 @@ function _parseRigSettings(rigData, result) {
         if (l.max_refresh_hz != null) {
             var hz = Number(l.max_refresh_hz);
             if (Number.isInteger(hz) && hz >= 1 && hz <= 2000) result.limits.max_refresh_hz = hz;
-            else result.warnings.push('limits.max_refresh_hz "' + l.max_refresh_hz + '" must be an integer 1–2000 — ignored');
+            else
+                result.warnings.push(
+                    'limits.max_refresh_hz "' +
+                        l.max_refresh_hz +
+                        '" must be an integer 1–2000 — ignored'
+                );
         }
     } else if (l != null) {
         result.warnings.push('limits: must be a mapping — ignored');
@@ -1257,13 +1266,18 @@ function _parseRigSettings(rigData, result) {
     var r = rigData.requires;
     if (r && typeof r === 'object' && !Array.isArray(r)) {
         if (r.panel_firmware != null) {
-            if (typeof r.panel_firmware === 'string' && r.panel_firmware.trim()) result.requires.panel_firmware = r.panel_firmware.trim();
-            else result.warnings.push('requires.panel_firmware must be a non-empty string — ignored');
+            if (typeof r.panel_firmware === 'string' && r.panel_firmware.trim())
+                result.requires.panel_firmware = r.panel_firmware.trim();
+            else
+                result.warnings.push(
+                    'requires.panel_firmware must be a non-empty string — ignored'
+                );
         }
     } else if (r != null) {
         result.warnings.push('requires: must be a mapping — ignored');
     }
-    if (rigData.strict != null) result.strict = rigData.strict === true || String(rigData.strict).toLowerCase() === 'true';
+    if (rigData.strict != null)
+        result.strict = rigData.strict === true || String(rigData.strict).toLowerCase() === 'true';
 }
 
 function parseRigIo(rigData) {
diff --git a/js/protocol-yaml-v3.js b/js/protocol-yaml-v3.js
index 6185d30b..775cc7ba 100644
--- a/js/protocol-yaml-v3.js
+++ b/js/protocol-yaml-v3.js
@@ -310,7 +310,13 @@ function unsupportedRequires(experiment) {
  * Mirrors js/controller-settings.js normalizeControllerBlock (that module is the runtime
  * side and cannot be imported from this ESM module without a bundler).
  */
-const CONTROLLER_PANEL_MODES = Object.freeze({ oneshot: 0, persist: 1, persistent: 1, triggered: 2, gated: 3 });
+const CONTROLLER_PANEL_MODES = Object.freeze({
+    oneshot: 0,
+    persist: 1,
+    persistent: 1,
+    triggered: 2,
+    gated: 3
+});
 const CONTROLLER_REFRESH_POLICIES = Object.freeze(['line_sync_safe']);
 function extractControllerBlock(raw) {
     const out = {
@@ -326,38 +332,70 @@ function extractControllerBlock(raw) {
     if (raw === undefined || raw === null) return out;
     out.declared = true;
     if (typeof raw !== 'object' || Array.isArray(raw)) {
-        out.errors.push('controller: must be a mapping (panel_mode / refresh_hz / refresh_policy / panel_firmware)');
+        out.errors.push(
+            'controller: must be a mapping (panel_mode / refresh_hz / refresh_policy / panel_firmware)'
+        );
         return out;
     }
     out.raw = JSON.parse(JSON.stringify(raw));
     const known = ['panel_mode', 'refresh_hz', 'refresh_policy', 'panel_firmware'];
     for (const k of Object.keys(raw)) {
-        if (!known.includes(k)) out.warnings.push('controller: unknown key "' + k + '" is ignored (known: ' + known.join(', ') + ')');
+        if (!known.includes(k))
+            out.warnings.push(
+                'controller: unknown key "' + k + '" is ignored (known: ' + known.join(', ') + ')'
+            );
     }
     if (raw.panel_mode !== undefined && raw.panel_mode !== null) {
         let m = null;
-        if (typeof raw.panel_mode === 'number' && Number.isInteger(raw.panel_mode) && raw.panel_mode >= 0 && raw.panel_mode <= 3) m = raw.panel_mode;
+        if (
+            typeof raw.panel_mode === 'number' &&
+            Number.isInteger(raw.panel_mode) &&
+            raw.panel_mode >= 0 &&
+            raw.panel_mode <= 3
+        )
+            m = raw.panel_mode;
         else if (typeof raw.panel_mode === 'string') {
             const k = raw.panel_mode.trim().toLowerCase();
-            if (Object.prototype.hasOwnProperty.call(CONTROLLER_PANEL_MODES, k)) m = CONTROLLER_PANEL_MODES[k];
+            if (Object.prototype.hasOwnProperty.call(CONTROLLER_PANEL_MODES, k))
+                m = CONTROLLER_PANEL_MODES[k];
             else if (/^[0-3]$/.test(k)) m = Number(k);
         }
-        if (m === null) out.errors.push('controller.panel_mode ' + JSON.stringify(raw.panel_mode) + ' is not 0–3 or one of oneshot/persistent/triggered/gated');
+        if (m === null)
+            out.errors.push(
+                'controller.panel_mode ' +
+                    JSON.stringify(raw.panel_mode) +
+                    ' is not 0–3 or one of oneshot/persistent/triggered/gated'
+            );
         else out.panel_mode = m;
     }
     if (raw.refresh_hz !== undefined && raw.refresh_hz !== null) {
         const hz = Number(raw.refresh_hz);
-        if (!Number.isInteger(hz) || hz < 1 || hz > 2000) out.errors.push('controller.refresh_hz ' + JSON.stringify(raw.refresh_hz) + ' must be an integer 1–2000');
+        if (!Number.isInteger(hz) || hz < 1 || hz > 2000)
+            out.errors.push(
+                'controller.refresh_hz ' +
+                    JSON.stringify(raw.refresh_hz) +
+                    ' must be an integer 1–2000'
+            );
         else out.refresh_hz = hz;
     }
     if (raw.refresh_policy !== undefined && raw.refresh_policy !== null) {
         const pol = String(raw.refresh_policy).trim();
-        if (!CONTROLLER_REFRESH_POLICIES.includes(pol)) out.errors.push('controller.refresh_policy ' + JSON.stringify(raw.refresh_policy) + ' must be one of ' + CONTROLLER_REFRESH_POLICIES.join('/'));
+        if (!CONTROLLER_REFRESH_POLICIES.includes(pol))
+            out.errors.push(
+                'controller.refresh_policy ' +
+                    JSON.stringify(raw.refresh_policy) +
+                    ' must be one of ' +
+                    CONTROLLER_REFRESH_POLICIES.join('/')
+            );
         else out.refresh_policy = pol;
     }
-    if (out.refresh_hz !== null && out.refresh_policy !== null) out.errors.push('controller: declare refresh_hz OR refresh_policy, not both');
+    if (out.refresh_hz !== null && out.refresh_policy !== null)
+        out.errors.push('controller: declare refresh_hz OR refresh_policy, not both');
     if (raw.panel_firmware !== undefined && raw.panel_firmware !== null) {
-        if (typeof raw.panel_firmware !== 'string' || !raw.panel_firmware.trim()) out.errors.push('controller.panel_firmware must be a non-empty string (a footer version or its prefix, e.g. "2p")');
+        if (typeof raw.panel_firmware !== 'string' || !raw.panel_firmware.trim())
+            out.errors.push(
+                'controller.panel_firmware must be a non-empty string (a footer version or its prefix, e.g. "2p")'
+            );
         else out.panel_firmware = raw.panel_firmware.trim();
     }
     return out;
@@ -629,7 +667,8 @@ function collectBlockingErrors(experiment) {
 
     // controller: block — a malformed declaration blocks (a wrong panel mode ruins data silently).
     if (experiment && experiment.controller && Array.isArray(experiment.controller.errors)) {
-        for (const msg of experiment.controller.errors) errors.push({ kind: 'controller-block', message: msg });
+        for (const msg of experiment.controller.errors)
+            errors.push({ kind: 'controller-block', message: msg });
     }
 
     // The two anchor checks need the CST; skip gracefully when it's absent.
diff --git a/tests/test-controller-settings.js b/tests/test-controller-settings.js
index 158bcefa..1edfe822 100644
--- a/tests/test-controller-settings.js
+++ b/tests/test-controller-settings.js
@@ -44,74 +44,309 @@ checkTrue('empty requirement always matches', CS.firmwareMatches('anything', '')
 checkTrue('no footer never matches a requirement', !CS.firmwareMatches(null, '2p'));
 
 console.log('normalizeControllerBlock');
-const nb = CS.normalizeControllerBlock({ panel_mode: 'triggered', refresh_policy: 'line_sync_safe', panel_firmware: '2p' });
-check('normalized', [nb.declared, nb.panel_mode, nb.refresh_hz, nb.refresh_policy, nb.panel_firmware, nb.errors.length], [true, 2, null, 'line_sync_safe', '2p', 0]);
+const nb = CS.normalizeControllerBlock({
+    panel_mode: 'triggered',
+    refresh_policy: 'line_sync_safe',
+    panel_firmware: '2p'
+});
+check(
+    'normalized',
+    [
+        nb.declared,
+        nb.panel_mode,
+        nb.refresh_hz,
+        nb.refresh_policy,
+        nb.panel_firmware,
+        nb.errors.length
+    ],
+    [true, 2, null, 'line_sync_safe', '2p', 0]
+);
 check('absent → undeclared', CS.normalizeControllerBlock(undefined).declared, false);
 check('bad mode → error', CS.normalizeControllerBlock({ panel_mode: 9 }).errors.length, 1);
-check('hz + policy → error', CS.normalizeControllerBlock({ refresh_hz: 300, refresh_policy: 'line_sync_safe' }).errors.length, 1);
+check(
+    'hz + policy → error',
+    CS.normalizeControllerBlock({ refresh_hz: 300, refresh_policy: 'line_sync_safe' }).errors
+        .length,
+    1
+);
 check('unknown key → warning', CS.normalizeControllerBlock({ foo: 1 }).warnings.length, 1);
 check('list → error', CS.normalizeControllerBlock([1]).errors.length, 1);
 
 console.log('rig YAML settings (parseRigIo)');
 const rig2p = Registry.parseRigIo({
-    name: 'Bergamo', io: { dio: [{ port: 1, role: 'out_debug_framescan' }, { port: 2, role: 'in_trigger' }], ao: { role: 'programmable', default: 0 } },
-    defaults: { panel_mode: 'triggered' }, limits: { max_refresh_hz: 300 }, requires: { panel_firmware: '2p' }, strict: true
-});
-check('rig defaults/limits/requires/strict', [rig2p.name, rig2p.defaults.panel_mode, rig2p.limits.max_refresh_hz, rig2p.requires.panel_firmware, rig2p.strict, rig2p.dio[1].role], ['Bergamo', 2, 300, '2p', true, 'in_trigger']);
-const rigCourse = Registry.parseRigIo({ io: { dio: [{ port: 1, role: 'out_debug_framescan' }] }, defaults: { panel_mode: 'persistent' } });
-check('course rig default persistent, not strict', [rigCourse.defaults.panel_mode, rigCourse.strict, rigCourse.limits.max_refresh_hz], [1, false, null]);
-const rigBad = Registry.parseRigIo({ defaults: { panel_mode: 'fast' }, limits: { max_refresh_hz: 99999 }, requires: { panel_firmware: 5 } });
-check('bad rig values → 3 warnings, all null', [rigBad.warnings.length, rigBad.defaults.panel_mode, rigBad.limits.max_refresh_hz, rigBad.requires.panel_firmware], [3, null, null, null]);
-check('parseRigIo(null) has the new fields', [Registry.parseRigIo(null).defaults.panel_mode, Registry.parseRigIo(null).strict], [null, false]);
+    name: 'Bergamo',
+    io: {
+        dio: [
+            { port: 1, role: 'out_debug_framescan' },
+            { port: 2, role: 'in_trigger' }
+        ],
+        ao: { role: 'programmable', default: 0 }
+    },
+    defaults: { panel_mode: 'triggered' },
+    limits: { max_refresh_hz: 300 },
+    requires: { panel_firmware: '2p' },
+    strict: true
+});
+check(
+    'rig defaults/limits/requires/strict',
+    [
+        rig2p.name,
+        rig2p.defaults.panel_mode,
+        rig2p.limits.max_refresh_hz,
+        rig2p.requires.panel_firmware,
+        rig2p.strict,
+        rig2p.dio[1].role
+    ],
+    ['Bergamo', 2, 300, '2p', true, 'in_trigger']
+);
+const rigCourse = Registry.parseRigIo({
+    io: { dio: [{ port: 1, role: 'out_debug_framescan' }] },
+    defaults: { panel_mode: 'persistent' }
+});
+check(
+    'course rig default persistent, not strict',
+    [rigCourse.defaults.panel_mode, rigCourse.strict, rigCourse.limits.max_refresh_hz],
+    [1, false, null]
+);
+const rigBad = Registry.parseRigIo({
+    defaults: { panel_mode: 'fast' },
+    limits: { max_refresh_hz: 99999 },
+    requires: { panel_firmware: 5 }
+});
+check(
+    'bad rig values → 3 warnings, all null',
+    [
+        rigBad.warnings.length,
+        rigBad.defaults.panel_mode,
+        rigBad.limits.max_refresh_hz,
+        rigBad.requires.panel_firmware
+    ],
+    [3, null, null, null]
+);
+check(
+    'parseRigIo(null) has the new fields',
+    [Registry.parseRigIo(null).defaults.panel_mode, Registry.parseRigIo(null).strict],
+    [null, false]
+);
 
 console.log('planAssertions — 2P protocol on the 2P rig');
-const block2p = CS.normalizeControllerBlock({ panel_mode: 2, refresh_policy: 'line_sync_safe', panel_firmware: '2p' });
-const snapOk = { panel_mode: 1, refresh_hz: 300, capabilities: ['g6_mode', 'v3_triggered', 'v3_gated', 'io_ext'], panel_firmware: { version: '2p-9014b5bb-d' }, verified: { ok: true, verified: 20, total: 20, at: 't' } };
-let plan = CS.planAssertions({ block: block2p, rig: rig2p, snapshot: snapOk, patterns: [{ name: 'a', gsVal: 2 }], protocolRig: 'bergamo_g6_2x10_2p', sessionRig: 'bergamo_g6_2x10_2p' });
-check('ok, strict, one action: mode 1→2', [plan.ok, plan.strict, plan.actions], [true, true, [{ setting: 'panel_mode', from: 1, to: 2 }]]);
-check('intended recorded', [plan.intended.panel_mode, plan.intended.refresh_hz_max, plan.intended.panel_firmware, plan.intended.pattern_gs], [2, 300, '2p', ['GS16']]);
+const block2p = CS.normalizeControllerBlock({
+    panel_mode: 2,
+    refresh_policy: 'line_sync_safe',
+    panel_firmware: '2p'
+});
+const snapOk = {
+    panel_mode: 1,
+    refresh_hz: 300,
+    capabilities: ['g6_mode', 'v3_triggered', 'v3_gated', 'io_ext'],
+    panel_firmware: { version: '2p-9014b5bb-d' },
+    verified: { ok: true, verified: 20, total: 20, at: 't' }
+};
+let plan = CS.planAssertions({
+    block: block2p,
+    rig: rig2p,
+    snapshot: snapOk,
+    patterns: [{ name: 'a', gsVal: 2 }],
+    protocolRig: 'bergamo_g6_2x10_2p',
+    sessionRig: 'bergamo_g6_2x10_2p'
+});
+check(
+    'ok, strict, one action: mode 1→2',
+    [plan.ok, plan.strict, plan.actions],
+    [true, true, [{ setting: 'panel_mode', from: 1, to: 2 }]]
+);
+check(
+    'intended recorded',
+    [
+        plan.intended.panel_mode,
+        plan.intended.refresh_hz_max,
+        plan.intended.panel_firmware,
+        plan.intended.pattern_gs
+    ],
+    [2, 300, '2p', ['GS16']]
+);
 check('no warnings', plan.warnings, []);
 
 console.log('planAssertions — refresh derivation');
-plan = CS.planAssertions({ block: block2p, rig: rig2p, snapshot: Object.assign({}, snapOk, { panel_mode: 2, refresh_hz: 1000 }), patterns: [{ name: 'a', gsVal: 2 }] });
-check('refresh above cap → set to cap', plan.actions, [{ setting: 'refresh_hz', from: 1000, to: 300 }]);
-plan = CS.planAssertions({ block: block2p, rig: rig2p, snapshot: Object.assign({}, snapOk, { panel_mode: 2, refresh_hz: 250 }), patterns: [{ name: 'gs2', gsVal: 1 }] });
-check('GS2 pattern (default 1000) on capped rig → pin to cap', plan.actions, [{ setting: 'refresh_hz', from: 250, to: 300 }]);
-plan = CS.planAssertions({ block: block2p, rig: rig2p, snapshot: Object.assign({}, snapOk, { panel_mode: 2, refresh_hz: 300 }), patterns: [{ name: 'a', gsVal: null }] });
-check('unknown grayscale → warning, no action', [plan.actions.length, plan.warnings.length], [0, 1]);
+plan = CS.planAssertions({
+    block: block2p,
+    rig: rig2p,
+    snapshot: Object.assign({}, snapOk, { panel_mode: 2, refresh_hz: 1000 }),
+    patterns: [{ name: 'a', gsVal: 2 }]
+});
+check('refresh above cap → set to cap', plan.actions, [
+    { setting: 'refresh_hz', from: 1000, to: 300 }
+]);
+plan = CS.planAssertions({
+    block: block2p,
+    rig: rig2p,
+    snapshot: Object.assign({}, snapOk, { panel_mode: 2, refresh_hz: 250 }),
+    patterns: [{ name: 'gs2', gsVal: 1 }]
+});
+check('GS2 pattern (default 1000) on capped rig → pin to cap', plan.actions, [
+    { setting: 'refresh_hz', from: 250, to: 300 }
+]);
+plan = CS.planAssertions({
+    block: block2p,
+    rig: rig2p,
+    snapshot: Object.assign({}, snapOk, { panel_mode: 2, refresh_hz: 300 }),
+    patterns: [{ name: 'a', gsVal: null }]
+});
+check(
+    'unknown grayscale → warning, no action',
+    [plan.actions.length, plan.warnings.length],
+    [0, 1]
+);
 const blockHz = CS.normalizeControllerBlock({ panel_mode: 2, refresh_hz: 500 });
 plan = CS.planAssertions({ block: blockHz, rig: rig2p, snapshot: snapOk, patterns: [] });
 check('explicit refresh_hz above rig cap → blocking', plan.ok, false);
-plan = CS.planAssertions({ block: CS.normalizeControllerBlock({ refresh_hz: 200 }), rig: rigCourse, snapshot: Object.assign({}, snapOk, { refresh_hz: 300 }), patterns: [] });
-check('explicit refresh_hz on an uncapped rig → set', plan.actions, [{ setting: 'refresh_hz', from: 300, to: 200 }]);
+plan = CS.planAssertions({
+    block: CS.normalizeControllerBlock({ refresh_hz: 200 }),
+    rig: rigCourse,
+    snapshot: Object.assign({}, snapOk, { refresh_hz: 300 }),
+    patterns: []
+});
+check('explicit refresh_hz on an uncapped rig → set', plan.actions, [
+    { setting: 'refresh_hz', from: 300, to: 200 }
+]);
 
 console.log('planAssertions — course protocol inherits the rig default');
-plan = CS.planAssertions({ block: undefined, rig: rigCourse, snapshot: Object.assign({}, snapOk, { panel_mode: 2 }), patterns: [] });
-check('bench left in triggered → set back to persistent, not strict', [plan.ok, plan.strict, plan.actions], [true, false, [{ setting: 'panel_mode', from: 2, to: 1 }]]);
-plan = CS.planAssertions({ block: undefined, rig: Registry.parseRigIo({}), snapshot: snapOk, patterns: [] });
-check('nothing declared anywhere → record only', [plan.ok, plan.actions.length, Object.keys(plan.intended).filter((k) => plan.intended[k] != null).length], [true, 0, 0]);
+plan = CS.planAssertions({
+    block: undefined,
+    rig: rigCourse,
+    snapshot: Object.assign({}, snapOk, { panel_mode: 2 }),
+    patterns: []
+});
+check(
+    'bench left in triggered → set back to persistent, not strict',
+    [plan.ok, plan.strict, plan.actions],
+    [true, false, [{ setting: 'panel_mode', from: 2, to: 1 }]]
+);
+plan = CS.planAssertions({
+    block: undefined,
+    rig: Registry.parseRigIo({}),
+    snapshot: snapOk,
+    patterns: []
+});
+check(
+    'nothing declared anywhere → record only',
+    [
+        plan.ok,
+        plan.actions.length,
+        Object.keys(plan.intended).filter((k) => plan.intended[k] != null).length
+    ],
+    [true, 0, 0]
+);
 
 console.log('planAssertions — what refuses');
-plan = CS.planAssertions({ block: block2p, rig: rigCourse, snapshot: snapOk, patterns: [], protocolRig: 'bergamo_g6_2x10_2p', sessionRig: 'cshl_g6_2x10' });
-checkTrue('2P protocol on a course rig → rig mismatch blocks (protocol block makes it strict)', !plan.ok && plan.blocking.some((b) => /rig/.test(b)), plan.blocking.join(' | '));
-plan = CS.planAssertions({ block: block2p, rig: rig2p, snapshot: Object.assign({}, snapOk, { panel_firmware: { version: 'panel-fw-v1.2.0' } }), patterns: [] });
-checkTrue('wrong panel firmware → blocks', !plan.ok && plan.blocking.some((b) => /firmware/.test(b)), plan.blocking.join(' | '));
-plan = CS.planAssertions({ block: block2p, rig: rig2p, snapshot: Object.assign({}, snapOk, { verified: { ok: false, verified: 18, total: 20, mismatched: [7, 12] } }), patterns: [] });
-checkTrue('failed fleet verify → blocks and names the panels', !plan.ok && plan.blocking.some((b) => /panels 7, 12/.test(b)), plan.blocking.join(' | '));
-plan = CS.planAssertions({ block: block2p, rig: rig2p, snapshot: Object.assign({}, snapOk, { verified: null }), patterns: [] });
-checkTrue('unverified fleet → warning, not blocking', plan.ok && plan.warnings.some((w) => /not verified/.test(w)), plan.warnings.join(' | '));
-plan = CS.planAssertions({ block: block2p, rig: rig2p, snapshot: Object.assign({}, snapOk, { capabilities: ['g6_mode'] }), patterns: [] });
-checkTrue('mode 2 without v3_triggered capability → blocks', !plan.ok && plan.blocking.some((b) => /v3_triggered/.test(b)), plan.blocking.join(' | '));
-plan = CS.planAssertions({ block: block2p, rig: rig2p, snapshot: Object.assign({}, snapOk, { panel_mode: null }), patterns: [] });
-checkTrue('unreadable mode on a strict rig → blocks', !plan.ok && plan.blocking.some((b) => /cannot read the panel display mode/.test(b)), plan.blocking.join(' | '));
-plan = CS.planAssertions({ block: undefined, rig: rigCourse, snapshot: Object.assign({}, snapOk, { panel_mode: null }), patterns: [] });
-checkTrue('unreadable mode on a course rig → warning only', plan.ok && plan.warnings.length === 1, plan.warnings.join(' | '));
-plan = CS.planAssertions({ block: CS.normalizeControllerBlock({ panel_mode: 'nope' }), rig: rigCourse, snapshot: snapOk, patterns: [] });
+plan = CS.planAssertions({
+    block: block2p,
+    rig: rigCourse,
+    snapshot: snapOk,
+    patterns: [],
+    protocolRig: 'bergamo_g6_2x10_2p',
+    sessionRig: 'cshl_g6_2x10'
+});
+checkTrue(
+    '2P protocol on a course rig → rig mismatch blocks (protocol block makes it strict)',
+    !plan.ok && plan.blocking.some((b) => /rig/.test(b)),
+    plan.blocking.join(' | ')
+);
+plan = CS.planAssertions({
+    block: block2p,
+    rig: rig2p,
+    snapshot: Object.assign({}, snapOk, { panel_firmware: { version: 'panel-fw-v1.2.0' } }),
+    patterns: []
+});
+checkTrue(
+    'wrong panel firmware → blocks',
+    !plan.ok && plan.blocking.some((b) => /firmware/.test(b)),
+    plan.blocking.join(' | ')
+);
+plan = CS.planAssertions({
+    block: block2p,
+    rig: rig2p,
+    snapshot: Object.assign({}, snapOk, {
+        verified: { ok: false, verified: 18, total: 20, mismatched: [7, 12] }
+    }),
+    patterns: []
+});
+checkTrue(
+    'failed fleet verify → blocks and names the panels',
+    !plan.ok && plan.blocking.some((b) => /panels 7, 12/.test(b)),
+    plan.blocking.join(' | ')
+);
+plan = CS.planAssertions({
+    block: block2p,
+    rig: rig2p,
+    snapshot: Object.assign({}, snapOk, { verified: null }),
+    patterns: []
+});
+checkTrue(
+    'unverified fleet → warning, not blocking',
+    plan.ok && plan.warnings.some((w) => /not verified/.test(w)),
+    plan.warnings.join(' | ')
+);
+plan = CS.planAssertions({
+    block: block2p,
+    rig: rig2p,
+    snapshot: Object.assign({}, snapOk, { capabilities: ['g6_mode'] }),
+    patterns: []
+});
+checkTrue(
+    'mode 2 without v3_triggered capability → blocks',
+    !plan.ok && plan.blocking.some((b) => /v3_triggered/.test(b)),
+    plan.blocking.join(' | ')
+);
+plan = CS.planAssertions({
+    block: block2p,
+    rig: rig2p,
+    snapshot: Object.assign({}, snapOk, { panel_mode: null }),
+    patterns: []
+});
+checkTrue(
+    'unreadable mode on a strict rig → blocks',
+    !plan.ok && plan.blocking.some((b) => /cannot read the panel display mode/.test(b)),
+    plan.blocking.join(' | ')
+);
+plan = CS.planAssertions({
+    block: undefined,
+    rig: rigCourse,
+    snapshot: Object.assign({}, snapOk, { panel_mode: null }),
+    patterns: []
+});
+checkTrue(
+    'unreadable mode on a course rig → warning only',
+    plan.ok && plan.warnings.length === 1,
+    plan.warnings.join(' | ')
+);
+plan = CS.planAssertions({
+    block: CS.normalizeControllerBlock({ panel_mode: 'nope' }),
+    rig: rigCourse,
+    snapshot: snapOk,
+    patterns: []
+});
 check('block errors are blocking', plan.ok, false);
 
 console.log('formatSnapshot');
-const line = CS.formatSnapshot(Object.assign({}, snapOk, { spi_mhz: 20, ao_mv: 0, dio_roles: [{ port: 1, role: 'out_debug_framescan' }, { port: 2, role: 'in_trigger' }], controller_firmware: 'v3' }));
-checkTrue('one line names mode, refresh, DIO roles, firmware', /persistent.*300 Hz.*SPI 20.*1=out_debug_framescan 2=in_trigger.*2p-9014b5bb-d.*verified 20\/20/.test(line), line);
+const line = CS.formatSnapshot(
+    Object.assign({}, snapOk, {
+        spi_mhz: 20,
+        ao_mv: 0,
+        dio_roles: [
+            { port: 1, role: 'out_debug_framescan' },
+            { port: 2, role: 'in_trigger' }
+        ],
+        controller_firmware: 'v3'
+    })
+);
+checkTrue(
+    'one line names mode, refresh, DIO roles, firmware',
+    /persistent.*300 Hz.*SPI 20.*1=out_debug_framescan 2=in_trigger.*2p-9014b5bb-d.*verified 20\/20/.test(
+        line
+    ),
+    line
+);
 
 console.log(`\n${checks - failures}/${checks} checks passed`);
 process.exit(failures ? 1 : 0);
diff --git a/tests/test-protocol-roundtrip-v3.js b/tests/test-protocol-roundtrip-v3.js
index 5095aad4..ff0f5341 100644
--- a/tests/test-protocol-roundtrip-v3.js
+++ b/tests/test-protocol-roundtrip-v3.js
@@ -4783,12 +4783,30 @@ console.log('\n--- Suite 39: controller: block ---');
     check('controller: refresh_hz absent → null', exp.controller.refresh_hz, null);
     check('controller: panel_firmware', exp.controller.panel_firmware, '2p');
     check('controller: no errors', exp.controller.errors.length, 0);
-    check('controller: not an unknown top-level key', Object.keys(exp._unknownTopLevel || {}).includes('controller'), false);
-    check('requires: controller_block is a web-runner capability', unsupportedRequires(exp).length, 0);
-    check('controller: fixture has no blocking errors', collectBlockingErrors(exp).errors.length, 0);
-    checkTrue('controller: fixture has no export warnings', collectExportWarnings(exp).warnings.length === 0);
+    check(
+        'controller: not an unknown top-level key',
+        Object.keys(exp._unknownTopLevel || {}).includes('controller'),
+        false
+    );
+    check(
+        'requires: controller_block is a web-runner capability',
+        unsupportedRequires(exp).length,
+        0
+    );
+    check(
+        'controller: fixture has no blocking errors',
+        collectBlockingErrors(exp).errors.length,
+        0
+    );
+    checkTrue(
+        'controller: fixture has no export warnings',
+        collectExportWarnings(exp).warnings.length === 0
+    );
     const regen = generateV3Protocol(exp);
-    checkTrue('controller: block survives regen', /controller:\s*\n\s+panel_mode: triggered/.test(regen));
+    checkTrue(
+        'controller: block survives regen',
+        /controller:\s*\n\s+panel_mode: triggered/.test(regen)
+    );
     const again = parseV3Protocol(regen);
     check('controller: round-trip stable', again.controller.panel_mode, 2);
 }
@@ -4796,19 +4814,37 @@ console.log('\n--- Suite 39: controller: block ---');
     // absent block → undeclared, no warnings
     const exp = parseV3Protocol(readFixture('v3_canonical_a.yaml'));
     check('controller: absent → declared false', exp.controller.declared, false);
-    checkTrue('controller: absent adds no warnings', !collectExportWarnings(exp).warnings.some((w) => /controller/.test(w.kind)));
+    checkTrue(
+        'controller: absent adds no warnings',
+        !collectExportWarnings(exp).warnings.some((w) => /controller/.test(w.kind))
+    );
 }
 {
     // malformed values block; a block without the capability token warns
     const bad = readFixture('v3_controller_block.yaml')
         .replace('panel_mode: triggered', 'panel_mode: warp')
-        .replace('refresh_policy: line_sync_safe', 'refresh_policy: line_sync_safe\n  refresh_hz: 300')
+        .replace(
+            'refresh_policy: line_sync_safe',
+            'refresh_policy: line_sync_safe\n  refresh_hz: 300'
+        )
         .replace('requires: [controller_block]', '');
     const exp = parseV3Protocol(bad);
     check('controller: bad mode + hz&policy → 2 errors', exp.controller.errors.length, 2);
-    check('controller: errors are blocking', collectBlockingErrors(exp).errors.filter((e) => e.kind === 'controller-block').length, 2);
-    checkTrue('controller: missing requires token → warning', collectExportWarnings(exp).warnings.some((w) => w.kind === 'controller-block-unrequired'));
-    const listy = parseV3Protocol(readFixture('v3_controller_block.yaml').replace(/controller:\n(  .*\n)+/, 'controller: [2]\n'));
+    check(
+        'controller: errors are blocking',
+        collectBlockingErrors(exp).errors.filter((e) => e.kind === 'controller-block').length,
+        2
+    );
+    checkTrue(
+        'controller: missing requires token → warning',
+        collectExportWarnings(exp).warnings.some((w) => w.kind === 'controller-block-unrequired')
+    );
+    const listy = parseV3Protocol(
+        readFixture('v3_controller_block.yaml').replace(
+            /controller:\n(  .*\n)+/,
+            'controller: [2]\n'
+        )
+    );
     check('controller: a list is an error', listy.controller.errors.length, 1);
 }
 
diff --git a/tests/test-studio-runtime-vars.js b/tests/test-studio-runtime-vars.js
index 2755ba1e..9353aa5b 100644
--- a/tests/test-studio-runtime-vars.js
+++ b/tests/test-studio-runtime-vars.js
@@ -132,7 +132,11 @@ checkBool(
     'collectExportWarnings flags it (soft: editing stays possible)',
     !!warn && /refuse to run/.test(warn.message)
 );
-check('WEB_RUNNER_CAPABILITIES is exported (controller_block since v0.88)', v3.WEB_RUNNER_CAPABILITIES, ['controller_block']);
+check(
+    'WEB_RUNNER_CAPABILITIES is exported (controller_block since v0.88)',
+    v3.WEB_RUNNER_CAPABILITIES,
+    ['controller_block']
+);
 checkBool('requires survives regeneration', /requires:/.test(v3.generateV3Protocol(reqExp)));
 
 console.log('\n=== opto protocol end to end through runtime-controls.js ===');