Beam suspender: replace the plain SuspendFloor with one that checks the ring's operating mode

[Anthony Sligar (sligara7)]

Replaces the plain beam-current suspender in the profile with a mode-aware one that checks the storage ring's operating mode every time it is evaluated, so low beam does not suspend the RunEngine while the ring is in maintenance or shutdown.

Why

main installs SuspendFloor(storage_ring.beam_current, 100, resume_thresh=390) unconditionally, so scans suspend on low beam even when the ring is down for maintenance or shutdown. An earlier approach (on a working branch, not on main) instead read the mode once at startup and skipped installing the suspender; that never sees a mode change later in the session. Per Jakub's review, the check now lives inside the suspender.

Changes

• hextools.suspenders.SuspendFloorUnlessOpsMode: a SuspendFloor that also subscribes to the ring's operating mode and folds it into _should_suspend / _should_resume:
  • normal operation: suspend below 100 mA, resume above 390 mA, as before;
  • MAINTENANCE / SHUTDOWN: low beam does not suspend, and entering one of these modes releases a tripped suspender;
  • returning to operations with beam still low trips it straight away;
  • until the mode has been read, it behaves like a plain SuspendFloor;
  • both the beam and the mode signal may be ophyd-async signals or ophyd-style ones, as SuspendFloor allows.
• profiles/collection.py: installs it in place of the plain SuspendFloor, with skip_modes=(MAINTENANCE, SHUTDOWN).

How it was verified: mock

• tests/test_suspenders.py (9 tests, mock NSLS2StorageRing and ophyd Signals): trips on low beam in operations; ignores low beam in maintenance and in shutdown; releases when the ring enters maintenance while tripped; trips when operations resume with beam still low; resumes on beam recovery; works with ophyd-style beam, mode, or both. The mode tests and the ophyd-style mode tests were each observed failing before their fix.
• Full suite: 128 passed; the 9 failures are the same ones that fail on main (60acf66), so CI will show them here too.
• Not yet run against the real ring PVs, the simulator, or a beamline.

Assisted-by: copilot:claude-opus-4-8

[Copilot]

Copilot review overview

🟡 Changes recommended

Legacy ophyd signals are reevaluated using the wrong callback form, and the PR description conflicts with the base diff.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Pass legacy beam callbacks using the expected value keyword · New
• Correct description of replacing the suspender with a mode-aware one · New

What changed in this PR

Adds mode-aware beam-current suspension that reacts to storage-ring mode changes.

Changes:

• Adds SuspendFloorUnlessOpsMode.
• Installs it in the collection profile.
• Adds mode-transition tests.

File	Description
src/​hextools/​suspenders.py	Implements mode-aware suspension.
src/​hextools/​profiles/​collection.py	Configures the new suspender.
tests/​test_suspenders.py	Tests current and mode transitions.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟡 Changes recommended

Concurrent mode and beam callbacks can leave the cached beam value stale.

Review effort: Balanced
Findings: 1

Open (1)

• Serialize mode updates with beam callbacks under the suspender lock · New

Resolved since last review (2)

• Pass legacy beam callbacks using the expected value keyword
• Correct description of replacing the suspender with a mode-aware one

[Copilot]

Copilot review overview

🔵 Needs a closer look

The concurrency-sensitive behavior affects live RunEngine suspension and has not been validated against real ring signals.

Review effort: Balanced
Findings: None

Resolved since last review (1)

• Serialize mode updates with beam callbacks under the suspender lock