One undo-block opener for the whole tree: fourteen sites route through it, and the reclaim span can no longer swallow a user's act

The drain refuses a tick inside a foreign block; applyMode wakes the reclaimer
before it opens the span.

CLAUDE.md

@@ -6,7 +6,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 **ReaSampler** is a per-project audio sample-bank capture tool that builds two artifacts: the REAPER extension (`reaper_reasampler`) and **ReaSampler 9000**, a Windows-only VST3 sampler instrument (`reasampler_9000.vst3`, `core/instrument/` + `shell/instrument/`, second CMake target `reasampler_vst`, gated on the vendored `vendor/vst3sdk` submodule slice). The pure-testable-core / REAPER-facing-shell discipline is preserved throughout: `core/` never includes REAPER or VST3 SDK types, `shell/` is where those hosts are actually touched, `app/` is the extension entry point. Every REAPER API name cited in project docs is correct-by-intent; verify argument order, types, and flag values against `vendor/reaper-sdk/sdk/reaper_plugin_functions.h` before use.
 
-Per-module detail — what each file owns, its invariants — lives in the twenty-seven per-directory `src/**/CLAUDE.md` files; see the compact map in "Architecture: the load-bearing split" below to find the right one. Landed-phase history lives in `docs/ARCHIVE.md`; current work lives in `docs/COMPLETED.md`, `docs/TODO.md`, and `docs/TODO-1.0.md` — see "Project docs" below.
+Per-module detail — what each file owns, its invariants — lives in the twenty-eight per-directory `src/**/CLAUDE.md` files; see the compact map in "Architecture: the load-bearing split" below to find the right one. Landed-phase history lives in `docs/ARCHIVE.md`; current work lives in `docs/COMPLETED.md`, `docs/TODO.md`, and `docs/TODO-1.0.md` — see "Project docs" below.
 
 ## Settled decisions
 
@@ -84,7 +84,7 @@ There is no hot-reload. Copy the **Release** build's binary (`build/Release/` on
 
 ## Architecture: the load-bearing split
 
-`core/` holds pure, unit-testable logic — no REAPER or VST3 SDK types, each with a corresponding `<module>_tests` target that runs without a DAW. `shell/` holds the REAPER/host-facing shells — where those SDK types are actually touched. `app/` is the extension entry point. Each of the twenty-seven directories below carries its own `CLAUDE.md` with the full module list and that area's invariants — open the relevant one for detail; this file states only repo-wide truth.
+`core/` holds pure, unit-testable logic — no REAPER or VST3 SDK types, each with a corresponding `<module>_tests` target that runs without a DAW. `shell/` holds the REAPER/host-facing shells — where those SDK types are actually touched. `app/` is the extension entry point. Each of the twenty-eight directories below carries its own `CLAUDE.md` with the full module list and that area's invariants — open the relevant one for detail; this file states only repo-wide truth.
 
 | Directory | Scope |
 |---|---|
@@ -114,6 +114,7 @@ There is no hot-reload. Copy the **Release** build's binary (`build/Release/` on
 | `src/shell/package/` | package filesystem I/O (streaming atomic read/write, exclusive-create landing), the rollback journal, and the REAPER file pickers |
 | `src/shell/panel/` | the docked bank-panel shell + the shared LICE draw kit |
 | `src/shell/persist/` | project ext-state persistence, prune filesystem I/O, usage scan |
+| `src/shell/undo/` | the one REAPER undo-block opener every extension block goes through |
 | `src/shell/view/` | Design View mode application shell |
 
 ## Directory and namespace layout

src/app/CMakeLists.txt

@@ -38,6 +38,7 @@ add_library(reaper_reasampler MODULE
     ${REASAMPLER_SRC_DIR}/shell/panel/draw_kit.cpp
     ${LICE_SRC}
     ${REASAMPLER_SRC_DIR}/shell/capture/insert.cpp
+    ${REASAMPLER_SRC_DIR}/shell/undo/undo_block.cpp
     ${REASAMPLER_SRC_DIR}/shell/view/view.cpp
     ${REASAMPLER_SRC_DIR}/shell/view/fx_reclaim.cpp
     ${REASAMPLER_SRC_DIR}/shell/view/view_lanes.cpp

src/shell/actions/CLAUDE.md

@@ -29,9 +29,13 @@ is owned by other directories and only skinned here.
   separation is load-bearing here same as everywhere else. Only the arrange-capture
   surface writes the `assignment_request` wire; Media-Explorer import and file-drop
   onto the bank panel do not, and neither affects a live instance's selection.
-- **Every bank index verb wraps its mutation in a batched REAPER undo point**
+- **Every undo block in this directory is opened through `shell/undo`'s
-  (`Undo_BeginBlock2`/`EndBlock2`, `UNDO_STATE_MISCCFG`) so one bank operation is
+  `UndoBlock`**, never `Undo_BeginBlock2` directly — the ingest surfaces, the two
-  one Ctrl-Z.
+  drop shells and the Design View membership actions alike. That is what keeps a
+  user's act its own correctly-labelled Ctrl-Z while a Design View mode switch's FX
+  reclaim span is open; the mechanism and its compile-time enforcement are
+  `src/shell/undo/CLAUDE.md`'s. Bank index verbs additionally stay one batched
+  `UNDO_STATE_MISCCFG` point apiece, so one bank operation is one Ctrl-Z.
 - **The prune action is the ONLY file-deletion action in the system**; it opens no
   undo point (file deletion is not REAPER-undoable). It halts on
   `blockedByTracking` and prints whichever blockers fired — the malformed ledger,
@@ -39,7 +43,7 @@ is owned by other directories and only skinned here.
 
 ## Modules
 
-- `shell/actions` (`action_registry` / `design_view_actions` / `bank_actions` / `prune_action`) — the bindable action families, all routed via the `command_id`/`gaccel`/`hookcommand` contract. `action_registry` owns the shared registration plumbing (interned channel-qualified id strings; register and mirror-unregister present the identical pointer) **and the Q-W6 registration TABLE**: `main.cpp`'s own family (capture scopes, panel toggle, insert, batch, realtime, recapture, version) is one `ActionTableRow` array — suffix, phrase, flat function-pointer handler — that registration, hookcommand dispatch, and the unload mirror-unregister all iterate, so adding an action touches the table only (OCP). Bank mutations flow through the promptless `shell/bank_ops` verbs (`bankOp*` + `persistBankOp`, taking `ReaSamplerSession&`), which the panel menus and `bank_actions` consume as thin UX skins. **Every bank index verb wraps its mutation in a batched REAPER undo point (`Undo_BeginBlock2`/`EndBlock2`, `UNDO_STATE_MISCCFG`) so one bank operation is one Ctrl-Z.** The prune action (`prune_action`, `BANK_PRUNE_FOLDER`) is **the ONLY file-deletion action in the system**; it opens no undo point (file deletion is not REAPER-undoable). `BANK_PRUNE_FOLDER` halts on `blockedByTracking` and prints each blocker that fired, with recovery instructions.
+- `shell/actions` (`action_registry` / `design_view_actions` / `bank_actions` / `prune_action`) — the bindable action families, all routed via the `command_id`/`gaccel`/`hookcommand` contract. `action_registry` owns the shared registration plumbing (interned channel-qualified id strings; register and mirror-unregister present the identical pointer) **and the Q-W6 registration TABLE**: `main.cpp`'s own family (capture scopes, panel toggle, insert, batch, realtime, recapture, version) is one `ActionTableRow` array — suffix, phrase, flat function-pointer handler — that registration, hookcommand dispatch, and the unload mirror-unregister all iterate, so adding an action touches the table only (OCP). Bank mutations flow through the promptless `shell/bank_ops` verbs (`bankOp*` + `persistBankOp`, taking `ReaSamplerSession&`), which the panel menus and `bank_actions` consume as thin UX skins; `src/shell/bank_ops/CLAUDE.md` owns the one-op-one-Ctrl-Z rule those verbs enforce. The prune action (`prune_action`, `BANK_PRUNE_FOLDER`) is **the ONLY file-deletion action in the system**; it opens no undo point (file deletion is not REAPER-undoable). `BANK_PRUNE_FOLDER` halts on `blockedByTracking` and prints each blocker that fired, with recovery instructions.
 - `package_export_action` — the "export bank as package" skin: survey and report first, confirm what is absent (and, separately, a destination being replaced), pick a destination, write. Every prompt in the flow lives here so `shell/package/export_bank` stays promptless. Read-only against the project — it holds the session by `const&`, so no ext-state write, generation bump or undo point is reachable. Registration rides `main.cpp`'s action table (`EXPORT_BANK_PACKAGE`); the panel's tab menu is the second skin over the same body.
 - `drag_out_win` — the host/OS boundary of drag-out: Windows OLE `DoDragDrop`/`CF_HDROP`, copy-only (`DROPEFFECT_MOVE` not offered); macOS/Linux via `SWELL_InitiateDragDropOfFileList`. Also owns `pointerOverHostWindow`, the window-ownership test behind `ui::DropContext::pointerOffHost` (`core/ui/CLAUDE.md` owns the hand-off rule it feeds) — process identity on Windows (`WindowFromPoint` + `GetWindowThreadProcessId`), non-null `WindowFromPoint` under SWELL, whose window list is already this-process-only. Its shipped exception: a plugin bridged into `reaper_host*.exe` reports off-host though the pointer never left REAPER.
 - `instrument_drop_win` — instrument-drop shell: `probeDropTarget` resolves a screen point to a track + a `ReaperSurface` (via the pure `wire::classifyReaperSurface`, whose token rules `core/wire/CLAUDE.md` owns) — it answers only what REAPER named, never whether the pointer is still in REAPER — and the drop half adds a ReaSampler 9000 instance and applies the dragged capture's state via a transient `.vstpreset` + `TrackFX_SetPreset` (the former `TrackFX_SetNamedConfigParm` "vst_chunk" write was silently unappliable for VST3). Exposes `loadInstrumentOntoTrack` (inner half, no own undo block) and `performInstrumentDrop` (wraps in its own undo block). **Never captures, never writes the bank, never inserts a timeline item.**

src/shell/actions/arrange_drop_win.cpp

@@ -29,6 +29,7 @@
 #include <vector>
 
 #include "core/capture/insert_plan.h"  // computeInsertMode — the ONE InsertMedia bitfield owner
+#include "shell/undo/undo_block.h"     // the ONE undo-block opener
 
 #include "reaper_plugin.h"
 
@@ -42,8 +43,6 @@
 #define REAPERAPI_WANT_SetOnlyTrackSelected
 #define REAPERAPI_WANT_SetTrackSelected
 #define REAPERAPI_WANT_SnapToGrid
-#define REAPERAPI_WANT_Undo_BeginBlock2
-#define REAPERAPI_WANT_Undo_EndBlock2
 #include "reaper_plugin_functions.h"
 
 namespace reasampler {
@@ -98,7 +97,7 @@ int performArrangeDrop(MediaTrack* track, double time,
 
     // One undo block around the whole drop (every item plus the selection/cursor restore) so a
     // single Ctrl-Z returns the project to exactly its pre-drop state.
-    Undo_BeginBlock2(nullptr);
+    UndoBlock undo(nullptr);
 
     SetOnlyTrackSelected(track);
     SetEditCurPos(SnapToGrid(nullptr, time), /*moveview=*/false, /*seekplay=*/false);
@@ -111,9 +110,6 @@ int performArrangeDrop(MediaTrack* track, double time,
         if (InsertMedia(path.c_str(), mode) != 0) ++inserted;
     }
 
-    // A fixed stack buffer, not std::string concatenation: the prior shape built the label with
-    // std::to_string + `+` between the restore below and Undo_EndBlock2, so a bad_alloc there
-    // would leave an unbalanced undo block open. snprintf here removes the allocation outright.
     char label[64];
     std::snprintf(label, sizeof(label), "ReaSampler: drop %d %s onto arrange", inserted,
                  inserted == 1 ? "capture" : "captures");
@@ -122,7 +118,7 @@ int performArrangeDrop(MediaTrack* track, double time,
     SetEditCurPos(priorCursor, /*moveview=*/false, /*seekplay=*/false);
 
     // extraflags -1 = UNDO_STATE_ALL, matching the insert action's own block.
-    Undo_EndBlock2(nullptr, label, -1);
+    undo.recordPoint(label, -1);
     return inserted;
 }
 

src/shell/actions/design_view_actions.cpp

@@ -25,7 +25,7 @@
 #include "shell/capture/item_read.h"     // shared MediaItem* -> GUID + fixed-lane-name reads (D2 W3-B)
 #include "shell/capture/track_guid.h"    // shared MediaTrack* -> canonical GUID key
 #include "shell/panel/panel_window.h"    // bankPanelInvalidate — footer toggle repaint
-#include "shell/view/fx_reclaim.h"       // fxReclaimEndUndoSpan — no block opens over the span
+#include "shell/undo/undo_block.h"       // the ONE undo-block opener
 #include "shell/view/view.h"             // applyMode (D2 shell)
 #include "shell/view/view_lanes.h"       // mintManagedLanes
 #include "shell/view/view_park.h"        // kViewUndoMask
@@ -41,8 +41,6 @@
 #define REAPERAPI_WANT_Main_SaveProject
 #define REAPERAPI_WANT_Help_Set
 #define REAPERAPI_WANT_ShowConsoleMsg
-#define REAPERAPI_WANT_Undo_BeginBlock2
-#define REAPERAPI_WANT_Undo_EndBlock2
 #include "reaper_plugin_functions.h"
 
 namespace reasampler {
@@ -217,37 +215,13 @@ void doActivateMode(const std::string& modeId) {
 // of its own — nothing it writes mints a point unaided — so a user-fired tag stays one
 // Ctrl-Z only because the ACTION spans it, and the label names the act the user
 // actually fired rather than the reapply it happened to trigger. Every one of them
-// closes the block before persistViewState, which can pop a modal Save-As. Stack RAII
+// closes the block before persistViewState, which can pop a modal Save-As.
-// so a throw between the two calls cannot leave the block open in the user's project.
 //
-// ENDING THE RECLAIM SPAN IS PART OF OPENING, and every action here inherits it from
+// The point is recorded only where the reapply actually wrote: re-tagging tracks that
-// this one constructor. A mode switch fired seconds ago has left the span open; a block
+// already sit in that mode writes nothing to the project, and the ("", 0) discard form
-// opened over it makes each close pair with the other's open, collapsing the switch
+// UndoBlock closes on by default is real from a hand-fired action (DAW-measured,
-// into this tag — mechanism and full rule in src/shell/view/CLAUDE.md.
+// src/shell/view/CLAUDE.md). The membership move itself is never in the point either
-//
+// way — persistViewState runs after the close.
-// `markWrote` decides whether this block mints at all: re-tagging tracks that already
-// sit in that mode writes nothing to the project, and the ("", 0) discard form is real
-// from a hand-fired action (DAW-measured, same doc). The membership move itself is
-// never in the point either way — persistViewState runs after the close.
-class ActionUndoBlock {
-public:
-    ActionUndoBlock(std::string label, int mask) : label_(std::move(label)), mask_(mask) {
-        fxReclaimEndUndoSpan();
-        Undo_BeginBlock2(nullptr);
-    }
-    ~ActionUndoBlock() {
-        if (wrote_) Undo_EndBlock2(nullptr, label_.c_str(), mask_);
-        else        Undo_EndBlock2(nullptr, "", 0);
-    }
-    void markWrote() { wrote_ = true; }
-    ActionUndoBlock(const ActionUndoBlock&) = delete;
-    ActionUndoBlock& operator=(const ActionUndoBlock&) = delete;
-
-private:
-    std::string label_;
-    int         mask_;
-    bool        wrote_ = false;
-};
 
 // tag() replaces any prior single-mode membership (a leaf lives in one mode; the
 // cross-mode case is show-both).
@@ -256,9 +230,10 @@ void doTag(const std::string& modeId) {
     if (guids.empty()) return;  // nothing selected — no act, no undo point (cf. doMoveItems)
 
     {
-        ActionUndoBlock undo("ReaSampler: tag selected tracks -> " + modeId, kViewUndoMask);
+        UndoBlock undo(nullptr);
         for (const std::string& g : guids) g_session->view().membership().tag(g, modeId);
-        if (reapplyActiveMode()) undo.markWrote();
+        if (reapplyActiveMode())
+            undo.recordPoint("ReaSampler: tag selected tracks -> " + modeId, kViewUndoMask);
     }
     persistViewState(PersistScope::Full);
 }
@@ -270,9 +245,10 @@ void doUntag() {
     if (guids.empty()) return;
 
     {
-        ActionUndoBlock undo("ReaSampler: untag selected tracks", kViewUndoMask);
+        UndoBlock undo(nullptr);
         for (const std::string& g : guids) g_session->view().membership().untag(g);
-        if (reapplyActiveMode()) undo.markWrote();
+        if (reapplyActiveMode())
+            undo.recordPoint("ReaSampler: untag selected tracks", kViewUndoMask);
     }
     persistViewState(PersistScope::Full);
 }
@@ -284,10 +260,11 @@ void doShowBoth() {
     if (guids.empty()) return;
 
     {
-        ActionUndoBlock undo("ReaSampler: toggle show-both on selected tracks", kViewUndoMask);
+        UndoBlock undo(nullptr);
         MembershipIndex& m = g_session->view().membership();
         for (const std::string& g : guids) m.setShowBoth(g, !m.isShowBoth(g));
-        if (reapplyActiveMode()) undo.markWrote();
+        if (reapplyActiveMode())
+            undo.recordPoint("ReaSampler: toggle show-both on selected tracks", kViewUndoMask);
     }
     persistViewState(PersistScope::Full);
 }
@@ -307,10 +284,7 @@ void doMoveItems(const std::string& targetMode) {
     MembershipIndex& membership = g_session->view().membership();
 
     {
-        ActionUndoBlock undo(targetMode.empty()
+        UndoBlock undo(nullptr);
-                                 ? std::string("ReaSampler: untag selected items")
-                                 : "ReaSampler: move selected items -> " + targetMode,
-                             -1);
         for (const ItemRetagOp& op : ops) {
             if (op.untag) membership.untag(op.guid);
             else          membership.tag(op.guid, op.modeId);
@@ -321,7 +295,11 @@ void doMoveItems(const std::string& targetMode) {
         // no flag leaves nothing for a point to hold.
         const bool minted    = mintManagedLanes(g_session->view(), nullptr);
         const bool reapplied = reapplyActiveMode();
-        if (minted || reapplied) undo.markWrote();
+        if (minted || reapplied)
+            undo.recordPoint(targetMode.empty()
+                                 ? std::string("ReaSampler: untag selected items")
+                                 : "ReaSampler: move selected items -> " + targetMode,
+                             -1);
     }
 
     persistViewState(PersistScope::Full);

src/shell/actions/ingest.cpp

@@ -22,6 +22,7 @@
 #include "core/wire/instrument_drop.h"     // pure buildInstrumentDropPreset (.vstpreset image for a sampleId)
 #include "shell/actions/instrument_drop_win.h" // shell loadInstrumentOntoTrack (FX add+apply, no own undo block)
 #include "shell/persist/session.h"             // ReaSamplerSession
+#include "shell/undo/undo_block.h"             // the ONE undo-block opener
 
 #include "core/capture/wav_codec.h"            // parseWavLayout (32f fast-path validator), buildFloat32Wav, hashWavContent
 
@@ -36,8 +37,6 @@
 #define REAPERAPI_WANT_GetMediaSourceNumChannels
 #define REAPERAPI_WANT_GetMediaSourceSampleRate
 #define REAPERAPI_WANT_GetMediaSourceLength
-#define REAPERAPI_WANT_Undo_BeginBlock2
-#define REAPERAPI_WANT_Undo_EndBlock2
 #define REAPERAPI_WANT_GetSelectedTrack
 #include "reaper_plugin_functions.h"
 
@@ -362,14 +361,14 @@ void doImportFromMediaExplorer() {
         // so any open VST3 browser instances refresh to show the new sound.
         bool persisted = true;  // true when nothing needed persisting (dedup)
         if (r.added) {
-            Undo_BeginBlock2(nullptr);
+            {
-            g_session->bumpBankGeneration();
+                UndoBlock undo(nullptr);
-            persisted = g_session->saveToActiveProject();
+                g_session->bumpBankGeneration();
-            if (persisted)
+                persisted = g_session->saveToActiveProject();
-                Undo_EndBlock2(nullptr, "ReaSampler: import Media Explorer file into bank",
+                if (persisted)
-                               UNDO_STATE_MISCCFG);
+                    undo.recordPoint("ReaSampler: import Media Explorer file into bank",
-            else
+                                     UNDO_STATE_MISCCFG);
-                Undo_EndBlock2(nullptr, "", 0);
+            }
             bankPanelRefresh();
         }
         ShowConsoleMsg(("ReaSampler ingest: " + r.message +
@@ -386,20 +385,21 @@ void doImportFromMediaExplorer() {
 
     // Persist happens INSIDE the block and BEFORE the FX add so the new instance's
     // setState -> reloadInstrument sees the just-persisted sample.
-    Undo_BeginBlock2(nullptr);
     bool persisted = true;  // true when nothing needed persisting (dedup)
-    if (r.added) {
+    bool placed    = false;
-        g_session->bumpBankGeneration();
+    {
-        persisted = g_session->saveToActiveProject();
+        UndoBlock undo(nullptr);
+        if (r.added) {
+            g_session->bumpBankGeneration();
+            persisted = g_session->saveToActiveProject();
+        }
+        placed = loadInstrumentOntoTrack(target, preset);
+        // Anything else — the FX add/inject failed (already rolled back, no orphan), or
+        // the project was unsaved (persist no-op) — records no point at all.
+        if (placed && persisted)
+            undo.recordPoint("ReaSampler: import from Media Explorer into selected track",
+                             UNDO_STATE_MISCCFG);
     }
-    const bool placed = loadInstrumentOntoTrack(target, preset);
-    if (placed && persisted)
-        Undo_EndBlock2(nullptr, "ReaSampler: import from Media Explorer into selected track",
-                       UNDO_STATE_MISCCFG);
-    else
-        // Either the FX add/inject failed (already rolled back, no orphan) or the
-        // project was unsaved (persist no-op): discard so no empty point is recorded.
-        Undo_EndBlock2(nullptr, "", 0);
 
     bankPanelRefresh();
     if (placed)
@@ -450,13 +450,14 @@ void ingestDroppedFiles(const std::vector<std::string>& absolutePaths) {
 
     // One undo point for the whole drop, opened only if a NEW index entry was created.
     if (importedNew > 0) {
-        Undo_BeginBlock2(nullptr);
+        bool persisted = false;
-        g_session->bumpBankGeneration();
+        {
-        const bool persisted = g_session->saveToActiveProject();
+            UndoBlock undo(nullptr);
-        if (persisted)
+            g_session->bumpBankGeneration();
-            Undo_EndBlock2(nullptr, "ReaSampler: import dropped file(s)", UNDO_STATE_MISCCFG);
+            persisted = g_session->saveToActiveProject();
-        else
+            if (persisted)
-            Undo_EndBlock2(nullptr, "", 0);
+                undo.recordPoint("ReaSampler: import dropped file(s)", UNDO_STATE_MISCCFG);
+        }
         bankPanelRefresh();
         const std::string msg =
             "ReaSampler ingest: imported " + std::to_string(importedTotal) +

src/shell/actions/instrument_drop_win.cpp

@@ -13,6 +13,7 @@
 
 #include "core/version/app_version.h"      // vstPluginName() — the CHANNEL-correct FX name (stable/beta pairing)
 #include "core/wire/instrument_drop.h"  // classifyReaperSurface — the PURE, unit-tested classifier
+#include "shell/undo/undo_block.h"      // the ONE undo-block opener
 
 #include "reaper_plugin.h"
 
@@ -22,8 +23,6 @@
 #define REAPERAPI_WANT_TrackFX_Delete
 #define REAPERAPI_WANT_TrackFX_GetCount
 #define REAPERAPI_WANT_TrackFX_SetPreset
-#define REAPERAPI_WANT_Undo_BeginBlock2
-#define REAPERAPI_WANT_Undo_EndBlock2
 #include "reaper_plugin_functions.h"
 
 namespace reasampler {
@@ -138,9 +137,9 @@ bool loadInstrumentOntoTrack(MediaTrack* track, const std::vector<std::uint8_t>&
 bool performInstrumentDrop(MediaTrack* track, const std::vector<std::uint8_t>& presetBytes) {
     if (!track || presetBytes.empty()) return false;
 
-    Undo_BeginBlock2(nullptr);
+    UndoBlock undo(nullptr);
     const bool ok = loadInstrumentOntoTrack(track, presetBytes);
-    Undo_EndBlock2(nullptr, "ReaSampler: drop capture onto FX chain", -1);
+    undo.recordPoint("ReaSampler: drop capture onto FX chain", -1);
     return ok;
 }
 

src/shell/bank_ops/CLAUDE.md

@@ -26,13 +26,18 @@ calls into that model, it does not reimplement its rules.
 - **Movement is index-only.** Moving/copying a sample between banks removes/adds
   the index entry only; the underlying file never moves on disk. No bank operation
   writes, moves, or deletes a file.
-- **One bank operation is one Ctrl-Z.** Every bank index verb wraps its mutation in
+- **One bank operation is one Ctrl-Z, whatever else is in flight.** Every bank index
-  a batched REAPER undo point (`Undo_BeginBlock2`/`EndBlock2`, `UNDO_STATE_MISCCFG`)
+  verb wraps its mutation in a batched REAPER undo point (`UNDO_STATE_MISCCFG`) via
-  via `persistBankOp` — this is enforced in this directory, not left to callers.
+  `persistBankOp` — enforced in this directory, not left to callers. The block is
+  opened through `shell/undo`'s `UndoBlock`, which is what makes the claim hold while
+  a Design View mode switch's FX reclaim span is open: without it the verb's own
+  close landed at depth 2->1, minted nothing, and the rename or delete was absorbed
+  into the mode switch, un-undoable on its own. Reason and mechanism:
+  `src/shell/undo/CLAUDE.md`.
 
 ## Modules
 
-- `bank_ops` (`shell/bank_ops`) — the promptless bank-mutation verb seam (Q-W6 lift out of `panel_bank_ops`): `bankOpCreate`/`Rename`/`Delete`/`Evacuate`/`Activate`/`Transfer`/`Remove` + `persistBankOp` (the undo-batched ext-state persist), each taking a `ReaSamplerSession&` and returning whether the model accepted the mutation — no prompts, no message boxes, no panel-state reads. `shell/panel/panel_bank_ops` (menu/prompt UX) and `shell/actions/bank_actions` (bindable-action UX) both consume these as thin skins, so the mutation logic has exactly one home.
+- `bank_ops` (`shell/bank_ops`) — the promptless bank-mutation verb seam (Q-W6 lift out of `panel_bank_ops`): `bankOpCreate`/`Rename`/`Delete`/`Evacuate`/`Activate`/`Transfer`/`Remove` + `persistBankOp` (the `UndoBlock`-batched ext-state persist), each taking a `ReaSamplerSession&` and returning whether the model accepted the mutation — no prompts, no message boxes, no panel-state reads. `shell/panel/panel_bank_ops` (menu/prompt UX) and `shell/actions/bank_actions` (bindable-action UX) both consume these as thin skins, so the mutation logic has exactly one home.
 
 ## Gotchas
 

src/shell/bank_ops/bank_ops.cpp

@@ -14,12 +14,11 @@
 
 #include "core/model/bank_book.h"       // BankBook / TransferResult / RemoveScope
 #include "shell/persist/session.h"      // ReaSamplerSession — the session the verbs mutate
+#include "shell/undo/undo_block.h"      // the ONE undo-block opener
 
 #define REAPERAPI_MINIMAL
 #define REAPERAPI_WANT_genGuid
 #define REAPERAPI_WANT_guidToString
-#define REAPERAPI_WANT_Undo_BeginBlock2
-#define REAPERAPI_WANT_Undo_EndBlock2
 #include "reaper_plugin_functions.h"
 
 namespace reasampler {
@@ -50,13 +49,11 @@ std::string mintBankId() {
 // design (mirrors capture, not Design-View) — deliberately no Save-As prompt.
 void persistBankOp(ReaSamplerSession& session, const char* label,
                    bool bumpGeneration) {
-    Undo_BeginBlock2(nullptr);
+    UndoBlock undo(nullptr);
     if (bumpGeneration) session.bumpBankGeneration();
-    const bool persisted = session.saveToActiveProject();
+    // No ext-state write -> record no point; the block's default discard form is what
-    if (persisted)
+    // keeps an unsaved project from collecting no-effect undo entries.
-        Undo_EndBlock2(nullptr, label, UNDO_STATE_MISCCFG);
+    if (session.saveToActiveProject()) undo.recordPoint(label, UNDO_STATE_MISCCFG);
-    else
-        Undo_EndBlock2(nullptr, "", 0);  // no ext-state write -> discard the empty point
 }
 
 // --- Promptless inner bank verbs (one home) ------------------------------------

src/shell/capture/CLAUDE.md

@@ -20,6 +20,10 @@ relative-paths-only) and the load-bearing capture/placement separation — see r
 `CLAUDE.md` §Precision invariants and §The load-bearing principle. Shell-specific
 detail not covered there:
 
+- **Every undo block here is opened through `shell/undo`'s `UndoBlock`**, never
+  `Undo_BeginBlock2` directly — `insert`, `capture_orchestrator`, `capture_batch`,
+  `bake_land` and `render_in_place` alike. Rule and enforcement:
+  `src/shell/undo/CLAUDE.md`.
 - **The item scope's render source is window-dependent.** `ResolveScopeSource` is
   where that is decided — it measures the selected items' extent against the
   resolved range (`core/capture/render_window`) and hands the answer to

src/shell/capture/bake_land.cpp

@@ -1,7 +1,8 @@
 // bake_land.cpp — see bake_land.h. main.cpp owns the API pointers; this TU gets them
 // extern. REAPER symbols used here (EnumProjects, EnumProjExtState, GetProjExtState,
-// SetProjExtState, ShowConsoleMsg, Undo_BeginBlock2/EndBlock2) are verified against
+// SetProjExtState, ShowConsoleMsg) are verified against
-// vendor/reaper-sdk/sdk/reaper_plugin_functions.h. Landing one request is bake_landing's.
+// vendor/reaper-sdk/sdk/reaper_plugin_functions.h. Landing one request is
+// bake_landing's; the undo block is shell/undo's.
 
 #include "shell/capture/bake_land.h"
 
@@ -19,6 +20,7 @@
 #include "shell/capture/bake_landing.h"
 #include "shell/panel/panel_input.h"     // bankPanelRefresh
 #include "shell/persist/session.h"
+#include "shell/undo/undo_block.h"       // the ONE undo-block opener
 
 #include "reaper_plugin.h"  // UNDO_STATE_MISCCFG
 
@@ -28,8 +30,6 @@
 #define REAPERAPI_WANT_GetProjExtState
 #define REAPERAPI_WANT_SetProjExtState
 #define REAPERAPI_WANT_ShowConsoleMsg
-#define REAPERAPI_WANT_Undo_BeginBlock2
-#define REAPERAPI_WANT_Undo_EndBlock2
 #include "reaper_plugin_functions.h"
 
 namespace reasampler::capture {
@@ -107,26 +107,6 @@ struct ScannedKey {
     wire::BakeKeyOutcome report;
 };
 
-// Undo_BeginBlock2/EndBlock2 as stack RAII, the FxBypassGuard discipline: a landing reads a
-// whole WAV and hashes it, so a bad_alloc between the two calls would otherwise leave an
-// open undo block in the user's project. Closing with an empty description records no undo
-// point, which is what every path that landed nothing wants anyway.
-class UndoBlock {
-public:
-    UndoBlock() { Undo_BeginBlock2(nullptr); }
-    ~UndoBlock() { Undo_EndBlock2(nullptr, description_.c_str(), flags_); }
-    void recordPoint(std::string description, int flags) {
-        description_ = std::move(description);
-        flags_ = flags;
-    }
-    UndoBlock(const UndoBlock&) = delete;
-    UndoBlock& operator=(const UndoBlock&) = delete;
-
-private:
-    std::string description_;
-    int flags_ = 0;
-};
-
 // One entry's write-back, and the proof of whether it took. Guarded whole: it encodes into
 // a fresh string and readKey grows a buffer toward 16 MB, and a throw escaping here would
 // skip the ShowConsoleMsg for EVERY key — the silent console this action exists to make
@@ -206,7 +186,7 @@ void RunResampleBake(ReaSamplerSession& session) {
     // the answers already buffered — the exact no-answer-with-a-silent-console this action
     // exists to make impossible. UndoBlock is inside the try, so unwinding still closes it.
     try {
-        UndoBlock undo;
+        UndoBlock undo(nullptr);
         for (const OpenProject& open : openProjects()) {
             ++tally.tabsScanned;
             const bool activeTab = static_cast<const void*>(open.proj) == active;

src/shell/capture/capture_batch.cpp

@@ -25,6 +25,7 @@
 #include "shell/capture/render_bounds_gate.h"   // refusedRenderFolder
 #include "shell/capture/scope_resolve.h"        // ResolvedSource
 #include "shell/capture/track_guid.h"           // guidString
+#include "shell/undo/undo_block.h"              // the ONE undo-block opener
 
 #include "reaper_plugin.h"  // UNDO_STATE_MISCCFG
 
@@ -46,8 +47,6 @@
 #define REAPERAPI_WANT_SetTrackSelected
 #define REAPERAPI_WANT_SetOnlyTrackSelected
 #define REAPERAPI_WANT_ShowConsoleMsg
-#define REAPERAPI_WANT_Undo_BeginBlock2
-#define REAPERAPI_WANT_Undo_EndBlock2
 #include "reaper_plugin_functions.h"
 
 namespace reasampler::capture {
@@ -493,26 +492,26 @@ void RunRecaptureFromSource(ReaSamplerSession& session)
     updated.provenance   = prov;
 
     // One batched undo point around the in-place mutation; index-only ext-state,
-    // nothing placed on the timeline.
+    // nothing placed on the timeline. A plan that mutated nothing records no point at
-    Undo_BeginBlock2(nullptr);
+    // all — the block's default discard form.
-    // Before the index outcome is even known: the render above already wrote the file,
-    // and makeUniqueTag guarantees a NEW path, so this is a second record carrying the
-    // same sampleId as the original. The superseded file becomes an orphan for prune.
-    session.recordCreated(updated, tracking::OriginKind::Recapture);
-    const bool changed = session.book().updateSampleInPlace(sampleId, updated);
-    if (changed)
     {
-        // Regenerating the same id's audio is exactly why instances need the generation
+        UndoBlock undo(nullptr);
-        // bump — they'd otherwise keep playing stale audio until reload. Bumped inside
+        // Before the index outcome is even known: the render above already wrote the
-        // the undo block so undo rolls back the generation with the rest of the blob.
+        // file, and makeUniqueTag guarantees a NEW path, so this is a second record
-        session.bumpBankGeneration();
+        // carrying the same sampleId as the original. The superseded file becomes an
-        const bool persisted = session.saveToActiveProject();  // book + ledger + generation + MarkProjectDirty
+        // orphan for prune.
-        Undo_EndBlock2(nullptr, persisted ? "ReaSampler: re-capture from source" : "",
+        session.recordCreated(updated, tracking::OriginKind::Recapture);
-                       persisted ? UNDO_STATE_MISCCFG : 0);
+        if (session.book().updateSampleInPlace(sampleId, updated))
-    }
+        {
-    else
+            // Regenerating the same id's audio is exactly why instances need the
-    {
+            // generation bump — they'd otherwise keep playing stale audio until reload.
-        Undo_EndBlock2(nullptr, "", 0);  // nothing mutated -> discard the empty point
+            // Bumped inside the undo block so undo rolls back the generation with the
+            // rest of the blob.
+            session.bumpBankGeneration();
+            // book + ledger + generation + MarkProjectDirty
+            if (session.saveToActiveProject())
+                undo.recordPoint("ReaSampler: re-capture from source", UNDO_STATE_MISCCFG);
+        }
     }
 
     bankPanelRefresh();  // reflect the regenerated file in the docked grid

src/shell/capture/capture_orchestrator.cpp

@@ -18,6 +18,7 @@
 #include "shell/capture/realtime_lifecycle.h"  // the in-flight realtime state
 #include "shell/capture/render_selection.h"    // RenderTrackSelection
 #include "shell/capture/render_isolation.h"    // UpstreamIsolation
+#include "shell/undo/undo_block.h"             // the ONE undo-block opener
 
 #include "reaper_plugin.h"  // UNDO_STATE_MISCCFG
 
@@ -28,8 +29,6 @@
 #define REAPERAPI_WANT_GetMediaTrackInfo_Value
 #define REAPERAPI_WANT_SetMediaTrackInfo_Value
 #define REAPERAPI_WANT_ShowConsoleMsg
-#define REAPERAPI_WANT_Undo_BeginBlock2
-#define REAPERAPI_WANT_Undo_EndBlock2
 #include "reaper_plugin_functions.h"
 
 namespace reasampler::capture {
@@ -369,20 +368,22 @@ void RunCaptureItemAssign(ReaSamplerSession& session)
 {
     // Reuse the Item-scope def from the capture table (index 0) — same range logic, same
     // FX-scope neutralize, same bank/persist landing as the plain "capture item" action.
-    Undo_BeginBlock2(nullptr);
-
-    const std::string sampleId = RunCapture(session, captureActionTable()[0]);
-    if (sampleId.empty())
     {
-        // Capture failed or no-op'd — RunCapture already reported. Discard the empty point.
+        UndoBlock undo(nullptr);
-        Undo_EndBlock2(nullptr, "", 0);
-        return;
-    }
 
-    // Assign inside the same block so undo clears both keys together.
+        const std::string sampleId = RunCapture(session, captureActionTable()[0]);
-    ingestAssignActiveInstance(session.book().activeBankId(), sampleId);
+        if (sampleId.empty())
-    Undo_EndBlock2(nullptr, "ReaSampler: capture + assign to active instance",
+        {
-                   UNDO_STATE_MISCCFG);
+            // Capture failed or no-op'd — RunCapture already reported. The block closes
+            // on its default discard form, so the empty point is never recorded.
+            return;
+        }
+
+        // Assign inside the same block so undo clears both keys together.
+        ingestAssignActiveInstance(session.book().activeBankId(), sampleId);
+        undo.recordPoint("ReaSampler: capture + assign to active instance",
+                         UNDO_STATE_MISCCFG);
+    }
 
     bankPanelRefresh();
     ShowConsoleMsg("ReaSampler ingest: captured into the bank and assigned to the active "

src/shell/capture/insert.cpp

@@ -33,6 +33,7 @@
 #include "shell/panel/panel_bank_ops.h"  // bankPanelSelectedSampleIds / SourceBankId
 #include "core/capture/capture_paths.h"
 #include "shell/persist/session.h"
+#include "shell/undo/undo_block.h"
 
 #define REAPERAPI_MINIMAL
 #define REAPERAPI_WANT_CountSelectedTracks
@@ -44,8 +45,6 @@
 #define REAPERAPI_WANT_SetOnlyTrackSelected
 #define REAPERAPI_WANT_SetTrackSelected
 #define REAPERAPI_WANT_ShowConsoleMsg
-#define REAPERAPI_WANT_Undo_BeginBlock2
-#define REAPERAPI_WANT_Undo_EndBlock2
 #include "reaper_plugin_functions.h"
 
 namespace reasampler {
@@ -139,9 +138,8 @@ InsertResult runInsert(ReaSamplerSession* session, const InsertRequest& request)
     const double cursorPos = GetCursorPosition();
 
     // One undo block around the whole placement (all tracks + selection/cursor
-    // restore) so a single undo removes every item and restores prior state. Always
+    // restore) so a single undo removes every item and restores prior state.
-    // balanced — opened before the first insert, closed after the restore.
+    UndoBlock undo(nullptr);
-    Undo_BeginBlock2(nullptr);
 
     // Insert onto each selected track at the same cursor position (assumption B): per
     // track, isolate it as the only selection (A + E), reset the cursor (C is
@@ -159,11 +157,10 @@ InsertResult runInsert(ReaSamplerSession* session, const InsertRequest& request)
 
     // Label reflects count + conform choice for a clear undo history. extraflags -1 =
     // UNDO_STATE_ALL (tracks, items, envelope points, project state).
-    const std::string label =
+    undo.recordPoint("ReaSampler: insert on " + std::to_string(result.inserted) +
-        "ReaSampler: insert on " + std::to_string(result.inserted) +
+                         (result.inserted == 1 ? " track" : " tracks") +
-        (result.inserted == 1 ? " track" : " tracks") +
+                         (request.options.conform == TempoConform::None ? "" : " (conform)"),
-        (request.options.conform == TempoConform::None ? "" : " (conform)");
+                     -1);
-    Undo_EndBlock2(nullptr, label.c_str(), -1);
 
     result.status = InsertStatus::Ok;
     return result;

src/shell/capture/insert.h

@@ -44,7 +44,7 @@ struct InsertResult {
 // currently-selected track set, then inserts the sample onto EACH selected track
 // at the SAME edit-cursor position. Snapshot/restore ensures the user's track
 // selection and cursor position are unchanged after the action. The whole operation
-// is wrapped in a single Undo_BeginBlock2 / Undo_EndBlock2.
+// is wrapped in a single UndoBlock.
 //
 // No-op cases (with console messages):
 //   - No track selected: prints "select a track first."

src/shell/capture/render_in_place.cpp

@@ -21,7 +21,7 @@
 #include "shell/capture/track_guid.h"            // guidString
 #include "shell/panel/panel_input.h"             // bankPanelTailSetting
 #include "shell/persist/session.h"
-#include "shell/view/fx_reclaim.h"               // fxReclaimEndUndoSpan
+#include "shell/undo/undo_block.h"               // the ONE undo-block opener
 #include "shell/view/view.h"                     // applyMode
 #include "shell/view/view_lanes.h"               // mintManagedLanes
 
@@ -43,8 +43,6 @@
 #define REAPERAPI_WANT_SetOnlyTrackSelected
 #define REAPERAPI_WANT_ShowConsoleMsg
 #define REAPERAPI_WANT_TrackList_AdjustWindows
-#define REAPERAPI_WANT_Undo_BeginBlock2
-#define REAPERAPI_WANT_Undo_EndBlock2
 #include "reaper_plugin_functions.h"
 
 namespace reasampler::capture {
@@ -134,87 +132,88 @@ void RunRenderTrackInPlace(ReaSamplerSession& session) {
     // visible — never to choose a tag. Both tags below are absolute.
     const std::string activeMode = session.view().activeModeId();
 
-    // A mode switch fired seconds ago has left the FX reclaimer's undo span open, and
+    // Both read after the block closes, so both outlive the scope below.
-    // no block may open over it — mechanism in src/shell/view/CLAUDE.md. Ending it here
+    bool        placed = false;
-    // mints the switch's point, whole, before this block exists; idempotent otherwise.
+    std::string freshName;
-    fxReclaimEndUndoSpan();
 
-    Undo_BeginBlock2(nullptr);
+    // Scoped so the persist below lands OUTSIDE the block — see the note at the close.
+    {
+        UndoBlock undo(nullptr);
 
-    // flags = 0, never 1: flags&1 adds default envelopes/FX, and a default chain
+        // flags = 0, never 1: flags&1 adds default envelopes/FX, and a default chain
-    // would process a render that already carries the source's FX a second time.
+        // would process a render that already carries the source's FX a second time.
-    InsertTrackInProject(proj, place.insertIndex, /*flags=*/0);
+        InsertTrackInProject(proj, place.insertIndex, /*flags=*/0);
-    MediaTrack* fresh = GetTrack(proj, place.insertIndex);
+        MediaTrack* fresh = GetTrack(proj, place.insertIndex);
-    if (!fresh) {
+        if (!fresh) {
-        // InsertTrackInProject already mutated the project by this point, so the
+            // InsertTrackInProject already mutated the project by this point, so the
-        // "no ext-state write -> discard" idiom does not apply here — a discard would
+            // "no ext-state write -> discard" idiom does not apply here — a discard would
-        // leave the orphaned track un-undoable.
+            // leave the orphaned track un-undoable.
-        Undo_EndBlock2(nullptr, "ReaSampler: render in place (failed to create result track)",
+            undo.recordPoint("ReaSampler: render in place (failed to create result track)", -1);
-                       -1);
+            refuse("could not create the result track; the render landed at " +
-        refuse("could not create the result track; the render landed at " +
+                   res.absolutePath + " but was not placed.");
-               res.absolutePath + " but was not placed.");
+            return;
-        return;
-    }
-
-    // Both writes or none — one alone lands the new track at the wrong nesting level,
-    // which is audible in both directions (see siblingPlacement).
-    if (place.precedingIndex >= 0) {
-        if (MediaTrack* preceding = GetTrack(proj, place.precedingIndex))
-            SetMediaTrackInfo_Value(preceding, "I_FOLDERDEPTH",
-                                    static_cast<double>(place.precedingDepth));
-    }
-    SetMediaTrackInfo_Value(fresh, "I_FOLDERDEPTH",
-                            static_cast<double>(place.newDepth));
-
-    // GetTrackColor returns the colour already OR'd with 0x1000000 and 0 for "no
-    // colour set", which I_CUSTOMCOLOR reads as unused — so one line clones a colour
-    // and the absence of one, with no branch.
-    SetMediaTrackInfo_Value(fresh, "I_CUSTOMCOLOR",
-                            static_cast<double>(GetTrackColor(source)));
-    const std::string freshName = captureTrackName(trackName(source));
-    setTrackName(fresh, freshName);
-
-    // After every attribute write, per the SDK header's manual-panel-update caveat.
-    TrackList_AdjustWindows(false);
-
-    // Unsnapped and unrounded, deliberately: this placement IS the null test performed
-    // automatically, so snapping it to the grid would move the audio off the position
-    // it was rendered from. InsertOptions{} defaults give native length and no conform.
-    const double cursorPos = GetCursorPosition();
-    SetOnlyTrackSelected(fresh);
-    SetEditCurPos(src.startSeconds, false, false);
-    // InsertMedia's int return isn't SDK-documented; treated conservatively as
-    // 0 = failure, matching performArrangeDrop — an empty result track would
-    // otherwise be a silent no-op, which is exactly what this verb must not produce.
-    const bool placed =
-        InsertMedia(res.absolutePath.c_str(), computeInsertMode(InsertOptions{})) != 0;
-    SetEditCurPos(cursorPos, false, false);
-    // The new track is left selected, alone — in the headline case the source is being
-    // parked out of sight in the same gesture, so restoring the selection would leave
-    // the user selecting an invisible track.
-
-    // Absolute, not mode-following: the source parks on the bench, the result is an
-    // Arrange member whatever mode was active. Explicit records rather than untag(),
-    // because the record is what the panel's auto-tag detector defers to.
-    MembershipIndex& membership = session.view().membership();
-    membership.tag(guidString(source), kDesignModeId);
-    membership.tag(guidString(fresh), kArrangeModeId);
-
-    // The track is brand new, so its items are exactly the ones just placed. An
-    // untagged item would be handed to the detector, which tags to the active mode.
-    const int itemCount = CountTrackMediaItems(fresh);
-    for (int i = 0; i < itemCount; ++i) {
-        if (MediaItem* it = GetTrackMediaItem(fresh, i)) {
-            const std::string ig = itemGuid(it);
-            if (!ig.empty()) membership.tag(ig, kArrangeModeId);
         }
+
+        // Both writes or none — one alone lands the new track at the wrong nesting level,
+        // which is audible in both directions (see siblingPlacement).
+        if (place.precedingIndex >= 0) {
+            if (MediaTrack* preceding = GetTrack(proj, place.precedingIndex))
+                SetMediaTrackInfo_Value(preceding, "I_FOLDERDEPTH",
+                                        static_cast<double>(place.precedingDepth));
+        }
+        SetMediaTrackInfo_Value(fresh, "I_FOLDERDEPTH",
+                                static_cast<double>(place.newDepth));
+
+        // GetTrackColor returns the colour already OR'd with 0x1000000 and 0 for "no
+        // colour set", which I_CUSTOMCOLOR reads as unused — so one line clones a colour
+        // and the absence of one, with no branch.
+        SetMediaTrackInfo_Value(fresh, "I_CUSTOMCOLOR",
+                                static_cast<double>(GetTrackColor(source)));
+        freshName = captureTrackName(trackName(source));
+        setTrackName(fresh, freshName);
+
+        // After every attribute write, per the SDK header's manual-panel-update caveat.
+        TrackList_AdjustWindows(false);
+
+        // Unsnapped and unrounded, deliberately: this placement IS the null test performed
+        // automatically, so snapping it to the grid would move the audio off the position
+        // it was rendered from. InsertOptions{} defaults give native length and no conform.
+        const double cursorPos = GetCursorPosition();
+        SetOnlyTrackSelected(fresh);
+        SetEditCurPos(src.startSeconds, false, false);
+        // InsertMedia's int return isn't SDK-documented; treated conservatively as
+        // 0 = failure, matching performArrangeDrop — an empty result track would
+        // otherwise be a silent no-op, which is exactly what this verb must not produce.
+        placed =
+            InsertMedia(res.absolutePath.c_str(), computeInsertMode(InsertOptions{})) != 0;
+        SetEditCurPos(cursorPos, false, false);
+        // The new track is left selected, alone — in the headline case the source is being
+        // parked out of sight in the same gesture, so restoring the selection would leave
+        // the user selecting an invisible track.
+
+        // Absolute, not mode-following: the source parks on the bench, the result is an
+        // Arrange member whatever mode was active. Explicit records rather than untag(),
+        // because the record is what the panel's auto-tag detector defers to.
+        MembershipIndex& membership = session.view().membership();
+        membership.tag(guidString(source), kDesignModeId);
+        membership.tag(guidString(fresh), kArrangeModeId);
+
+        // The track is brand new, so its items are exactly the ones just placed. An
+        // untagged item would be handed to the detector, which tags to the active mode.
+        const int itemCount = CountTrackMediaItems(fresh);
+        for (int i = 0; i < itemCount; ++i) {
+            if (MediaItem* it = GetTrackMediaItem(fresh, i)) {
+                const std::string ig = itemGuid(it);
+                if (!ig.empty()) membership.tag(ig, kArrangeModeId);
+            }
+        }
+
+        mintManagedLanes(session.view(), nullptr);
+        applyMode(session.view(), activeMode, nullptr);  // a reapply, never a switch
+
+        undo.recordPoint("ReaSampler: render selected track to a new track", -1);
     }
 
-    mintManagedLanes(session.view(), nullptr);
-    applyMode(session.view(), activeMode, nullptr);  // a reapply, never a switch
-
-    Undo_EndBlock2(nullptr, "ReaSampler: render selected track to a new track", -1);
-
     // Persist outside the block. The offline render's own save gate already forced a
     // saved project, so the Save-As-guarded persist the Design View actions need
     // cannot have anything to prompt for here.

src/shell/undo/CLAUDE.md

@@ -0,0 +1,53 @@
+# src/shell/undo — the one REAPER undo-block opener
+
+## Scope
+
+One type, `UndoBlock`, and one query, `undoBlockOpen()`. Every extension-owned undo
+block in the tree is opened through this type; nothing here decides what a point is
+called or whether one is worth minting — each call site still owns its own label,
+mask, and discard-vs-mint condition. The FX reclaim span is NOT this directory's:
+`shell/view/fx_reclaim` owns it, and this directory only guarantees no block ever
+nests over it.
+
+## Invariants
+
+- **`Undo_BeginBlock2` is not callable outside this directory, and that is enforced
+  by the compiler, not by review.** Only `undo_block.cpp` and `shell/view`'s
+  `fx_reclaim.cpp` (which owns the span's own begin/end) define
+  `REAPERAPI_WANT_Undo_BeginBlock2` / `..._Undo_EndBlock2`. Every other TU compiles
+  under `REAPERAPI_MINIMAL` with no header in its include graph pulling the SDK in
+  unguarded, so a raw `Undo_BeginBlock2` there is an undeclared identifier. Adding
+  the WANT define back to a third TU is the one way to defeat this — do not.
+- **Ending the reclaim span is part of opening, and ONLY the outermost block does
+  it.** At depth 0 the span is the only block that can be open, so ending it mints
+  the pending mode switch's point whole before this block exists. At depth > 0 an
+  enclosing `UndoBlock` already ended it, and a close from the inner one would land
+  at depth 2->1 — minting nothing and hijacking the enclosing block's label. That
+  is the same criterion `applyMode`'s reapply is gated on; it lives in the
+  constructor so no call site has to make the judgment. Full reasoning for the rule
+  itself: `src/shell/view/CLAUDE.md`.
+- **Closing is a destructor.** No throw between the open and the label decision can
+  leave a block open in the user's project, which is why several call sites can
+  allocate freely between the two.
+- **No label recorded means no point.** `UndoBlock` closes on `("", 0)` unless
+  `recordPoint` was called — the discard form, real from a hand-fired action
+  (DAW-measured; `src/shell/view/CLAUDE.md`). A verb that mutated nothing therefore
+  costs no undo entry simply by saying nothing.
+
+## Modules
+
+- `undo_block` — `UndoBlock` (RAII open/close plus `recordPoint`) and
+  `undoBlockOpen()`. The latter is read by `fxReclaimTick`, which refuses a tick
+  outright while any block is open: the drain's lazy `openSpan` would otherwise
+  begin at depth 2, and the enclosing block's close would then mint under the span's
+  label and destroy the user's own point. The refusal consumes nothing — no wakeup,
+  no queue, no project pin — so the first tick after the block closes drains as if
+  this one had never been due.
+
+## Gotchas
+
+- The depth counter deliberately does NOT count the reclaim span. The span is the
+  thing this stands off, not a peer.
+- The counter drops AFTER `Undo_EndBlock2`, not before: the close that reaches depth
+  0 mints a point, and anything re-entered through that must still read a block as
+  open rather than let the drain open a span underneath it.

src/shell/undo/undo_block.cpp

@@ -0,0 +1,51 @@
+// See undo_block.h. Compiled into the reaper_reasampler module; includes
+// reaper_plugin_functions.h without REAPERAPI_IMPLEMENT (main.cpp owns that).
+
+#include "shell/undo/undo_block.h"
+
+#include <utility>
+
+#include "shell/view/fx_reclaim.h"  // fxReclaimEndUndoSpan — the span this must not nest over
+
+#define REAPERAPI_MINIMAL
+#define REAPERAPI_WANT_Undo_BeginBlock2
+#define REAPERAPI_WANT_Undo_EndBlock2
+#include "reaper_plugin_functions.h"
+
+namespace reasampler {
+
+namespace {
+
+// Extension-owned nesting depth only — REAPER's own counter is not readable, and the
+// reclaim span is deliberately NOT counted here (it is the thing this stands off).
+int g_depth = 0;
+
+}  // namespace
+
+bool undoBlockOpen() { return g_depth > 0; }
+
+UndoBlock::UndoBlock(ReaProject* proj) : project_(proj) {
+    // ONLY the outermost block ends the span, which mechanizes the whole nesting rule.
+    // At depth 0 the span is the only block that can be open, so ending it mints the
+    // switch's point whole, at depth 0, before this block exists. At depth > 0 the
+    // enclosing UndoBlock already did it, and a close from here would land at depth
+    // 2->1 — minting nothing and hijacking the enclosing block's label instead. That is
+    // the same criterion applyMode's reapply is gated on.
+    if (g_depth++ == 0) fxReclaimEndUndoSpan();
+    Undo_BeginBlock2(proj);
+}
+
+UndoBlock::~UndoBlock() {
+    // Depth drops AFTER the SDK call, not before: the close that reaches depth 0 mints a
+    // point, and anything re-entered through that must still read a block as open rather
+    // than let the drain open a span underneath it.
+    Undo_EndBlock2(project_, label_.c_str(), mask_);
+    --g_depth;
+}
+
+void UndoBlock::recordPoint(std::string label, int mask) {
+    label_ = std::move(label);
+    mask_  = mask;
+}
+
+}  // namespace reasampler

src/shell/undo/undo_block.h

@@ -0,0 +1,42 @@
+#pragma once
+// The ONE way an extension undo block is opened. Ending the FX reclaim span is part of
+// opening, so no block can ever nest over it, and the close is a destructor, so no throw
+// can leave one open in the user's project.
+//
+// Enforced by the SDK's own opt-in: only this TU and fx_reclaim.cpp (which owns the span
+// itself) define REAPERAPI_WANT_Undo_BeginBlock2, so `Undo_BeginBlock2` does not even
+// name a declared symbol anywhere else in the tree.
+
+#include <string>
+
+// Forward-declared to keep this header SDK-free; the .cpp includes the real SDK header.
+class ReaProject;
+
+namespace reasampler {
+
+class UndoBlock {
+public:
+    // `proj` is nullptr for the active project, matching Undo_BeginBlock2's own contract
+    // (reaper_plugin_functions.h:7753).
+    explicit UndoBlock(ReaProject* proj);
+    ~UndoBlock();
+
+    // What the close names the point. Never called, the block closes on the discard form
+    // (`""`, 0) — real from a hand-fired action, a coalesce from a timer (see UndoSpan),
+    // and what every site that ended up writing nothing already wanted.
+    void recordPoint(std::string label, int mask);
+
+    UndoBlock(const UndoBlock&) = delete;
+    UndoBlock& operator=(const UndoBlock&) = delete;
+
+private:
+    ReaProject* project_ = nullptr;
+    std::string label_;
+    int         mask_ = 0;
+};
+
+// True while any UndoBlock is alive, at any nesting depth. The FX reclaim drain reads it
+// to stand off a tick it would otherwise open its span inside of — see fxReclaimTick.
+bool undoBlockOpen();
+
+}  // namespace reasampler

src/shell/view/CLAUDE.md

@@ -122,9 +122,16 @@ decide membership or mode rules.
   FX write, and the only reason the span exists. A TRANSPORT deferral is not bounded
   (it lasts as long as the playback pass), so it ends the span and the parking that
   follows mints its own point (`spanEndsAfter`).
-- **NOTHING MAY OPEN AN UNDO BLOCK WHILE THE SPAN IS OPEN — every opener ends it
+  Stated as ONE property over the pure state, which is how it is tested
-  first, as its first act.** REAPER's blocks are read as a DEPTH COUNTER, not a stack
+  (`tests/test_fx_reclaim.cpp`, at every terminator rather than incidentally in one
-  of identities (`[verify — DAW]`, and the same undocumented nested-block behaviour the
+  scenario): **`!pending()` implies `!span.open()`.** The timer gates every tick on
+  `pending()`, so a span left open with the wakeup down has nothing that could ever
+  close it. That is why `applyMode` raises the wakeup BEFORE it opens the span rather
+  than on its way out — a throw in between would otherwise leak the block with the
+  reclaimer asleep — and why the state-load terminator closes BEFORE it abandons.
+- **NOTHING MAY OPEN AN UNDO BLOCK WHILE THE SPAN IS OPEN — and no site decides that
+  for itself any more.** REAPER's blocks are read as a DEPTH COUNTER, not a stack of
+  identities (`[verify — DAW]`, and the same undocumented nested-block behaviour the
   Gotchas below name): `Undo_EndBlock2` at depth 2->1 mints nothing and drops the label
   and mask it was handed, and the close that does reach depth 0 mints under whatever
   label IT carries. So a block opened over the span leaves each close paired with the
@@ -134,18 +141,31 @@ decide membership or mode rules.
   reading: ending the span first yields the switch's point and the opener's as two
   correctly-labelled points under the counter reading AND under an identity-pairing one,
   which is why it is stated as an unconditional discipline rather than a workaround for
-  a behaviour nobody has observed. Ending it first mints the switch's point whole, at
+  a behaviour nobody has observed. **The mechanism is `shell/undo`'s `UndoBlock`, which
-  depth 0, and leaves the opener's block the only one in play. The
+  every extension-owned block in the tree now opens through — its constructor ends the
-  openers, all of them: `design_view_actions`' `ActionUndoBlock` (whose constructor
+  span when, and only when, it is the OUTERMOST block, so a nested opener cannot close
-  ends the span, so all four membership actions inherit it), `view_lanes`'
+  at depth 2->1 and hijack its enclosing block.** That directory's `CLAUDE.md` owns the
-  `mintManagedLanes`, and `shell/capture`'s `render_in_place`. The mirror half is
+  mechanism and the compile-time enforcement behind it; here it closes three things at
-  `applyMode`'s: a REAPPLY never closes a span, precisely because it is reachable from
+  once. First, the openers no longer have to be enumerated by hand — the former list
-  inside one of those blocks — only a real switch supersedes, and a real switch is
+  (`ActionUndoBlock`, `mintManagedLanes`, `render_in_place`) was never the whole set and
-  always fired at depth 0. RESIDUAL, out of this rule's reach: an extension undo block
+  omitted ten user-fired blocks in `shell/capture`, `shell/bank_ops` and
-  ELSEWHERE (a capture, a bank verb, an ingest) that pumps the message loop can re-enter
+  `shell/actions`, each of which absorbed the user's own act into the mode switch.
-  the timer, and a drain tick that settles in there closes the span at depth 2->1 with
+  Second, `mintManagedLanes` gets the same nesting criterion as everything else: it is
-  the same result. Closing that needs every extension-owned `Undo_BeginBlock2` to route
+  called from inside `doMoveItems`' and `render_in_place`' blocks, where it used to end
-  through one opener that ends the span — not attempted here.
+  the span unconditionally. Third, the RESIDUAL in the other direction is closed too —
+  a foreign block's message pump can re-enter the timer, and a drain tick in there would
+  open its span at depth 2; `fxReclaimTick` now refuses outright while `undoBlockOpen()`
+  and consumes nothing, so it simply drains on the first tick after the block closes.
+  The mirror half is still `applyMode`'s: a REAPPLY never closes a span, precisely
+  because it is reachable from inside one of those blocks — only a real switch
+  supersedes, and a real switch is always fired at depth 0.
+  ACCEPTED, and not fixed: `mintManagedLanes` opens its block once its plan is
+  non-empty, but a non-empty plan whose writes are all already satisfied still mints
+  nothing — so a background detect tick can end a switch's span having competed with it
+  for nothing. Telling the two apart means running the plan, which is the write. The
+  cost is bounded at ONE extra undo point (the switch mints early; its remaining parking
+  mints again under `kReclaimUndoLabel`), the same degradation a transport deferral
+  already carries, where the alternative destroys the switch's point outright.
 - **EVERY project-state load terminates the span itself, at the hook, before REAPER
   restores anything — `isUndo` does not narrow it.**
   `fxReclaimAbandonForStateLoad` runs UNBRANCHED from `BeginLoadProjectState`
@@ -234,13 +254,13 @@ applies the resulting lane state to live tracks.
 
 ## Modules
 
-- `view` — Design View shell: runs the pure planner over the live folder tree and iterates its park/restore plans, applies managed-lane and parent-visibility writes, and on a REAL SWITCH ends any prior span and opens the ONE undo span all of that rides (`fx_reclaim` is what closes it; a reapply opens none and closes none). Reports what it wrote (`ModeApplyResult`) so a caller holding its own block can discard an empty point. Owns the one discriminator (`target != active`) that separates a real switch from a reapply, and with it both the playback gate (`transportBlocksModeSwitch`) and the solo cache/clear/restore seams. **Never touches master or `B_MUTE`.** FX are NOT written here — see `fx_reclaim`.
+- `view` — Design View shell: runs the pure planner over the live folder tree and iterates its park/restore plans, applies managed-lane and parent-visibility writes, and on a REAL SWITCH ends any prior span, raises the reclaimer's wakeup, and opens the ONE undo span all of that rides (`fx_reclaim` is what closes it; a reapply opens none and closes none). Reports what it wrote (`ModeApplyResult`) so a caller holding its own block can discard an empty point. Owns the one discriminator (`target != active`) that separates a real switch from a reapply, and with it both the playback gate (`transportBlocksModeSwitch`) and the solo cache/clear/restore seams. **Never touches master or `B_MUTE`.** FX are NOT written here — see `fx_reclaim`.
 - `view_park` — the park surface, FLAG DOMAIN ONLY. `parkTrack` captures the pre-park snapshot (flags AND the FX chain's identity-keyed offline state) when the model holds none, drives the four flags, and EXPOSEs a track that reads park-shaped with no record behind it rather than adopting it; `restoreTrack` writes the flags back from the snapshot and spends its flag half (`releaseSnapshotFlags`). Also `trackFlagParm` (the one `Flag` → REAPER-parameter mapping), `writeIfChanged` (the read-before-write every driven parameter goes through), `fxGuidString` (the one FX-identity read snapshot/reclaim both address FX through), `kViewUndoMask`, and `reportExposedTracks`/`describeExposedTracks` (named tracks, once per changed set per project).
 - `view_lanes` — managed fixed lanes: `mintManagedLanes` splits multi-mode content onto per-mode lanes, `applyLaneOps` drives `C_LANEPLAYS` for the active mode, `reconcileManagedLanes` recovers ownership from durable `P_LANENAME` on project open. Manual lanes are never minted, driven, renamed or reassigned.
 - `view_reconcile` — the repair pass for a project state REAPER reloaded under us: `noteAppliedState` records what an apply left driven; `reconcileAppliedFlags` diffs that fingerprint against the reloaded model and hands back any track the reload no longer records but still reads driven — the fix for `UNDO_STATE_TRACKCFG` not carrying `B_SHOWINTCP`/`B_SHOWINMIXER` (DAW-confirmed). It opens no undo block: it runs in the wake of a Ctrl-Z, and its writes are flags only.
 - `view_tracks` — the scaffolding every write pass sets up: `TrackHandles`/`TrackByGuid`, `readFolderEntries`/`indexHandles`, and `UiRefreshHold` (the `PreventUIRefresh` RAII pair every write phase runs under).
 - `view_solo` — the `I_SOLO` read/write pair behind the per-mode solo surface, plus `clearTrackSolos`/`restoreTrackSolos`, the outgoing-clear and incoming-replay entry points `view` drives them through. Holds no policy: what to cache, clear, or replay is `core/view/solo_cache`.
-- `fx_reclaim` — the FX convergence loop, off the switch's synchronous path (`TrackFX_SetOffline` was 1897ms of a measured 1942ms switch). `drainTick` moves one track's FX per step against `core/view/fx_state`'s derived work list (Online before Offline; an Offline item waits out `kParkHoldMs` so a fast A→B→A flip moves nothing), budgeted per tick (`kOnlineBudgetMs`/`kOfflineBudgetMs`) and gated off the transport for the Offline direction only. `FxReclaimQueue` owns the derived queue's lifetime across re-entrancy (a plugin unload is assumed to pump). `UndoSpan` owns the ONE undo block the whole drain writes under — opened by `applyMode` on a real switch, else lazily by the first `writeOffline`, and closed through the single idempotent `fxReclaimEndUndoSpan` that every terminating path routes through (`spanEndsAfter` decides which ticks terminate; `fxReclaimAbandonForStateLoad` is the state-load terminator, which also stops the drain). `ReleaseFlush`/`fxReclaimFlushRelease` make a completed record's spend durable on the project's next save, never on the drain's own initiative. `fxReclaimActivity` reports WHICH DIRECTION the drain is moving for an indicator to paint — Idle whenever nothing may move, so a debounced or transport-held offline item never names a direction nothing is travelling in; undirected `fxReclaimPending` stays the timer's one idle test and must not drive a UI (it is true throughout the debounce, when only the OPPOSITE direction is eligible).
+- `fx_reclaim` — the FX convergence loop, off the switch's synchronous path (`TrackFX_SetOffline` was 1897ms of a measured 1942ms switch). `drainTick` moves one track's FX per step against `core/view/fx_state`'s derived work list (Online before Offline; an Offline item waits out `kParkHoldMs` so a fast A→B→A flip moves nothing), budgeted per tick (`kOnlineBudgetMs`/`kOfflineBudgetMs`) and gated off the transport for the Offline direction only. `FxReclaimQueue` owns the derived queue's lifetime across re-entrancy (a plugin unload is assumed to pump). `UndoSpan` owns the ONE undo block the whole drain writes under — opened by `applyMode` on a real switch, else lazily by the first `writeOffline`, never while an extension undo block is open (`fxReclaimTick` refuses the tick outright, consuming nothing), and closed through the single idempotent `fxReclaimEndUndoSpan` that every terminating path routes through (`spanEndsAfter` decides which ticks terminate; `fxReclaimAbandonForStateLoad` is the state-load terminator, which also stops the drain). `ReleaseFlush`/`fxReclaimFlushRelease` make a completed record's spend durable on the project's next save, never on the drain's own initiative. `fxReclaimActivity` reports WHICH DIRECTION the drain is moving for an indicator to paint — Idle whenever nothing may move, so a debounced or transport-held offline item never names a direction nothing is travelling in; undirected `fxReclaimPending` stays the timer's one idle test and must not drive a UI (it is true throughout the debounce, when only the OPPOSITE direction is eligible).
 
 ## Gotchas
 
@@ -338,15 +358,15 @@ applies the resulting lane state to live tracks.
   into sync.
 - **"Nothing nests on the reapply paths" was FALSE, and cost the switch its undo
   point.** `render_in_place` and the membership actions each call `applyMode` inside
-  their own `Undo_BeginBlock2` pair; the reapply opens no block of its own, but a prior
+  their own block; the reapply opens none of its own, but a prior REAL SWITCH's span can
-  REAL SWITCH's span can still be open — for `kParkHoldMs` plus the whole drain — and
+  still be open — for `kParkHoldMs` plus the whole drain — and it is a block like any
-  it is a block like any other. Two things nest there, and both are now handled by the
+  other. Two things nest there, and both are now handled by the "nothing may open a
-  "nothing may open a block while the span is open" invariant: the caller's block over
+  block while the span is open" invariant: the caller's block over the span (`UndoBlock`
-  the span (each caller ends the span first), and the reapply's former unconditional
+  ends it at the outermost open), and the reapply's former unconditional supersede-close
-  supersede-close inside the caller's block (only a real switch closes now). What still
+  inside the caller's block (only a real switch closes now). What still nests
-  nests legitimately: `doMoveItems` and `render_in_place` over `mintManagedLanes`, both
+  legitimately: `doMoveItems` and `render_in_place` over `mintManagedLanes`, all three
-  properly paired inside a single outer block, so the SDK's undocumented nested-block
+  `UndoBlock`s, so the SDK's undocumented nested-block coalescing is load-bearing only
-  coalescing is load-bearing only for that shape.
+  for that shape.
 - `fx_offline`'s identity keying (`TrackFX_GetFXGUID`) assumes the GUID stays
   attached to its plugin across a chain mutation while parked. That is
   `[verify — DAW]` (see `fxGuidString` in `view_park.cpp`) and SWS issue #802 is a

src/shell/view/fx_reclaim.cpp

@@ -11,6 +11,7 @@
 #include <vector>
 
 #include "shell/persist/session.h"  // flushViewState — the release's durable half
+#include "shell/undo/undo_block.h"  // undoBlockOpen — the reverse of the nesting rule
 #include "shell/view/view.h"        // modeApplyInProgress, transportBlocksModeSwitch
 #include "shell/view/view_park.h"   // fxGuidString — the one FX-identity read
 #include "shell/view/view_tracks.h"
@@ -233,12 +234,21 @@ void invalidateFxReclaim() {
 bool fxReclaimDrainInProgress() { return g_draining; }
 
 void fxReclaimTick(ReaSamplerSession& session, ReaProject* proj) {
-    // Neither guard may close the span: both name a caller that is still on the stack and
+    // NO guard here may close the span: each names a caller that is still on the stack and
-    // still owns it — the outer drain, or the applyMode that opened it. Both re-tick.
+    // still owns it — the outer drain, or the applyMode that opened it. All re-tick.
     if (g_draining) return;
     // The model is mid-rewrite and its records are being consumed out from under any
     // plan derived from it. The apply invalidates on its way out, so nothing is lost.
     if (modeApplyInProgress()) return;
+    // The MIRROR of the rule that no block may open over the span: an extension undo
+    // block is open — a capture, a bank verb, an ingest — and its own message pump is how
+    // this tick arrived. openSpan from in there would begin at depth 2, and that block's
+    // close would then mint under the SPAN's label and destroy the user's own point.
+    // Refused whole rather than written unspanned, which would instead absorb the FX
+    // toggles into the user's act. Starves nothing: the wakeup, the derived queue and the
+    // project pin are all untouched (this returns before beginTick), so the first tick
+    // after the block closes drains exactly as if this one had never been due.
+    if (undoBlockOpen()) return;
     DrainLatch latch;
 
     // beginTick owns what a pin/project mismatch means. What is local to here: the model

src/shell/view/fx_reclaim.h

@@ -658,7 +658,9 @@ bool fxReclaimDrainInProgress();
 // Drains one tick against `proj` (nullptr = current project), re-deriving the queue from
 // the session's view model first if it was invalidated or if the active project moved
 // (FxReclaimQueue::beginTick). Returns without touching the project while an applyMode is
-// on the stack, while already draining, or when there is no valid active project at all.
+// on the stack, while already draining, while any extension undo block is open
+// (shell/undo's undoBlockOpen — a refusal that consumes nothing, so the next tick drains),
+// or when there is no valid active project at all.
 // Takes the SESSION rather than the model alone because completing an online spends the
 // park record's FX half — see FxReclaimQueue::run.
 void fxReclaimTick(ReaSamplerSession& session, ReaProject* proj);
@@ -667,7 +669,8 @@ void fxReclaimTick(ReaSamplerSession& session, ReaProject* proj);
 // ONE Ctrl-Z. Called by applyMode on a REAL SWITCH ONLY — a reapply opens no block at
 // all — which then returns with the span still open, and the reclaimer closes it once
 // the parking has drained. No-op if a span is already open, so callers END first (see
-// applyMode) rather than nesting.
+// applyMode) rather than nesting. applyMode also raises the wakeup BEFORE this call: the
+// tick it guarantees is the only thing that can ever close the span again.
 void fxReclaimBeginUndoSpan(ReaProject* proj);
 
 // Sets what the eventual close names the point. Separate from the begin because the
@@ -677,8 +680,9 @@ void fxReclaimLabelUndoSpan(const char* label, int mask);
 // The ONE close, idempotent: every terminating path routes through it — the drain
 // settling, aborting, or deferring on the transport; the project retargeting or closing;
 // the next apply superseding it; ANY project-state load; a project save; extension
-// unload. A leaked open block would swallow everything the user does afterwards, so
+// unload; and shell/undo's UndoBlock, at its OUTERMOST open. A leaked open block would
-// nothing may return past a terminating condition without calling this.
+// swallow everything the user does afterwards, so nothing may return past a terminating
+// condition without calling this.
 void fxReclaimEndUndoSpan();
 
 // EVERY project-state load, undo-driven or not — Ctrl-Z, Ctrl-Shift-Z, a project open, a

src/shell/view/view.cpp

@@ -128,6 +128,13 @@ ModeApplyResult applyModeImpl(ViewModeModel& model, const std::string& targetMod
     // CLAUDE.md. Both calls are idempotent; do not reintroduce either unconditionally.
     if (realSwitch) {
         fxReclaimEndUndoSpan();
+        // BEFORE the open, never after this function returns. The wakeup is what
+        // guarantees a tick, and a tick is the only thing that can close this span; a
+        // throw anywhere below would otherwise leave the block open with the reclaimer
+        // asleep, swallowing every later edit until a save, a state load, the next switch
+        // or unload. The wrapper's own invalidate stays where it is — it covers the
+        // refusal paths above, which never reach this line.
+        invalidateFxReclaim();
         fxReclaimBeginUndoSpan(project);
     }
     {

src/shell/view/view_lanes.cpp

@@ -16,15 +16,13 @@
 #include "core/view/lane_keys.h"
 #include "core/view/view_tree.h"
 #include "shell/capture/item_read.h"
-#include "shell/view/fx_reclaim.h"  // fxReclaimEndUndoSpan — no block opens over the span
+#include "shell/undo/undo_block.h"  // the ONE undo-block opener
 #include "shell/view/view_park.h"  // writeIfChanged — the read-before-write every driven parm takes
 
 #define REAPERAPI_MINIMAL
 #define REAPERAPI_WANT_GetMediaTrackInfo_Value
 #define REAPERAPI_WANT_SetMediaTrackInfo_Value
 #define REAPERAPI_WANT_GetSetMediaTrackInfo_String
-#define REAPERAPI_WANT_Undo_BeginBlock2
-#define REAPERAPI_WANT_Undo_EndBlock2
 #define REAPERAPI_WANT_UpdateArrange
 #define REAPERAPI_WANT_UpdateTimeline
 #define REAPERAPI_WANT_CountTrackMediaItems
@@ -277,21 +275,46 @@ bool mintManagedLanes(ViewModeModel& model, ReaProject* proj) {
 
     const TrackByGuid trackByGuid = indexHandles(handleByGuid);
 
-    // No block may open over a still-open reclaim span — mechanism in this directory's
+    bool changed = false;
-    // CLAUDE.md. Placed past the empty-plan return above deliberately: a detect tick
+    {
-    // that mints nothing must not shorten a span it never competes with.
+        // Opening ends any reclaim span — but only when this is the OUTERMOST block, so
-    fxReclaimEndUndoSpan();
+        // the two callers that already hold one (doMoveItems, render_in_place) are not
+        // hijacked. UndoBlock owns that criterion; do not re-end the span here.
+        //
+        // ACCEPTED, not fixed: the plan being non-empty is not the same as its writes
+        // being needed, so the already-satisfied case below still ends a switch's span
+        // having minted nothing of its own. Telling the two apart means running the plan
+        // first, which is the write. The cost is bounded at ONE extra undo point — the
+        // switch mints early and its remaining parking mints again under
+        // kReclaimUndoLabel, the same degradation a transport deferral already carries —
+        // where the alternative, opening over the span, destroys the switch's point
+        // outright.
+        //
+        // `proj` deliberately NOT pinned the way applyMode pins it: nothing between the
+        // open and the close pumps the message loop, so no tab switch can land between.
+        UndoBlock undo(proj);
+        changed = applyMintPlan(model, plan, trackByGuid);
 
-    // `proj` deliberately NOT pinned the way applyMode pins it: nothing between this
+        if (changed) {
-    // begin and its end pumps the message loop, so no tab switch can land between them.
+            // Reapply the active mode's lane visibility so freshly-minted lanes take
-    Undo_BeginBlock2(proj);
+            // their play/show state immediately. applyMode is deliberately NOT reused
-    const bool changed = applyMintPlan(model, plan, trackByGuid);
+            // here — it would re-park/restore whole tracks and recompute parent
+            // visibility, which a lane-only mint must not touch.
+            const TogglePlan togglePlan =
+                model.planToggle(FolderTree{}, model.activeModeId());
+            applyLaneOps(trackByGuid, togglePlan.lanes);
+
+            UpdateTimeline();  // a split happened this call — refresh is owed
+            UpdateArrange();
+
+            undo.recordPoint("ReaSampler: separate cross-mode content into lanes",
+                             kViewUndoMask);
+        }
+        // Otherwise every write was already satisfied: the block's default discard form
+        // keeps the detect tick from flooding history with empty points.
+    }
 
     if (!changed) {
-        // Plan was non-empty but every write was already satisfied — discard the empty
-        // undo point rather than flooding history every detect tick.
-        Undo_EndBlock2(proj, "", 0);
-
         // The arrange still needs a redraw: this no-op path is reached when a
         // freshly-inserted item already landed on the active mode's playing lane
         // (REAPER places new items on the playing lane), so assignItemToLane wrote
@@ -299,21 +322,8 @@ bool mintManagedLanes(ViewModeModel& model, ReaProject* proj) {
         // alone (no I_FREEMODE change happened, so UpdateTimeline isn't owed) is a
         // repaint, not a mutation — stays outside the undo block.
         UpdateArrange();
-        return false;
     }
-
+    return changed;
-    // Reapply the active mode's lane visibility so freshly-minted lanes take their
-    // play/show state immediately. applyMode is deliberately NOT reused here — it
-    // would re-park/restore whole tracks and recompute parent visibility, which a
-    // lane-only mint must not touch.
-    const TogglePlan togglePlan = model.planToggle(FolderTree{}, model.activeModeId());
-    applyLaneOps(trackByGuid, togglePlan.lanes);
-
-    UpdateTimeline();  // a split happened this call — refresh is owed
-    UpdateArrange();
-
-    Undo_EndBlock2(proj, "ReaSampler: separate cross-mode content into lanes", kViewUndoMask);
-    return true;
 }
 
 void reconcileManagedLanes(ViewModeModel& model, ReaProject* proj) {

tests/test_fx_reclaim.cpp

@@ -1433,6 +1433,93 @@ static void testTheDirectionHoldsThroughTheDrainsOwnMessagePump() {
     CHECK(q.activity(host.clock, host.rolling) == FxReclaimActivity::Idle);  // latch released
 }
 
+// -- 13. the sleep invariant ------------------------------------------------------------
+
+// !pending() => !span.open(), at EVERY terminator. A span left open with the wakeup down
+// has nothing left that could ever close it: the timer gates every tick on pending(), and
+// the block then swallows the user's edits until a save, a state load, the next switch or
+// unload. The check below is written as that implication and applied to each pure move
+// that can put the loop to sleep, rather than falling out of one scenario.
+static bool asleepWithTheSpanOpen(const FxReclaimQueue& q, const UndoSpan& span) {
+    return !q.pending() && span.open();
+}
+
+static void testNoTerminatorLeavesTheSpanOpenWithTheLoopAsleep() {
+    // FIRST, the predicate's own teeth: the violation is expressible, so a CHECK that it
+    // does not occur is not vacuously true.
+    {
+        FxReclaimQueue q;
+        UndoSpan       span;
+        span.begin(kProjA, "ReaSampler: activate Design view", 9);
+        q.goIdle();  // the sleep WITHOUT the close — exactly the leak this test forbids
+        CHECK(asleepWithTheSpanOpen(q, span));
+    }
+
+    // 1. Every verdict a tick can come back with, swept whole. The shell closes on
+    //    spanEndsAfter and sleeps on settled, in that order (fxReclaimTick); the property
+    //    is that the second can never fire where the first did not.
+    for (int bits = 0; bits < 8; ++bits) {
+        ReclaimRunResult run;
+        run.settled           = (bits & 1) != 0;
+        run.aborted           = (bits & 2) != 0;
+        run.transportDeferred = (bits & 4) != 0;
+
+        FxReclaimQueue q;
+        UndoSpan       span;
+        q.invalidate();
+        CHECK(q.beginTick(kProjA));
+        span.begin(kProjA, "ReaSampler: activate Design view", 9);
+
+        if (spanEndsAfter(run)) span.end();
+        if (!run.aborted && run.settled) q.goIdle();
+
+        CHECK(!asleepWithTheSpanOpen(q, span));
+    }
+
+    // 2. The state-load terminator. `abandon` is the one move that clears the wakeup with
+    //    work still owed, which is what makes the close-FIRST ordering load-bearing rather
+    //    than tidy — reverse the two and the loop is asleep under an open block.
+    {
+        FxReclaimQueue q;
+        UndoSpan       span;
+        q.invalidate();
+        span.begin(kProjA, "ReaSampler: activate Design view", 9);
+        span.end();  // fxReclaimAbandonForStateLoad closes before it abandons
+        q.abandon();
+        CHECK(!q.pending());
+        CHECK(!asleepWithTheSpanOpen(q, span));
+    }
+
+    // 3. The project moving out from under the span. No active project sleeps the loop
+    //    (beginTick's nullptr arm), a tab switch does not — but both close, because the
+    //    span is keyed on its OWN project and neither one is it.
+    for (ReaProject* arrived : {static_cast<ReaProject*>(nullptr), kProjB}) {
+        FxReclaimQueue q;
+        UndoSpan       span;
+        q.invalidate();
+        q.beginTick(kProjA);
+        span.begin(kProjA, "ReaSampler: activate Design view", 9);
+
+        if (span.project() != arrived) span.end();
+        q.beginTick(arrived);
+
+        CHECK(!span.open());
+        CHECK(!asleepWithTheSpanOpen(q, span));
+    }
+
+    // 4. The terminators with no queue move at all — a project save, an extension unload,
+    //    the next real switch superseding. Each is the idempotent close alone, so the
+    //    wakeup is whatever it already was; the implication has to hold either way.
+    for (bool woken : {false, true}) {
+        FxReclaimQueue q;
+        UndoSpan       span;
+        if (woken) q.invalidate();
+        span.begin(kProjA, "ReaSampler: activate Design view", 9);
+        span.end();
+        CHECK(!asleepWithTheSpanOpen(q, span));
+    }
+}
+
 int main() {
     testFastFlipMovesZeroPluginsButAHeldParkStillReclaims();
 
@@ -1484,6 +1571,8 @@ int main() {
     testARollingTransportHidesOfflineWorkFromTheDirectionButNeverOnline();
     testTheDirectionHoldsThroughTheDrainsOwnMessagePump();
 
+    testNoTerminatorLeavesTheSpanOpenWithTheLoopAsleep();
+
     if (g_fail == 0) std::printf("All tests passed.\n");
     return g_fail ? 1 : 0;
 }