dsh-labscript 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,19 +1,30 @@
-# Changelog
-
-## 0.2.0
-
-- Safe default: backend is mock-labscript unless the config explicitly sets labscript.
-- labs_abort bypasses the serial queue, so it is never blocked behind labs_wait.
-- Pending/last-run state is persisted under DSH_HOME and reloaded after a restart.
-- labs_doctor: read-only diagnostic for python, numpy/h5py, labscript/runmanager, paths and versions.
-- Minimal Plugins-page configuration page (backend, python, runmanager, protocolsDir) + doctor results.
-- Python environment requirements documented per backend.
-
-## 0.1.0
-
-- Eight labs_* tools: status, set, engage, wait, abort, data, protocol, restore.
-- Fixed-operation YAML protocols with postprocess write-back and panel restore.
-- Panel snapshots before writes plus an events.jsonl action log.
-- Built-in mock-labscript backend for tests, examples and hardware-free development.
-- Runmanager (labscript) backend built on the stock remote API and shot HDF5.
-- Stalled-queue diagnosis, selective panel restore and accurate abort semantics.
+# Changelog
+
+## 0.2.1
+
+- Hard limits support a lower bound: limits entries can now use min as well as max
+  (panel writes and scan expressions are checked on both sides).
+- Boolean globals can be limited too: true/false count as 1/0, so max: 0 forbids "on"
+  and min: 1 requires it.
+- labs_protocol show reports keys that are missing from the currently loaded labscript;
+  protocol runs ask for an explicit confirmation on real hardware before proceeding.
+- labs_abort now also stops an in-flight labs_wait, so a running batch can be cancelled
+  without waiting for the wait timeout.
+
+## 0.2.0
+
+- Safe default: backend is mock-labscript unless the config explicitly sets labscript.
+- labs_abort bypasses the serial queue, so it is never blocked behind labs_wait.
+- Pending/last-run state is persisted under DSH_HOME and reloaded after a restart.
+- labs_doctor: read-only diagnostic for python, numpy/h5py, labscript/runmanager, paths and versions.
+- Minimal Plugins-page configuration page (backend, python, runmanager, protocolsDir) + doctor results.
+- Python environment requirements documented per backend.
+
+## 0.1.0
+
+- Eight labs_* tools: status, set, engage, wait, abort, data, protocol, restore.
+- Fixed-operation YAML protocols with postprocess write-back and panel restore.
+- Panel snapshots before writes plus an events.jsonl action log.
+- Built-in mock-labscript backend for tests, examples and hardware-free development.
+- Runmanager (labscript) backend built on the stock remote API and shot HDF5.
+- Stalled-queue diagnosis, selective panel restore and accurate abort semantics.

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 dsh-labscript contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 dsh-labscript contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,154 +1,161 @@
-# dsh-labscript
-
-Control a [labscript-suite](https://labscriptsuite.org/) experiment from DeepSeek Harness (DSH).
-
-The plugin exposes the stock labscript control surface only: the runmanager remote API
-(panel globals, n_shots, engage, abort, run_shots, error_in_globals) plus the shot HDF5
-files. It does not require any custom BLACS/lyse patch. Everything lab-specific
-(analysis, protocols, hard limits) is supplied by configuration.
-
-## Status
-
-v0.2.0. The mock-labscript backend, the protocol/postprocess flow and the
-snapshot/diagnosis behaviour are covered by node and python tests. A client
-configuration page (Plugins page) and a read-only `labs_doctor` are included. The real
-labscript backend is implemented against the stock runmanager remote API but has
-not yet been validated on laboratory hardware. Start real-machine work with a
-read-only status call, then a single-key write/restore, then a few shots.
-
-## Requirements
-
-- DSH >= 0.2 and Node.js ^22.19 or >= 24.
-- Python >= 3.9. Mock mode needs only numpy >= 1.23 and h5py >= 3.8; real
-  hardware needs the labscript-suite Python environment (labscript, runmanager,
-  labscript_utils, zprocess importable). Tested with Python 3.11.0,
-  numpy 2.2.5, h5py 3.13.0. The plugin never stores credentials; zprocess
-  authentication is read by labscript from labconfig.
-
-## Install
-
-Clone this repository, add it as a `link:` dependency in your DSH profile and
-`pnpm install`; docs/INSTALL.zh.md walks through it. The backend defaults to
-`mock-labscript`; real hardware is only used when the config sets
-`backend: labscript` explicitly. Connection settings can be edited in
-Plugins -> dsh-labscript after install (advanced keys stay in the profile
-config). Run `labs_doctor` first if anything looks misconfigured.
-
-## Tools
-
-| Tool | What it does |
-|---|---|
-| labs_doctor | Read-only configuration diagnostic: python, numpy/h5py, labscript/runmanager, paths, approval, versions. |
-| labs_status | Read the panel: labscript, globals, n_shots, error_in_globals, run_shots, pending run progress, snapshot directory |
-| labs_set | Write panel globals (or raw expressions, or the repetition counter). Snapshots the panel first. Does not run. |
-| labs_engage | Submit the current panel for a run; returns immediately with n_shots_at_submit and expected_n_shots |
-| labs_wait | Wait (blocking, with timeout) for the pending run; finalizes a pending protocol: postprocess, finish write-back, restore |
-| labs_abort | Abort the current submission |
-| labs_data | Read the run folder HDF5: first-shot globals and, with scan, a per-shot table |
-| labs_protocol | list / show / run YAML fixed-operation protocols |
-| labs_restore | Restore the panel from the latest snapshot taken before a write |
-
-A runtime skill named labscript carries the workflow rules (status first, fixed
-protocols for stable flows, submit then end the turn, one run at a time, never
-guess panel state).
-
-## Fixed-operation protocols
-
-    name: demo_scan
-    labscript: /path/to/your/sequence.py   # or: joint_script: registry_key
-    set:
-      do_acquire: true
-      amplitude: 0.5
-    scan:
-      duration_test_us: np.linspace(0.0, 8.0, 5)   # expression, number or list
-    reps: 2
-    postprocess: demo.peaks                        # entry configured once
-    finish:
-      restore: true
-      panel:
-        duration_test_us: fit.center               # written back to the panel
-      history:
-        demo.peaks.center_us: fit.center           # appended to the calibration jsonl
-
-    labs_protocol show demo_scan     # validates the plan and hard limits
-    labs_protocol run demo_scan      # set + scan + reps + engage, returns immediately
-    labs_wait                        # waits, then postprocess -> finish -> restore
-
-## Configuration
-
-Add one row to your DSH profile patch (see examples/config.example.yml):
-
-    - id: dsh-labscript
-      name: dsh-labscript
-      config:
-        python: /path/to/labscript-suite/python
-        backend: labscript
-        runmanager: { host: 127.0.0.1, port: 42523, timeoutS: 10 }
-        protocolsDir: /path/to/protocols
-        scriptsFile: /path/to/scripts.json
-        hardLimitsFile: /path/to/hard_limits.json
-        calibrationLog: /path/to/calibration.jsonl
-        pathMap:
-          - { remotePrefix: "E:/Experiments", localPrefix: "//lab-pc/Experiments" }
-        reps: { global: dummy_iterator }
-        postprocess:
-          entry: my_lab.analysis:analyze
-          pythonPaths: [/path/to/my_lab]
-        approval: { engage: true, protocolRun: true }
-
-The python interpreter must be able to import numpy and h5py; the real backend
-also needs runmanager (labscript-suite). The plugin never stores credentials:
-zprocess authentication is read by labscript itself from labconfig.
-
-### Mock backend
-
-    backend: mock-labscript
-
-runs a built-in simulator (fake panel, fake HDF5, persistent state under
-mock.stateDir). It exists for tests, examples and hardware-free development; it
-is not a physics simulation.
-
-## Install (local)
-
-    git clone <this repo> && cd dsh-labscript
-    npm install
-    # add "dsh-labscript": "link:/path/to/dsh-labscript" to the profile package.json
-    # add the bundle name and the cordis.patch.yml row; restart DSH
-
-## Development
-
-    npm install              # only runtime dependency: yaml
-    npm test                 # node --test, 18 tests (fake bridge, no python needed)
-    python python/tests/run_tests.py   # 8 tests (needs numpy + h5py)
-    LABSCRIPT_PYTHON=/path/to/python3 node scripts/demo.mjs   # end-to-end mock demo
-
-A fresh clone must run `npm install` before `npm test`; the CI workflow does this.
-
-## Docs
-
-- docs/README.zh.md - Chinese guide
-- docs/INSTALL.zh.md - local DSH profile install
-
-## Boundaries
-
-- Real hardware: engage/protocol run ask for a DSH approval (one-shot) when the
-  backend is labscript; abort and panel writes do not. The plugin is not a
-  hardware interlock.
-- Completion is detected from the run folder on the filesystem (HDF5 count,
-  stable file sizes, and a readable last shot); stock labscript has no
-  run-state query.
-- Cancelling labs_wait only stops waiting: the run keeps going. Call labs_abort
-  explicitly when something must stop. labscript abort stops compiling/submitting new
-  shots; shots already queued in BLACS or running are not stopped.
-- labs_wait reports a diagnosis (complete, no_shots, compiling, compiled_not_executed,
-  partial). compiled_not_executed means shots exist but show no acquisition data yet;
-  BLACS may be paused or not executing the queue.
-- Real runmanager engage does not return a run folder; the bridge captures the
-  output folder before engage and reports it as the run folder.
-- The panel is snapshotted before every write; labs_restore restores only the keys the
-  write touched (full=true restores the whole panel), so unrelated concurrent edits survive.
-- Actions are logged to events.jsonl next to the snapshots.
-
----
-
-Development note: implemented with assistance from a DeepSeek Harness coding agent.
+# dsh-labscript
+
+Control a [labscript-suite](https://labscriptsuite.org/) experiment from DeepSeek Harness (DSH).
+
+The plugin exposes the stock labscript control surface only: the runmanager remote API
+(panel globals, n_shots, engage, abort, run_shots, error_in_globals) plus the shot HDF5
+files. It does not require any custom BLACS/lyse patch. Everything lab-specific
+(analysis, protocols, hard limits) is supplied by configuration.
+
+## Status
+
+v0.2.0. The mock-labscript backend, the protocol/postprocess flow and the
+snapshot/diagnosis behaviour are covered by node and python tests. A client
+configuration page (Plugins page) and a read-only `labs_doctor` are included. The real
+labscript backend is implemented against the stock runmanager remote API but has
+not yet been validated on laboratory hardware. Start real-machine work with a
+read-only status call, then a single-key write/restore, then a few shots.
+
+## Requirements
+
+- DSH >= 0.2 and Node.js ^22.19 or >= 24.
+- Python >= 3.9. Mock mode needs only numpy >= 1.23 and h5py >= 3.8; real
+  hardware needs the labscript-suite Python environment (labscript, runmanager,
+  labscript_utils, zprocess importable). Tested with Python 3.11.0,
+  numpy 2.2.5, h5py 3.13.0. The plugin never stores credentials; zprocess
+  authentication is read by labscript from labconfig.
+
+## Install
+
+Install the npm package `dsh-labscript` (add it to the DSH profile
+dependencies and run `pnpm install`), or clone this repository and use a
+`link:` dependency for local development. docs/INSTALL.zh.md walks through both. The backend defaults to
+`mock-labscript`; real hardware is only used when the config sets
+`backend: labscript` explicitly. Connection settings can be edited in
+Plugins -> dsh-labscript after install (advanced keys stay in the profile
+config). Run `labs_doctor` first if anything looks misconfigured.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| labs_doctor | Read-only configuration diagnostic: python, numpy/h5py, labscript/runmanager, paths, approval, versions. |
+| labs_status | Read the panel: labscript, globals, n_shots, error_in_globals, run_shots, pending run progress, snapshot directory |
+| labs_set | Write panel globals (or raw expressions, or the repetition counter). Snapshots the panel first. Does not run. |
+| labs_engage | Submit the current panel for a run; returns immediately with n_shots_at_submit and expected_n_shots |
+| labs_wait | Wait (blocking, with timeout) for the pending run; finalizes a pending protocol: postprocess, finish write-back, restore |
+| labs_abort | Abort the current submission |
+| labs_data | Read the run folder HDF5: first-shot globals and, with scan, a per-shot table |
+| labs_protocol | list / show / run YAML fixed-operation protocols |
+| labs_restore | Restore the panel from the latest snapshot taken before a write |
+
+A runtime skill named labscript carries the workflow rules (status first, fixed
+protocols for stable flows, submit then end the turn, one run at a time, never
+guess panel state).
+
+## Fixed-operation protocols
+
+    name: demo_scan
+    labscript: /path/to/your/sequence.py   # or: joint_script: registry_key
+    set:
+      do_acquire: true
+      amplitude: 0.5
+    scan:
+      duration_test_us: np.linspace(0.0, 8.0, 5)   # expression, number or list
+    reps: 2
+    postprocess: demo.peaks                        # entry configured once
+    finish:
+      restore: true
+      panel:
+        duration_test_us: fit.center               # written back to the panel
+      history:
+        demo.peaks.center_us: fit.center           # appended to the calibration jsonl
+
+    labs_protocol show demo_scan     # validates the plan and hard limits
+    labs_protocol run demo_scan      # set + scan + reps + engage, returns immediately
+    labs_wait                        # waits, then postprocess -> finish -> restore
+
+## Configuration
+
+Add one row to your DSH profile patch (see examples/config.example.yml):
+
+    - id: dsh-labscript
+      name: dsh-labscript
+      config:
+        python: /path/to/labscript-suite/python
+        backend: labscript
+        runmanager: { host: 127.0.0.1, port: 42523, timeoutS: 10 }
+        protocolsDir: /path/to/protocols
+        scriptsFile: /path/to/scripts.json
+        hardLimitsFile: /path/to/hard_limits.json
+        calibrationLog: /path/to/calibration.jsonl
+        pathMap:
+          - { remotePrefix: "E:/Experiments", localPrefix: "//lab-pc/Experiments" }
+        reps: { global: dummy_iterator }
+        postprocess:
+          entry: my_lab.analysis:analyze
+          pythonPaths: [/path/to/my_lab]
+        approval: { engage: true, protocolRun: true }
+
+The python interpreter must be able to import numpy and h5py; the real backend
+also needs runmanager (labscript-suite). The plugin never stores credentials:
+zprocess authentication is read by labscript itself from labconfig.
+
+### Mock backend
+
+    backend: mock-labscript
+
+runs a built-in simulator (fake panel, fake HDF5, persistent state under
+mock.stateDir). It exists for tests, examples and hardware-free development; it
+is not a physics simulation.
+
+## Install (local)
+
+    git clone <this repo> && cd dsh-labscript
+    npm install
+    # add "dsh-labscript": "link:/path/to/dsh-labscript" to the profile package.json
+    # add the bundle name and the cordis.patch.yml row; restart DSH
+
+## Development
+
+    npm install              # only runtime dependency: yaml
+    npm test                 # node --test, 18 tests (fake bridge, no python needed)
+    python python/tests/run_tests.py   # 8 tests (needs numpy + h5py)
+    LABSCRIPT_PYTHON=/path/to/python3 node scripts/demo.mjs   # end-to-end mock demo
+
+A fresh clone must run `npm install` before `npm test`; the CI workflow does this.
+
+## Docs
+
+- docs/README.zh.md - Chinese guide
+- docs/INSTALL.zh.md - local DSH profile install
+
+## Boundaries
+
+- Real hardware: engage/protocol run ask for a DSH approval (one-shot) when the
+  backend is labscript; abort and panel writes do not. The plugin is not a
+  hardware interlock.
+- Optional hard limits (limits/channels entries with min and/or max, plus
+  run_limits) are checked on panel writes and protocol planning; boolean values
+  count as 0/1. They are advisory configuration, not a safety interlock.
+- labs_protocol show warns when a set/scan key is missing from the currently loaded
+  labscript; protocol runs ask for confirmation before proceeding on real hardware.
+- Completion is detected from the run folder on the filesystem (HDF5 count,
+  stable file sizes, and a readable last shot); stock labscript has no
+  run-state query.
+- Cancelling labs_wait only stops waiting: the run keeps going. Call labs_abort
+  explicitly when something must stop; labs_abort also cancels an in-flight labs_wait.
+  labscript abort stops compiling/submitting new shots; shots already queued in BLACS
+  or running are not stopped.
+- labs_wait reports a diagnosis (complete, no_shots, compiling, compiled_not_executed,
+  partial). compiled_not_executed means shots exist but show no acquisition data yet;
+  BLACS may be paused or not executing the queue.
+- Real runmanager engage does not return a run folder; the bridge captures the
+  output folder before engage and reports it as the run folder.
+- The panel is snapshotted before every write; labs_restore restores only the keys the
+  write touched (full=true restores the whole panel), so unrelated concurrent edits survive.
+- Actions are logged to events.jsonl next to the snapshots.
+
+---
+
+Development note: implemented with assistance from a DeepSeek Harness coding agent.

package/cordis.patch.yml

@@ -1,6 +1,6 @@
-# dsh-labscript -- DSH bundle patch
-#
-# Declares the plugin row. The "name" must match the installed package name.
-- insert:
-    - id: dsh-labscript
-      name: dsh-labscript
+# dsh-labscript -- DSH bundle patch
+#
+# Declares the plugin row. The "name" must match the installed package name.
+- insert:
+    - id: dsh-labscript
+      name: dsh-labscript

package/docs/INSTALL.zh.md

@@ -1,54 +1,64 @@
-# 安装（DSH desktop profile）
-
-## 0. 环境要求
-
-- DSH >= 0.2，Node.js ^22.19 或 >= 24。
-- Python >= 3.9。
-  - mock 模式：只需 numpy >= 1.23、h5py >= 3.8；
-  - 真机模式：用 labscript-suite 的 Python 环境（labscript、runmanager、
-    labscript_utils、zprocess 可导入）。
-  - 开发时实测：Python 3.11.0、numpy 2.2.5、h5py 3.13.0。
-
-## 1. 安装插件
-
-把仓库放到本机任意目录（下称 `<repo>`），在 DSH desktop profile 里 link 安装：
-
-1. 编辑 `%USERPROFILE%\.dsh\profiles\desktop\package.json`：
-
-       "dependencies": {
-         ...,
-         "dsh-labscript": "link:<repo>"
-       }
-
-   并在 `dsh.profile.bundles` 里加入 `"dsh-labscript"`。
-
-2. 在 profile 目录执行 `pnpm install`，重启 DSH。
-3. 新会话里应出现 9 个 `labs_*` 工具和 `labscript` skill。
-
-实验机建议固定 tag：`git checkout v0.2.0` 后再安装，避免 main 变动影响硬件行为。
-
-## 2. 配置
-
-优先在 DSH 里配置：侧边栏 → 插件 → dsh-labscript，填 backend、python、
-runmanager host/port、protocolsDir，保存后下一次工具调用生效（不用重启）。
-
-高级配置（scriptsFile、hard limits、postprocess、approval、pathMap、超时等）
-仍写在 profile 的 `cordis.patch.yml`：
-
-    - id: dsh-labscript
-      name: dsh-labscript
-      config:
-        scriptsFile: <path>/scripts.json
-        hardLimitsFile: <path>/hard_limits.json
-        postprocess:
-          entry: my_lab.analysis:analyze
-          pythonPaths: [<path>/my_lab]
-        approval: { engage: true, protocolRun: true }
-
-## 3. 冒烟顺序
-
-1. `labs_doctor`：确认 python/依赖/路径/版本身份；
-2. mock：`labs_status` → `labs_protocol list` → `labs_protocol run demo_scan` → `labs_wait`；
-3. 真机：只读 `labs_status` → 单键 `labs_set` + `labs_restore` → ≤10 shots →
-   `labs_data` → 一条协议。
-
+# 安装（DSH desktop profile）
+
+## 0. 环境要求
+
+- DSH >= 0.2，Node.js ^22.19 或 >= 24。
+- Python >= 3.9。
+  - mock 模式：只需 numpy >= 1.23、h5py >= 3.8；
+  - 真机模式：用 labscript-suite 的 Python 环境（labscript、runmanager、
+    labscript_utils、zprocess 可导入）。
+  - 开发时实测：Python 3.11.0、numpy 2.2.5、h5py 3.13.0。
+
+## 1. 安装插件
+
+### 方式 A：从 npm 安装（推荐）
+
+在 DSH desktop profile 的 `package.json` 依赖里加：
+
+    "dsh-labscript": "^0.2.0"
+
+在 profile 目录执行 `pnpm install`，重启 DSH。升级时改版本号再 `pnpm install`。
+
+### 方式 B：本地 link（开发用）
+
+把仓库放到本机任意目录（下称 `<repo>`），在 DSH desktop profile 里 link 安装：
+
+1. 编辑 `%USERPROFILE%\.dsh\profiles\desktop\package.json`：
+
+       "dependencies": {
+         ...,
+         "dsh-labscript": "link:<repo>"
+       }
+
+   并在 `dsh.profile.bundles` 里加入 `"dsh-labscript"`。
+
+2. 在 profile 目录执行 `pnpm install`，重启 DSH。
+3. 新会话里应出现 9 个 `labs_*` 工具和 `labscript` skill。
+
+实验机建议固定 tag：`git checkout v0.2.0` 后再安装，避免 main 变动影响硬件行为。
+
+## 2. 配置
+
+优先在 DSH 里配置：侧边栏 → 插件 → dsh-labscript，填 backend、python、
+runmanager host/port、protocolsDir，保存后下一次工具调用生效（不用重启）。
+
+高级配置（scriptsFile、hard limits、postprocess、approval、pathMap、超时等）
+仍写在 profile 的 `cordis.patch.yml`：
+
+    - id: dsh-labscript
+      name: dsh-labscript
+      config:
+        scriptsFile: <path>/scripts.json
+        hardLimitsFile: <path>/hard_limits.json
+        postprocess:
+          entry: my_lab.analysis:analyze
+          pythonPaths: [<path>/my_lab]
+        approval: { engage: true, protocolRun: true }
+
+## 3. 冒烟顺序
+
+1. `labs_doctor`：确认 python/依赖/路径/版本身份；
+2. mock：`labs_status` → `labs_protocol list` → `labs_protocol run demo_scan` → `labs_wait`；
+3. 真机：只读 `labs_status` → 单键 `labs_set` + `labs_restore` → ≤10 shots →
+   `labs_data` → 一条协议。
+