dsh-labscript 0.2.8 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 0.3.0
+
+Implements the upstream request written from the field (labscript-suite workflow terms and
+`runmanager.remote` limits). No output field is renamed or removed.
+
+- `n_shots` is now documented and rendered as the authoritative shot count. The scan-axes line is
+  labelled a heuristic: runmanager expands list/array globals but passes tuples through, and an
+  expansion setting of `none` turns an array into a non-axis; neither is visible through
+  `runmanager.remote`. A mismatch now reads "n_shots is authoritative (a tuple global or an
+  expansion setting of none is not an axis)" instead of printing two numbers with no verdict. The
+  bridge's axis guess ignores tuples and dicts, and the mock backend follows the same rule (it used
+  to multiply tuples in, pinning the wrong semantics into the tests).
+- Skill and tool descriptions no longer tell the agent to "read the runmanager output": compilation
+  errors appear only in runmanager's output tab (the compiler subprocess writes its traceback to
+  stderr and runmanager redirects it to an in-memory Qt widget), so the instruction is now to say
+  that no shot file appeared, ask the operator to paste the tab, and not guess the cause.
+  `labs_set` also warns that a global name must not shadow a Python builtin or a
+  `from labscript import *` name: runmanager accepts it and labscript fails at compile time.
+- `compiled_not_executed` explains the other official causes: BLACS may keep a shot out of its
+  queue (the shot's connection table must be a subset of the lab connection table) or put it back
+  at the head after a device programming timeout; all of that is visible only in the BLACS GUI.
+  More shot files than expected now points at a changed panel or BLACS Repeat all / Repeat last,
+  which re-runs completed shots without creating new files.
+- `labs_status` reports `shuffle` (from `get_shuffle`; "unknown" when that runmanager version has
+  no such method). With shuffle on, shot order is not axis order: read each shot's parameters from
+  its own h5 globals.
+- runmanager host/port/timeout default to labscript's labconfig when unset, resolved by
+  `runmanager.remote.Client` itself (`[servers]/[ports]/[timeouts]`, port 42523, timeout 60 s);
+  configured values still win. The Plugins page now leaves host/port blank for that reason, and
+  clearing them hands the endpoint back to labconfig. `labs_doctor` prints the effective endpoint
+  and whether it came from config or labconfig.
+- mock backend: `mock.errorInGlobals` makes `error_in_globals` true so the engagement refusal can
+  be tested, and `mock.shuffle` sets the reported shuffle flag.
+- Docs: a terminology table maps the plugin's short names to the suite's (shot output folder,
+  sequence, shot file, parameter space/axes, acquired data) without renaming fields.
+- Compilation logs stay out of scope: nothing about a compilation failure is written anywhere
+  readable (see README), so no `labs_compile_log` was added; a guessed diagnosis would be worse
+  than none.
+- Tests: 33 python + 47 node (axis heuristic with tuples/dicts, mock error/shuffle switches,
+  labconfig client defaults, extra shot files, scan/shuffle rendering, endpoint clearing).
+
 ## 0.2.8
 
 Fixes from a real labscript-suite session (2026-11-14, 145 tool calls, no run submitted by the

package/README.md

@@ -40,9 +40,9 @@ config). Run `labs_doctor` first if anything looks misconfigured.
 | 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_status | Read the panel: labscript, globals, n_shots, error_in_globals, run_shots, shuffle, 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_engage | Submit the current panel as one sequence (shot files to BLACS); 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 |
@@ -84,7 +84,7 @@ Add one row to your DSH profile patch (see examples/config.example.yml):
       config:
         python: /path/to/labscript-suite/python
         backend: labscript
-        runmanager: { host: 127.0.0.1, port: 42523, timeoutS: 10 }
+        # runmanager: { host: 127.0.0.1, port: 42523, timeoutS: 10 }   # optional; labconfig otherwise
         protocolsDir: /path/to/protocols
         scriptsFile: /path/to/scripts.json
         hardLimitsFile: /path/to/hard_limits.json
@@ -103,6 +103,12 @@ already mapped: `labs_status`, `labs_engage`, `labs_wait`, `labs_data` and
 `labs_protocol` show local paths, while `run_folder` keeps the raw runmanager
 value next to `mapped_run_folder`.
 
+`runmanager` may be omitted: host, port and timeout then come from labscript's labconfig
+(`[servers] runmanager`, `[ports] runmanager` — default 42523 — and
+`[timeouts] communication_timeout` — default 60 s), the same way `runmanager.remote.Client`
+resolves them. Configured values override labconfig. The Plugins page leaves host/port blank
+for that reason; typing them pins them.
+
 `engage` controls how a submitted run is watched: `timeoutS` (default 900) is the
 total wait budget of one `labs_wait`, `noShotS` (default 25) makes the wait return
 early with a diagnosis when no shot appeared, `staleS` (default 180) drops a pending
@@ -133,8 +139,8 @@ is not a physics simulation.
 ## Development
 
     npm install              # only runtime dependency: yaml
-    npm test                 # node --test, 46 tests (fake bridge, no python needed)
-    python python/tests/run_tests.py   # 28 tests (needs numpy + h5py)
+    npm test                 # node --test, 47 tests (fake bridge, no python needed)
+    python python/tests/run_tests.py   # 33 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.
@@ -144,6 +150,20 @@ A fresh clone must run `npm install` before `npm test`; the CI workflow does thi
 - docs/README.zh.md - Chinese guide
 - docs/INSTALL.zh.md - local DSH profile install
 
+## Terminology
+
+The plugin uses short names; the labscript suite uses its own. Both describe the same objects,
+and the field names are unchanged:
+
+| plugin | labscript suite |
+|---|---|
+| run folder, `run_folder` | **shot output folder** (one **sequence**'s shot files) |
+| run, engage | one **sequence**: one shot file per point in the parameter space |
+| shot h5, `n_h5` | **shot file** (`.h5`) |
+| scan, scan axis | **parameter space**, **axis**, **expansion** (`none`/`outer`/zip group/`auto`) |
+| `n_executed` | shots that **acquired data** (`images/`, `results/`) |
+| postprocess | lyse **single-shot / multi-shot routine** |
+
 ## Boundaries
 
 - Real hardware: engage/protocol run ask for a DSH approval (one-shot) when the
@@ -154,6 +174,23 @@ A fresh clone must run `npm install` before `npm test`; the CI workflow does thi
   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.
+- The panel's `n_shots` is the authoritative shot count. The reported scan axes and
+  `n_shots_from_arrays` are a heuristic: runmanager expands list/array globals but passes
+  tuples through unwrapped, and an expansion setting of `none` turns an array back into a
+  non-axis; neither is visible through the remote API. When the two numbers disagree,
+  `n_shots` wins and the difference is reported as such.
+- `labs_status` reports `shuffle`. With shuffle on, shot order is not axis order, so each
+  shot's parameters must be read from its own h5 globals.
+- Compilation errors appear only in runmanager's output tab. The compiler subprocess writes the
+  traceback to its stderr, which runmanager redirects to that tab (an in-memory Qt widget);
+  `runmanager.remote` has no interface for it and nothing is written to a log file. The plugin
+  therefore reports that no shot file appeared and asks for the tab to be pasted, instead of
+  guessing why compilation failed.
+- A shot file exists as soon as a sequence starts; `images/` and `results/` are written only
+  after execution, which is what `n_executed` counts. BLACS can keep a shot out of its queue
+  (its connection table must be a subset of the lab connection table) or put it back at the head
+  after a device programming timeout, and BLACS Repeat all / Repeat last re-runs completed shots
+  without creating new files; none of that is visible to the plugin.
 - 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.

package/docs/README.zh.md

@@ -27,6 +27,9 @@ hard limits 全部通过配置接入。
 - 要求：DSH >= 0.2、Node ^22.19/24；Python >= 3.9。mock 模式只要 numpy+h5py；
   真机用 labscript-suite 环境。详见 docs/INSTALL.zh.md。
 - 默认 backend 是 mock-labscript；真机必须显式配置 backend: labscript。
+- runmanager 的 host/port/timeout 可以不填：不填就读 labscript 的 labconfig
+  （`[servers]/[ports] runmanager`，端口默认 42523；`[timeouts] communication_timeout`,
+  默认 60 s），和 runmanager 自己的客户端一致；填了就以配置为准。插件页留空即走 labconfig。
 - 安装后在 DSH 插件页填 backend、python、runmanager host/port、protocolsDir；
   其余高级配置（scriptsFile、hard limits、postprocess、approval、pathMap、
   engage 的超时/早退参数）写在 profile 的 cordis.patch.yml。
@@ -62,4 +65,15 @@ postprocess 是后处理：跑完后调用配置的 Python 函数（entry + pyth
   丢弃并报 dropped_stale_pending，不再永久挡住提交；RUN_PENDING 的错误里也会写清年龄和两种出路。
 - 配了 pathMap 时 pending 记录映射后的目录（原始路径保留为 remote_run_folder），所以
   labs_wait 传映射后目录或原始目录都能对上，不会再说"run folder does not exist"。
+- **shot 数以面板 `n_shots` 为准**。工具报的 scan axes / n_shots_from_arrays 只是猜测：
+  runmanager 会把 list/array 展开成轴，但 **tuple 不展开**，而且 expansion 被设成 `none` 时
+  数组就不再是轴——这两件事从 remote 接口都看不到。两个数字不一致时按 `n_shots` 报，并说明差别。
+- `labs_status` 会显示 `shuffle`。shuffle 打开时 shot 顺序不等于轴顺序，每发参数要从该发 h5 的
+  globals 读，不要按序号推。
+- 编译报错只出现在 runmanager 的 output tab：编译器子进程把回溯写到自己的 stderr，runmanager
+  把它转到这个 Qt 界面上（内存里，不落盘），`runmanager.remote` 没有任何读取接口。所以插件只能报
+  "n 秒内没有出现 shot 文件"，并请操作员贴 output tab，不猜原因。
+- shot 文件在 sequence 开始时就写出来了；`images/`、`results/` 是执行后才写，`n_executed`
+  数的就是这个。BLACS 可能因为连接表不是实验室连接表的子集而拒收、或设备编程超时把 shot 放回队首，
+  BLACS 的 Repeat all / Repeat last 会把跑完的 shot 重跑而不新增文件——这些插件都看不到。
 

package/examples/config.example.yml

@@ -19,7 +19,9 @@
 #   config:
 #     python: /path/to/labscript-suite/python
 #     backend: labscript
-#     runmanager: { host: 127.0.0.1, port: 42523, timeoutS: 10 }
+#     # runmanager 可以不写：host/port/timeout 默认读 labscript 的 labconfig
+#     # （[servers]/[ports]/[timeouts]，端口默认 42523、超时默认 60 s），填了才覆盖。
+#     # runmanager: { host: 127.0.0.1, port: 42523, timeoutS: 10 }
 #     protocolsDir: /path/to/your/protocols
 #     scriptsFile: /path/to/scripts.json
 #     hardLimitsFile: /path/to/hard_limits.json

package/lib/client.js

@@ -78,8 +78,8 @@ window.__ModuleLoader__.load({
       const [version, setVersion] = useState('')
       const [backend, setBackend] = useState('mock-labscript')
       const [python, setPython] = useState('')
-      const [host, setHost] = useState('127.0.0.1')
-      const [port, setPort] = useState(42523)
+      const [host, setHost] = useState('')
+      const [port, setPort] = useState('')
       const [protocolsDir, setProtocolsDir] = useState('')
       const [busy, setBusy] = useState('')
       const [message, setMessage] = useState(null)
@@ -94,8 +94,8 @@ window.__ModuleLoader__.load({
           const current = payload.config || {}
           setBackend(current.backend || 'mock-labscript')
           setPython(current.python || '')
-          setHost((current.runmanager && current.runmanager.host) || '127.0.0.1')
-          setPort((current.runmanager && current.runmanager.port) || 42523)
+          setHost((current.runmanager && current.runmanager.host) || '')
+          setPort(current.runmanager && current.runmanager.port ? String(current.runmanager.port) : '')
           setProtocolsDir(current.protocolsDir || '')
         } catch (error) {
           setMessage({ kind: 'err', text: error.message })
@@ -118,7 +118,7 @@ window.__ModuleLoader__.load({
             body: JSON.stringify({
               backend,
               python,
-              runmanager: { host, port: Number(port) },
+              runmanager: { host: host.trim(), port: port === '' ? '' : Number(port) },
               protocolsDir,
             }),
           })
@@ -160,8 +160,8 @@ window.__ModuleLoader__.load({
             ),
           ),
           h(Row, { label: 'python', hint: '真机填 labscript-suite 环境的 python；模拟器只需 numpy+h5py。' }, h('input', { type: 'text', value: python, onChange: (event) => setPython(event.target.value) })),
-          h(Row, { label: 'runmanager host' }, h('input', { type: 'text', value: host, onChange: (event) => setHost(event.target.value) })),
-          h(Row, { label: 'runmanager port' }, h('input', { type: 'number', value: port, onChange: (event) => setPort(event.target.value) })),
+          h(Row, { label: 'runmanager host', hint: '留空则用 labscript 的 labconfig（[servers] runmanager）。' }, h('input', { type: 'text', value: host, placeholder: 'labconfig 里的地址', onChange: (event) => setHost(event.target.value) })),
+          h(Row, { label: 'runmanager port', hint: '留空则用 labconfig（[ports] runmanager，默认 42523）。' }, h('input', { type: 'number', value: port, placeholder: 'labconfig', onChange: (event) => setPort(event.target.value) })),
         ),
         h('section', { className: 'lsc-section' },
           h('h3', null, '实验'),

package/lib/skill.js

@@ -10,8 +10,11 @@ export const SKILL_CONTENT = [
   'not your memory, is the truth. Never guess a global value or a scan axis.',
   '',
   '## Before any write',
-  '1. Call labs_status. Confirm the loaded labscript, n_shots, error_in_globals, run_shots',
-  '   and the keys you are about to touch.',
+  '1. Call labs_status. Confirm the loaded labscript, n_shots, error_in_globals, run_shots,',
+  '   shuffle and the keys you are about to touch. n_shots is the authoritative shot count:',
+  '   the scan axes line is only a heuristic (runmanager does not expand tuples, and an',
+  '   expansion setting of none makes an array a non-axis), so report a difference instead',
+  '   of recomputing the count yourself.',
   '2. Real hardware: the user must approve this turn before panel writes, engage or abort.',
   '   The plugin asks for its own one-shot approval on engage/protocol run in the real',
   '   backend; that approval does not replace the user conversation requirement.',
@@ -21,13 +24,19 @@ export const SKILL_CONTENT = [
   '## Running',
   '- labs_set writes the panel. It does not run anything. Always pass note: one sentence',
   '  saying what this batch is for (it is written to the event log).',
-  '- labs_engage only reports that runmanager accepted the submission; it cannot see',
-  '  compile errors. If nothing runs, the next labs_wait says so (see Stop rules).',
+  '- One engage submits one sequence: runmanager writes one shot file per point into the',
+  '  shot output folder (called run folder in these tools) and hands each file to BLACS.',
   '- labs_engage submits a run and returns immediately with n_shots_at_submit and',
   '  expected_n_shots. Do not poll in a loop; when the user wants results, call labs_wait.',
   '  After submitting you may end the turn or do independent work.',
-  '- n_h5 counts shot h5 files, which labscript writes before compiling each shot; only',
+  '- labs_engage cannot see compilation errors: runmanager shows them only in its output',
+  '  tab, which runmanager.remote cannot read. If nothing runs, see Stop rules.',
+  '- n_h5 counts shot files, which labscript writes before compiling each shot; only',
   '  n_executed (or the diagnosis) says whether shots actually acquired data.',
+  '- shuffle true means shot order is not axis order: read each shot parameters from its',
+  '  own h5 globals, never from the shot index.',
+  '- Never name a global like a Python builtin or a name from "from labscript import *":',
+  '  runmanager accepts it, labscript fails at compile time, and only the output tab shows it.',
   '- labs_protocol run submits a fixed protocol; labs_wait finalizes it (postprocess,',
   '  finish write-back, panel restore).',
   '- backend defaults to mock-labscript; real hardware is only used when the config says',
@@ -40,22 +49,28 @@ export const SKILL_CONTENT = [
   '  write touched (pass full=true for the whole panel), so concurrent edits elsewhere are kept.',
   '',
   '## Reading results',
-  '- labs_data reads the run folder HDF5: globals of the first shot and, with scan: a',
-  '  per-shot table. HDF5 is authoritative; the panel is only intermediate state.',
+  '- labs_data reads the shot files HDF5: globals of the first shot and, with scan: a',
+  '  per-shot table. HDF5 is authoritative; the panel is only intermediate state. images/',
+  '  and results/ are written only after execution.',
   '- Report facts: run folder, expected vs actual shots, postprocess numbers, warnings.',
   '  If a number is missing, say so instead of inventing one.',
   '',
   '## Stop rules',
   '- error_in_globals true: fix or ask; never engage.',
   '- labs_wait returns before the timeout with diagnosis no_shots or compile_stalled when no',
-  '  shot appeared for config.engage.noShotS seconds (default 25). That usually means runmanager',
-  '  aborted the compilation: read the runmanager output, then labs_abort, or labs_wait again if',
-  '  you expect a slow compile. A submission that never produced a shot is dropped by the next',
-  '  labs_engage once it is config.engage.staleS seconds old (default 180) and reported as',
-  '  dropped_stale_pending.',
-  '- diagnosis=compiled_not_executed, or timed_out with h5 files but no acquisition data: the',
-  '  shots were compiled but BLACS may be paused/not executing. Check BLACS and the panel, then',
-  '  abort or ask; do not resubmit blindly.',
+  '  shot file appeared for config.engage.noShotS seconds (default 25). Compilation errors are',
+  '  visible only in runmanager output tab, which this tool cannot read: say exactly that, ask',
+  '  the operator to paste the tab, and do not guess the cause or resubmit blindly. Call',
+  '  labs_wait again only if you expect a slow compile. A submission that never produced a shot',
+  '  is dropped by the next labs_engage once it is config.engage.staleS seconds old (default',
+  '  180) and reported as dropped_stale_pending.',
+  '- diagnosis=compiled_not_executed, or timed_out with shot files but no acquisition data:',
+  '  BLACS did not run that shot. It may be paused, may have refused the shot because its',
+  '  connection table is not a subset of the lab connection table, or a device group may have',
+  '  failed to program within 5 minutes (BLACS then pauses the queue and puts the shot back at',
+  '  its head). None of this is visible to this tool: look at the BLACS GUI, then abort or ask.',
+  '- More shots finished than expected: check the panel n_shots and expansion settings first,',
+  '  then BLACS Repeat all / Repeat last, which re-run existing shot files.',
   '- A run is already pending: wait or abort before submitting another.',
 ].join(String.fromCharCode(10))
 

package/lib/store.mjs

@@ -34,8 +34,13 @@ export function normalizeUiConfig(input) {
     throw new Error('backend must be one of ' + BACKENDS.join(', ') + ', got: ' + backend)
   }
   const runmanager = source.runmanager && typeof source.runmanager === 'object' ? source.runmanager : {}
-  const port = Number(runmanager.port || 42523)
-  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('runmanager.port must be 1-65535')
+  // host/port stay optional: when they are not stored, the bridge lets runmanager.remote
+  // resolve them from labscript's labconfig ([servers]/[ports] runmanager), the same way
+  // the runmanager GUI does. Storing the old hardcoded defaults here would pin them.
+  const host = runmanager.host === undefined || runmanager.host === null ? '' : String(runmanager.host).trim()
+  const portText = runmanager.port === undefined || runmanager.port === null ? '' : String(runmanager.port).trim()
+  const port = portText === '' ? undefined : Number(portText)
+  if (port !== undefined && (!Number.isInteger(port) || port < 1 || port > 65535)) throw new Error('runmanager.port must be 1-65535')
   const timeoutS = runmanager.timeoutS === undefined || runmanager.timeoutS === null || runmanager.timeoutS === ''
     ? undefined
     : Number(runmanager.timeoutS)
@@ -45,12 +50,11 @@ export function normalizeUiConfig(input) {
   const out = {
     backend,
     python: String(source.python || '').trim(),
-    runmanager: {
-      host: String(runmanager.host || '127.0.0.1').trim(),
-      port,
-    },
+    runmanager: {},
     protocolsDir: String(source.protocolsDir || '').trim(),
   }
+  if (host !== '') out.runmanager.host = host
+  if (port !== undefined) out.runmanager.port = port
   if (timeoutS !== undefined) out.runmanager.timeoutS = timeoutS
   return out
 }
@@ -75,9 +79,13 @@ export function readUiConfig(home) {
 export function writeUiConfig(input, home) {
   const previous = readUiConfig(home).config || {}
   const patch = input && typeof input === 'object' ? input : {}
-  const config = normalizeUiConfig(Object.assign({}, previous, patch, {
-    runmanager: Object.assign({}, previous.runmanager || {}, patch.runmanager || {}),
-  }))
+  const runmanager = Object.assign({}, previous.runmanager || {}, patch.runmanager || {})
+  // An empty host/port means "unset, ask labconfig": drop the stored key instead of
+  // keeping the previous value, so a lab that moves runmanager can clear it.
+  for (const key of Object.keys(runmanager)) {
+    if (runmanager[key] === '' || runmanager[key] === null || runmanager[key] === undefined) delete runmanager[key]
+  }
+  const config = normalizeUiConfig(Object.assign({}, previous, patch, { runmanager }))
   const file = uiConfigPath(home)
   fs.mkdirSync(path.dirname(file), { recursive: true })
   const temp = file + '.' + process.pid + '.' + Date.now() + '.tmp'

package/lib/tools.js

@@ -67,14 +67,21 @@ function globalLines(args, value) {
   return out
 }
 
+// runmanager decides the shot count from the expansion settings, which runmanager.remote
+// cannot read: a tuple is not an axis and an array can be switched to expansion "none".
+// The panel's n_shots is therefore the only authoritative number; this line is a hint.
 function scanLine(value) {
   const axes = value.scan_axes && typeof value.scan_axes === 'object' ? value.scan_axes : {}
   const names = Object.keys(axes).sort()
   const product = value.n_shots_from_arrays
-  const mismatch = typeof product === 'number' && typeof value.n_shots === 'number' && value.n_shots !== product
+  const known = typeof value.n_shots === 'number'
+  const mismatch = typeof product === 'number' && known && value.n_shots !== product
   if (names.length === 0 && !mismatch) return ''
   const detail = names.length ? names.map((key) => key + '=' + axes[key]).join(', ') : 'none'
-  return 'scan axes: ' + detail + '  n_shots_from_arrays=' + product + (mismatch ? '  (panel n_shots=' + value.n_shots + ' differs)' : '')
+  const verdict = mismatch
+    ? '  product ' + product + ' != n_shots ' + value.n_shots + ': n_shots is authoritative (a tuple global or an expansion setting of none is not an axis)'
+    : '  product ' + product + '  n_shots ' + (known ? value.n_shots : '?') + ' (authoritative)'
+  return 'scan axes (heuristic): ' + detail + verdict
 }
 
 function resultsLine(value) {
@@ -248,7 +255,7 @@ export function registerTools(ctx, runtime) {
 
   ctx.tools.register({
     name: 'labs_status',
-    description: 'Read the labscript runmanager panel: loaded labscript, globals (evaluated; raw expressions with raw=true), n_shots, error_in_globals, run_shots, shot output folder, pending run progress, and the panel snapshot directory. Read-only; call this before any write. Pass keys=[...] (leaf global names; UI group names are not globals) to print the selected panel values (240 chars each; raw=true prints the raw expression), missing keys are shown as <missing>; keys=["*"] prints every global. scan axes lists array-valued globals (their lengths multiply to n_shots_from_arrays) and a differing panel n_shots is flagged. The shot output folder is the folder the NEXT run will use; it does not exist until engage. Paths in the output are already mapped for this machine through pathMap; do not map them again.',
+    description: 'Read the labscript runmanager panel: loaded labscript, globals (evaluated; raw expressions with raw=true), n_shots, error_in_globals, run_shots, shuffle, shot output folder (called run folder in this tool: where the NEXT engage writes its shot files; it does not exist until engage), pending run progress, and the panel snapshot directory. Read-only; call this before any write. Pass keys=[...] (leaf global names; UI group names are not globals) to print the selected panel values (240 chars each; raw=true prints the raw expression), missing keys are shown as <missing> (the global is in an inactive group or misspelled); keys=["*"] prints every global. scan axes is a heuristic: it counts array-valued globals and their lengths multiply to n_shots_from_arrays, but runmanager does not expand tuples and an expansion setting of none turns an array into a non-axis, neither of which is visible from the remote API. n_shots is authoritative: when the two differ, report n_shots and say that at least one array-valued global is not an axis. shuffle true means shot order does not follow the axis order. Paths in the output are already mapped for this machine through pathMap; do not map them again.',
     parameters: {
       type: 'object',
       properties: {
@@ -262,7 +269,7 @@ export function registerTools(ctx, runtime) {
       'backend: ' + value.backend + '  plugin: v' + runtime.version,
       'labscript: ' + value.labscript,
       'shot output: ' + value.shot_output_folder,
-      'n_shots: ' + value.n_shots + '  error_in_globals: ' + value.error_in_globals + '  run_shots: ' + value.run_shots,
+      'n_shots: ' + value.n_shots + '  error_in_globals: ' + value.error_in_globals + '  run_shots: ' + value.run_shots + '  shuffle: ' + (value.shuffle === undefined || value.shuffle === null ? 'unknown' : value.shuffle),
       progressLine(value.last_run),
       'panel history: ' + (value.panel_history ? value.panel_history.dir + ' (' + value.panel_history.count + ' snapshots)' : 'n/a'),
       scanLine(value),
@@ -282,7 +289,7 @@ export function registerTools(ctx, runtime) {
 
   ctx.tools.register({
     name: 'labs_set',
-    description: 'Write runmanager panel globals. One call can do the whole step: values are JSON scalars (bool/number/string); with raw=true a string value is written as an expression (e.g. np.arange(0.5, 6.7, 0.2)) while bool/number values are still converted normally (true -> True, 2.72 -> 2.72), so scalars, an expression scan axis and reps=N can be combined. reps=N writes the configured repetition global as np.arange(N). A full panel snapshot is taken before the write. Does not run anything.',
+    description: 'Write runmanager panel globals. One call can do the whole step: values are JSON scalars (bool/number/string); with raw=true a string value is written as an expression (e.g. np.arange(0.5, 6.7, 0.2)) while bool/number values are still converted normally (true -> True, 2.72 -> 2.72), so scalars, an expression scan axis and reps=N can be combined. reps=N writes the configured repetition global as np.arange(N). A list global becomes a scan axis only if runmanager actually expands it (a tuple is passed through whole, and an expansion setting of none drops the axis). A global name must not shadow a Python builtin or a name from "from labscript import *": runmanager accepts the name, labscript fails at compile time, and that failure is visible only in runmanager output tab. A full panel snapshot is taken before the write. Does not run anything.',
     parameters: {
       type: 'object',
       properties: {
@@ -312,7 +319,7 @@ export function registerTools(ctx, runtime) {
 
   ctx.tools.register({
     name: 'labs_engage',
-    description: 'Submit the current panel for a run (compiles and sends to BLACS). Returns immediately with run_folder, n_shots_at_submit and expected_n_shots; use labs_wait later to wait for completion. Refuses when error_in_globals is true or another run is still pending; a pending run that produced no shot at all for config.engage.staleS (default 180 s) is dropped and reported as dropped_stale_pending.',
+    description: 'Submit the current panel as one sequence: runmanager writes one shot file per point and hands it to BLACS (this is the "shot output folder", called run_folder in this tool). Returns immediately with run_folder, n_shots_at_submit and expected_n_shots; use labs_wait later to wait for completion. It cannot see compilation errors: runmanager shows those only in its output tab. Refuses when error_in_globals is true or another run is still pending; a pending run that produced no shot at all for config.engage.staleS (default 180 s) is dropped and reported as dropped_stale_pending.',
     parameters: {
       type: 'object',
       properties: {
@@ -356,7 +363,7 @@ export function registerTools(ctx, runtime) {
 
   ctx.tools.register({
     name: 'labs_wait',
-    description: 'Wait for the pending run to finish (blocking, timeout in seconds). If the pending run came from labs_protocol run, this call also finalizes it: postprocess, finish write-back of panel and calibration history, and panel restore. Returns expected vs actual shots and, for protocols, the postprocess/finish/restore results. Returns early with diagnosis no_shots or compile_stalled when no shot h5 appears for config.engage.noShotS seconds (default 25): the compilation probably aborted, so check runmanager and call labs_wait again only if you expect a slow compile. A run folder that does not exist and is not the pending run of this session fails immediately instead of waiting.',
+    description: 'Wait for the pending run (sequence) to finish (blocking, timeout in seconds). If it came from labs_protocol run, this call also finalizes it: postprocess, finish write-back of panel and calibration history, and panel restore. Returns expected vs actual shot files and, for protocols, the postprocess/finish/restore results. Returns early with diagnosis no_shots or compile_stalled when no shot file appeared for config.engage.noShotS seconds (default 25): compilation errors are visible only in runmanager output tab, which this tool cannot read, so report exactly that and ask the operator to paste the tab; call labs_wait again only if you expect a slow compile. diagnosis compiled_not_executed means shot files exist but BLACS acquired no data: BLACS may be paused, may have refused the shot because its connection table is not a subset of the lab connection table, or a device group failed to program within 5 minutes (the queue then pauses and puts the shot back at its head) - all visible only in the BLACS GUI. More shot files than expected means the panel n_shots changed after submit, or BLACS Repeat all / Repeat last re-ran shots. A run folder that does not exist and is not the pending run of this session fails immediately instead of waiting.',
     parameters: {
       type: 'object',
       properties: {
@@ -483,7 +490,7 @@ export function registerTools(ctx, runtime) {
 
   ctx.tools.register({
     name: 'labs_data',
-    description: 'Read a run folder HDF5: first-shot globals (pass keys=[...] to print selected values, ["*"] for all), the results groups with results: true, and with scan: a per-shot scan axis summary (unique points, min/max, median step) plus the numeric result columns; pass limit to print up to 20 raw rows. Read-only. run_folder defaults to the pending run, else the last run submitted through this plugin (persisted across restarts); for a historical run pass its folder explicitly. A missing folder is an error: runmanager\'s shot output is the NEXT run folder and only exists after engage.',
+    description: 'Read a run folder (shot output folder) HDF5: first-shot globals (pass keys=[...] to print selected values, ["*"] for all), the results groups with results: true, and with scan: a per-shot axis summary (unique points, min/max, median step) plus the numeric result columns; pass limit to print up to 20 raw rows. Each shot file holds the evaluated globals of that shot, its hardware commands and, after execution, images/ and results/ - a shot with no images/results was not executed. With shuffle on, read each shot\'s parameters from its own file instead of assuming axis order. Read-only. run_folder defaults to the pending run, else the last run submitted through this plugin (persisted across restarts); for a historical run pass its folder explicitly. A missing folder is an error: the shot output folder is the NEXT sequence\'s folder and only exists after engage.',
     parameters: {
       type: 'object',
       properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-labscript",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "description": "Control labscript-suite experiments from DeepSeek Harness: runmanager globals and scans, submits and waits, YAML fixed-operation protocols with postprocess write-back, panel snapshots, a built-in mock backend and a read-only doctor.",
   "type": "module",
   "main": "lib/index.js",

package/python/bridge.py

@@ -211,6 +211,28 @@ def eval_panel_value(raw):
         return str(raw)
 
 
+def axis_length(value):
+    """Length of the axis runmanager expands from this global, or None.
+
+    Heuristic: runmanager's automatic expansion turns list/array globals into axes
+    ("outer") and passes tuples through whole, so a tuple is not an axis. Expansion
+    settings (none / zip group) are not visible from runmanager.remote, so a list that
+    was switched to "none" still looks like an axis here. The panel's n_shots is the
+    authoritative shot count; this is only a hint.
+    """
+    if isinstance(value, (str, bytes, dict, tuple)):
+        return None
+    if not hasattr(value, "__len__"):
+        return None
+    ndim = getattr(value, "ndim", None)
+    if ndim is not None:
+        return int(value.size) if ndim >= 1 else None
+    try:
+        return int(len(value))
+    except Exception:
+        return None
+
+
 def raw_repr(value):
     if isinstance(value, bool):
         return "True" if value else "False"
@@ -297,18 +319,39 @@ class LabscriptBackend(object):
             from runmanager.remote import Client
         except Exception as exc:
             raise BridgeError("BACKEND_UNAVAILABLE", "labscript python environment not importable: " + str(exc))
+        # Anything left unset is resolved by runmanager.remote.Client from labscript's
+        # labconfig ([servers] runmanager, [ports] runmanager, [timeouts]
+        # communication_timeout), the same way the runmanager GUI does it. Explicit
+        # config always wins.
         rm = self.config.get("runmanager") or {}
-        host = rm.get("host") or "127.0.0.1"
-        port = int(rm.get("port") or 42523)
-        timeout = float(rm.get("timeoutS") or 10)
+        kwargs = {}
+        if rm.get("host"):
+            kwargs["host"] = rm["host"]
+        if rm.get("port"):
+            kwargs["port"] = int(rm["port"])
+        if rm.get("timeoutS"):
+            kwargs["timeout"] = float(rm["timeoutS"])
+        try:
+            client = Client(**kwargs)
+        except Exception as exc:
+            raise BridgeError("BACKEND_UNAVAILABLE", "cannot create a runmanager client: " + type(exc).__name__ + ": " + str(exc))
         try:
-            client = Client(host=host, port=port, timeout=timeout)
             client.say_hello()
         except Exception as exc:
-            raise BridgeError("BACKEND_UNAVAILABLE", "runmanager not reachable at " + host + ":" + str(port) + ": " + str(exc))
+            raise BridgeError("BACKEND_UNAVAILABLE", "runmanager not reachable at " + str(getattr(client, "host", "?")) + ":" + str(getattr(client, "port", "?")) + ": " + str(exc))
         self._client = client
         return client
 
+    def endpoint(self):
+        """Where this client points, and whether the values came from config or labconfig."""
+        rm = self.config.get("runmanager") or {}
+        source = "config" if (rm.get("host") or rm.get("port")) else "labconfig"
+        try:
+            client = self.client()
+            return str(client.host) + ":" + str(client.port) + " (" + source + ", timeout " + str(client.timeout) + "s)"
+        except Exception as exc:
+            return "<unknown> (" + source + "): " + str(exc)
+
     def version(self):
         try:
             return str(self.client().get_version())
@@ -337,6 +380,13 @@ class LabscriptBackend(object):
         except Exception:
             return None
 
+    def shuffle(self):
+        # Older runmanager versions have no get_shuffle; report unknown instead of failing.
+        try:
+            return bool(self.client().get_shuffle())
+        except Exception:
+            return None
+
     def labscript_file(self):
         try:
             return self.client().get_labscript_file()
@@ -415,7 +465,9 @@ class MockBackend(object):
         panel = self.read_panel()
         if raw:
             return dict(panel)
-        return dict((k, jsonable(eval_panel_value(v))) for k, v in panel.items())
+        # Keep Python types (tuple vs list matters to the expansion rules); callers
+        # jsonable() values before they leave the bridge.
+        return dict((k, eval_panel_value(v)) for k, v in panel.items())
 
     def set_globals(self, values, raw=False):
         panel = self.read_panel()
@@ -425,17 +477,21 @@ class MockBackend(object):
         return dict((k, panel[k]) for k in values)
 
     def n_shots(self):
-        import numpy as np
         total = 1
         for value in self.get_globals(raw=False).values():
-            arr = np.asarray(value) if hasattr(value, "__len__") and not isinstance(value, str) else None
-            if arr is None or arr.ndim == 0:
+            length = axis_length(value)
+            if length is None or length <= 0:
                 continue
-            total *= max(1, int(arr.size))
+            total *= length
         return int(total)
 
     def error_in_globals(self):
-        return False
+        # Simulator switch: mock.errorInGlobals makes the mock panel report an evaluation
+        # error, so the GLOBALS_ERROR refusal path can be tested without real hardware.
+        return bool((self.config.get("mock") or {}).get("errorInGlobals"))
+
+    def shuffle(self):
+        return bool((self.config.get("mock") or {}).get("shuffle"))
 
     def run_shots(self):
         return True
@@ -452,11 +508,8 @@ class MockBackend(object):
         values = self.get_globals(raw=False)
         arrays = {}
         for key, value in values.items():
-            if isinstance(value, str):
-                continue
-            arr = np.asarray(value)
-            if arr.ndim >= 1 and arr.size > 1:
-                arrays[key] = arr
+            if (axis_length(value) or 0) > 1:
+                arrays[key] = np.asarray(value).ravel()
         total = 1
         for arr in arrays.values():
             total *= int(arr.size)
@@ -565,6 +618,10 @@ class HttpSimBackend(object):
     def run_shots(self):
         return True
 
+    def shuffle(self):
+        snap = self.snapshot()
+        return bool(snap.get("shuffle")) if "shuffle" in snap else None
+
     def labscript_file(self):
         return self.snapshot().get("labscript_file")
 
@@ -948,13 +1005,8 @@ def cmd_status(config, args):
     scan_axes = {}
     n_shots_from_arrays = 1
     for name, value in panel_values.items():
-        if isinstance(value, str) or not hasattr(value, "__len__"):
-            continue
-        try:
-            size = int(len(value))
-        except Exception:
-            continue
-        if size <= 1:
+        size = axis_length(value)
+        if size is None or size <= 1:
             continue
         scan_axes[str(name)] = size
         n_shots_from_arrays *= size
@@ -973,6 +1025,7 @@ def cmd_status(config, args):
         "n_shots": backend.n_shots(),
         "error_in_globals": backend.error_in_globals(),
         "run_shots": backend.run_shots(),
+        "shuffle": backend.shuffle() if hasattr(backend, "shuffle") else None,
         "panel_history": panel_history_info(config),
     }
     if raw:
@@ -1123,7 +1176,12 @@ def wait_for_run(config, run_folder, expected, timeout_s):
             if stable_since is None:
                 stable_since = time.time()
             elif time.time() - stable_since >= settle:
-                return result(True, False, "complete", time.time() - start)
+                hint = None
+                if want and len(shots) != want:
+                    hint = ("finished with " + str(len(shots)) + " shot files for expected_n_shots=" + str(want) +
+                            ": the panel's n_shots changed after submit, or shots were re-run (BLACS Repeat all / "
+                            "Repeat last re-executes existing shot files and does not create new ones).")
+                return result(True, False, "complete", time.time() - start, hint)
         else:
             stable_since = None
             if ready and executed is False:
@@ -1132,8 +1190,11 @@ def wait_for_run(config, run_folder, expected, timeout_s):
                 elif time.time() - compiled_since >= stall:
                     return result(
                         False, False, "compiled_not_executed", time.time() - start,
-                        "shots were compiled but show no acquisition data after " + str(int(stall)) +
-                        " s: BLACS may be paused / the queue may not be running, or the run is still being programmed. Check BLACS and the panel, then labs_abort if needed.")
+                        "shot files exist but show no acquisition data after " + str(int(stall)) + " s: BLACS may be "
+                        "paused, or it kept the shot out of the queue (its connection table must be a subset of the "
+                        "lab connection table) or a device group failed to program within 5 minutes (the queue then "
+                        "pauses and puts that shot back at its head), or the run is still being programmed. Check the "
+                        "BLACS GUI and the panel, then labs_abort if needed.")
             else:
                 compiled_since = None
         last_count = count
@@ -1160,7 +1221,9 @@ def wait_for_run(config, run_folder, expected, timeout_s):
                 hint = "only " + str(count) + " of " + str(expected) + " shots appeared before the timeout; the run may still be compiling or blocked."
             elif executed is False:
                 diagnosis = "compiled_not_executed"
-                hint = "shots were compiled but no acquisition data was found: BLACS may be paused or not executing the queue."
+                hint = ("shot files exist but no acquisition data was found: BLACS may be paused, may have refused the "
+                        "shot (connection table not a subset of the lab connection table) or re-queued it after a device "
+                        "programming timeout. Check the BLACS GUI.")
             else:
                 diagnosis = "partial"
                 hint = "shots appeared but the run was not confirmed complete before the timeout."
@@ -1512,7 +1575,7 @@ def cmd_doctor(config, args):
             probe = LabscriptBackend(config)
             client = probe.client()
             version = client.get_version() if hasattr(client, "get_version") else "unknown"
-            _add_check(checks, "runmanager", "ok", str(version))
+            _add_check(checks, "runmanager", "ok", str(version) + " at " + probe.endpoint())
             try:
                 _add_check(checks, "panel", "ok", "n_shots=" + str(probe.n_shots()) + ", run_shots=" + str(probe.run_shots()) + ", error_in_globals=" + str(probe.error_in_globals()))
             except Exception as exc:

package/python/tests/run_tests.py

@@ -9,6 +9,7 @@ import shutil
 import sys
 import tempfile
 import time
+import types
 
 HERE = os.path.dirname(os.path.abspath(__file__))
 sys.path.insert(0, os.path.dirname(HERE))
@@ -278,6 +279,120 @@ def test_wait_diagnosis_compiled_not_executed():
         shutil.rmtree(tmp, ignore_errors=True)
 
 
+def test_axis_heuristic_ignores_tuples_and_dicts():
+    """runmanager does not expand tuples, so the scan-axes hint must not count them."""
+    tmp = tempfile.mkdtemp(prefix="dsh-labscript-axis-")
+    try:
+        cfg = make_config(tmp)
+        out = bridge.cmd_set(cfg, {"values": {"pulse_shape": "(0.1, 0.2, 0.3)"}, "raw": True})
+        assert out["missing"] == [], out
+        status = bridge.cmd_status(cfg, {})
+        assert "pulse_shape" not in status["scan_axes"], status["scan_axes"]
+        assert status["n_shots"] == 1, status["n_shots"]
+        assert status["n_shots_from_arrays"] == 1, status["n_shots_from_arrays"]
+        # a list/array global is an axis, a dict is not
+        bridge.cmd_set(cfg, {"values": {"freq": "np.arange(0.5, 6.7, 0.2)", "shape": "{'a': 1, 'b': 2}"}, "raw": True})
+        status = bridge.cmd_status(cfg, {})
+        assert status["scan_axes"].get("freq") == 31, status["scan_axes"]
+        assert "shape" not in status["scan_axes"], status["scan_axes"]
+        assert status["n_shots"] == 31, status["n_shots"]
+        assert status["n_shots_from_arrays"] == 31, status["n_shots_from_arrays"]
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+
+
+def test_mock_error_in_globals_blocks_engage():
+    tmp = tempfile.mkdtemp(prefix="dsh-labscript-mock-error-")
+    try:
+        cfg = make_config(tmp)
+        assert bridge.cmd_status(cfg, {})["error_in_globals"] is False
+        cfg["mock"]["errorInGlobals"] = True
+        assert bridge.cmd_status(cfg, {})["error_in_globals"] is True
+        try:
+            bridge.cmd_engage(cfg, {})
+        except bridge.BridgeError as exc:
+            assert exc.code == "GLOBALS_ERROR", exc.code
+        else:
+            raise AssertionError("expected GLOBALS_ERROR")
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+
+
+def test_mock_reports_shuffle():
+    tmp = tempfile.mkdtemp(prefix="dsh-labscript-mock-shuffle-")
+    try:
+        cfg = make_config(tmp)
+        assert bridge.cmd_status(cfg, {})["shuffle"] is False
+        cfg["mock"]["shuffle"] = True
+        assert bridge.cmd_status(cfg, {})["shuffle"] is True
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+
+
+def test_real_client_uses_labconfig_defaults():
+    """Unset host/port/timeout must be resolved by runmanager.remote from labconfig."""
+    class FakeClient(object):
+        last = None
+
+        def __init__(self, **kwargs):
+            self.kwargs = kwargs
+            self.host = kwargs.get("host") or "localhost"
+            self.port = kwargs.get("port") or 42523
+            self.timeout = kwargs.get("timeout") or 60
+            FakeClient.last = self
+
+        def say_hello(self):
+            return "hello"
+
+        def get_shuffle(self):
+            return True
+
+    class NoShuffleClient(FakeClient):
+        def get_shuffle(self):
+            raise AttributeError("get_shuffle")
+
+    fake_remote = types.ModuleType("runmanager.remote")
+    fake_remote.Client = FakeClient
+    fake_package = types.ModuleType("runmanager")
+    fake_package.remote = fake_remote
+    saved = dict((name, sys.modules.get(name)) for name in ("runmanager", "runmanager.remote"))
+    sys.modules["runmanager"] = fake_package
+    sys.modules["runmanager.remote"] = fake_remote
+    try:
+        bare = bridge.LabscriptBackend({})
+        client = bare.client()
+        assert client.kwargs == {}, client.kwargs
+        assert bare.shuffle() is True
+        explicit = bridge.LabscriptBackend({"runmanager": {"host": "10.0.0.5", "port": 43000, "timeoutS": 25}})
+        assert explicit.client().kwargs == {"host": "10.0.0.5", "port": 43000, "timeout": 25.0}
+        assert "10.0.0.5" in explicit.endpoint() and "config" in explicit.endpoint()
+        fake_remote.Client = NoShuffleClient
+        assert bridge.LabscriptBackend({}).shuffle() is None
+    finally:
+        for name, module in saved.items():
+            if module is None:
+                sys.modules.pop(name, None)
+            else:
+                sys.modules[name] = module
+
+
+def test_wait_reports_extra_shot_files():
+    tmp = tempfile.mkdtemp(prefix="dsh-labscript-extra-shots-")
+    try:
+        cfg = make_config(tmp)
+        cfg["engage"] = {"timeoutS": 5, "pollS": 0.05, "settleS": 0.1}
+        run_dir = os.path.join(tmp, "extra_run")
+        os.makedirs(run_dir, exist_ok=True)
+        for index in range(4):
+            write_shot(os.path.join(run_dir, "shot_000%d.h5" % index), executed=True)
+        result = bridge.wait_for_run(cfg, run_dir, 2, 4)
+        assert result["complete"] is True, result
+        assert result["n_h5"] == 4, result
+        assert "Repeat all" in result["hint"], result
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+
+
 def write_shot(path, executed):
     """Write a shot h5 like labscript does: globals first, acquisition data later."""
     import h5py