dsh-labscript 0.2.7 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,77 @@
 # 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
+plugin). Each defect was reproduced against the stock runmanager source before the fix.
+
+- Fix: labs_set failed with "TypeError: 'NoneType' object is not iterable" after the write had
+  already landed. runmanager's set_globals RPC is a side-effect call whose handler returns None,
+  and the bridge fed that reply to dict(). It now reports the requested values and lets the
+  readback decide success. When a write really fails, the error carries `landed` (what the panel
+  holds now) and the hint says to read the keys back instead of claiming the panel may be half
+  written and pointing at labs_restore.
+- Fix: labs_wait blocked for the whole timeout when compilation aborted. It returns after
+  engage.noShotS seconds (default 25) with diagnosis no_shots (no shot file appeared at all) or
+  compile_stalled (files stopped appearing), so the runmanager compile error can be read instead
+  of waiting 5-15 minutes. The hint says to call labs_wait again if a slow compile is expected.
+- Fix: a pending run that never produced a shot blocked labs_engage forever. A pending submission
+  with zero shots and older than engage.staleS (default 180 s) is dropped and reported as
+  dropped_stale_pending; the RUN_PENDING error now states the run's age and both ways out.
+- Fix: with pathMap configured, labs_wait(run_folder=<the folder labs_engage printed>) failed with
+  RUN_FOLDER_MISSING: the pending run kept the unmapped path and the wait compared strings. Pending
+  state now stores the mapped folder (raw kept as remote_run_folder) and both forms match.
+- Fix: shot h5 files that only hold compiled globals were counted as progress, so h5=1/64 looked
+  like "a shot ran". Progress reports n_h5 (files) and n_executed (shots with acquisition data,
+  located by binary search over the file order), completion requires acquisition data in the last
+  shot, and labs_status renders executed=.
+- labs_protocol show prints the closest key names for plan keys missing from the loaded labscript
+  (previously only the run path did), so stale protocols can be renamed without guessing.
+- labs_set description: one call can mix scalars, an expression scan axis and reps=N.
+- Tests: 28 python + 46 node, adding a client whose set_globals returns None, a stalled
+  compilation, a stale zero-shot pending run, mapped/raw pending folders and the show suggestions.
+
 ## 0.2.7
 
 - Fix: labs_wait no longer fails with "value is not lossless JSON". Tool results must be

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,20 @@ 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
+submission that never produced a single shot, `pollS`, `settleS` and `stallS` tune the
+polling and the compiled-not-executed detection.
+
+    engage: { timeoutS: 900, noShotS: 25, staleS: 180, stallS: 20 }
+
 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.
@@ -125,8 +139,8 @@ is not a physics simulation.
 ## Development
 
     npm install              # only runtime dependency: yaml
-    npm test                 # node --test, 40 tests (fake bridge, no python needed)
-    python python/tests/run_tests.py   # 22 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.
@@ -136,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
@@ -146,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.
@@ -153,9 +198,19 @@ A fresh clone must run `npm install` before `npm test`; the CI workflow does thi
   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.
+- labs_wait reports a diagnosis (complete, no_shots, compile_stalled, compiling,
+  compiled_not_executed, partial). no_shots and compile_stalled come back before the
+  timeout when nothing new appeared for engage.noShotS seconds: runmanager probably
+  aborted the compilation, so read its output. compiled_not_executed means shots were
+  compiled but show no acquisition data yet; BLACS may be paused or not executing the queue.
+- labs_engage only reports that runmanager accepted the submission; compilation errors are
+  invisible to it. A pending submission with no shots at all is dropped after
+  engage.staleS seconds and reported as dropped_stale_pending, so a dead run does not block
+  the next one forever.
+- Shot h5 files exist before they are executed: progress reports n_h5 (files) and
+  n_executed (shots with acquisition data), and completion requires acquisition data.
+- The pending run is stored under the pathMap-mapped folder (the raw runmanager path is kept
+  as remote_run_folder), so labs_wait accepts whichever of the two an agent quotes back.
 - Real runmanager engage does not return a run folder; the bridge captures the
   output folder before engage and reports it as the run folder. That shot output
   folder is the NEXT run's folder and does not exist until engage, so labs_data

package/docs/README.zh.md

@@ -11,7 +11,7 @@ hard limits 全部通过配置接入。
 |---|---|
 | labs_doctor | 只读诊断：python、numpy/h5py、labscript/runmanager、路径、审批、版本 |
 | labs_status | 读面板：labscript、globals、n_shots、error_in_globals、run_shots、pending 进度 |
-| labs_set | 写面板（标量 / raw 表达式 / reps），写前全量快照；不运行 |
+| labs_set | 写面板（标量 / raw 表达式 / reps 可一次混用），写前全量快照；不运行 |
 | labs_engage | 提交当前面板，立即返回 n_shots_at_submit 与 expected_n_shots |
 | labs_wait | 等待 pending run（可超时）；若是协议则收尾：postprocess → finish 写回 → restore |
 | labs_abort | 中止当前提交（不排队，不会被 labs_wait 堵住） |
@@ -27,9 +27,12 @@ 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）写在
-  profile 的 cordis.patch.yml。
+  其余高级配置（scriptsFile、hard limits、postprocess、approval、pathMap、
+  engage 的超时/早退参数）写在 profile 的 cordis.patch.yml。
 
 ## 协议 YAML
 
@@ -52,6 +55,25 @@ postprocess 是后处理：跑完后调用配置的 Python 函数（entry + pyth
 - 真机 engage / protocol run 会请求 DSH 审批（一次），abort 和面板写入不请求；
   插件不是硬件联锁。
 - labscript abort 只停止编译/提交新的 shot，已进 BLACS 队列或正在跑的 shot 不会被停。
-- 完成判定基于 HDF5 数量、大小稳定和最后一发可读；BLACS paused 会报
-  compiled_not_executed 诊断。
+- 完成判定基于 HDF5 数量、大小稳定和最后一发可读。shot 的 h5 文件在编译阶段就写了出来，
+  所以 labs_status 分别报 h5（文件数）和 executed（真正采到数据的枪数），完成要求最后一发
+  有采集数据；BLACS paused 会报 compiled_not_executed 诊断。
+- 编译 abort 时 labs_wait 不再等满 timeout：距今没有任何新 shot 超过 engage.noShotS
+  （默认 25 s）就返回 no_shots / compile_stalled 诊断，去 runmanager 看编译错误；如果只是
+  编译慢，再调一次 labs_wait 继续等。
+- 一条一枪都没产生的 pending 提交，超过 engage.staleS（默认 180 s）会被下一次 labs_engage
+  丢弃并报 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,9 +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).',
+  '- 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.',
+  '- 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',
@@ -36,15 +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.',
-  '- wait timed out or diagnosis=compiled_not_executed: the shots may be compiled but BLACS',
-  '  may be paused/not executing. Check BLACS and the panel, then abort or ask; do not resubmit blindly.',
+  '- labs_wait returns before the timeout 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: 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'