crosspad-mcp-server 8.1.2 → 9.1.0

package/skills/swd-tracer/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: swd-tracer
+description: Use when tracing/plotting STM32 firmware variables in real time over SWD (ST-Link) on the CrossPad r20 board (CrossPad_STM32_r20 repo, STM32G0B1xx), or when the SWD tracer / pyOCD environment needs setting up or repairing. Covers the doctor→config→symbols→start→read/ui→stop workflow, signal-spec syntax (arrays/structs/whole-array expansion), configuring all four environments (pyOCD venv, user config paths, ST-Link udev rules, the Debug ELF), and recovering from no-probe / wedged-probe / halted-core / MCU-STOP conditions. The MCP tool is `crosspad_trace`.
+---
+
+# CrossPad SWD real-time tracer
+
+Live, **non-halting** plotting of firmware variables read straight from MCU RAM
+over an ST-Link, à la ST-Studio / CubeMonitor — but driven by the agent. The MCP
+server already lists *which* tools exist; this skill encodes *how* to set the
+tracer up and drive it, and how to recover when the probe misbehaves.
+
+**Target:** CrossPad r20 = **STM32G0B1xx (Cortex-M0+)** firmware in the
+`CrossPad_STM32_r20` repo. Variables are resolved from the **Debug ELF** DWARF;
+pyOCD polls their RAM addresses while the core keeps running. (Cortex-M0+ has no
+ITM/SWO/DWT, so SWO/ITM "printf" is impossible — RAM polling is the mechanism.)
+
+All operations go through one MCP tool, `crosspad_trace`, via its `action`:
+`doctor · config_set · symbols · start · add · remove · status · read · save ·
+device_state · ui · stop`.
+
+## First move: always `doctor`
+
+```
+crosspad_trace action=doctor
+```
+
+It reports `issues[]` and whether a probe is connected. Resolve blocking issues
+(below) before `start`. If you're unsure what's configured, also run the
+read-only environment probe:
+
+```
+bash scripts/detect-env.sh
+```
+
+The helper scripts are bundled next to this SKILL.md in `scripts/`. Resolve them
+relative to the skill directory — e.g. `~/.claude/skills/swd-tracer/scripts/…`
+(global skill) or `<crosspad-mcp>/skills/swd-tracer/scripts/…` (repo / plugin).
+
+## Configuring the four environments
+
+The tracer needs four things in place. `doctor` / `detect-env.sh` tell you which
+are missing; fix only those.
+
+1. **pyOCD venv** — the daemon runs in a Python venv (system Python is usually
+   PEP-668 locked). Create it and point config at it:
+   ```
+   bash scripts/setup-venv.sh
+   crosspad_trace action=config_set key=pyocd_python value=$HOME/.local/share/crosspad-mcp/venv/bin/python
+   ```
+2. **User config paths** — persisted to `~/.config/crosspad-mcp/config.json`.
+   Keys: `stm_elf_path` (the Debug ELF), `pyocd_python`, `probe_serial`
+   (optional; only if multiple ST-Links), `trace_dir` (where `.cptrace`/CSV go).
+   ```
+   crosspad_trace action=config_set key=stm_elf_path value=<repo>/build/Debug/CrossPad_STM32_r20.elf
+   ```
+3. **ST-Link udev rules** (Linux) — needed for libusb access without root:
+   ```
+   bash scripts/install-udev-rules.sh   # sudo; then replug the ST-Link
+   ```
+4. **Debug ELF with symbols** — build it in the firmware repo so DWARF exists:
+   ```
+   cmake --preset Debug && cmake --build build/Debug
+   ```
+
+Resolution order for every config value: `config.json` → env var → default. So
+`config_set` wins; `CROSSPAD_STM_ELF` / `CROSSPAD_TRACE_PYTHON` /
+`CROSSPAD_PROBE_SERIAL` / `CROSSPAD_TRACE_DIR` are fallbacks.
+
+## The trace loop
+
+```
+doctor                       → green? continue
+symbols [query=…]            → discover variable names (rich metadata: kind/dims/members)
+start signals=[…] rate_hz=N  → spawns the daemon + opens the localhost UI
+ui                           → get the http://localhost:7373/ dashboard URL
+read [max_points] [window_…] → downsampled series + per-signal stats (cheap; LLM-safe)
+add / remove signals=[…]     → edit the watched set on a LIVE trace (no restart)
+status                       → device_state, sample_count, actual_fs, signals
+save                         → export buffer to CSV
+stop                         → end the trace (always frees the probe)
+```
+
+`rate_hz=0` means "as fast as the probe allows"; the real rate comes back as
+`actual_fs` (ST-Link V2 + pyOCD tops out ~480 Hz total across all ranges).
+Fewer/contiguous signals = higher Fs.
+
+## Signal-spec syntax
+
+| Form | Resolves to |
+|---|---|
+| `s_vbat_mv` | a scalar global/static |
+| `s_inputs[3]` | array element (bounds-checked against the DWARF length) |
+| `mat[1][2]` | multi-dim element |
+| `hpcd.Init.speed` | nested struct member |
+| `s_adc_raw` / `s_adc_raw[*]` | **whole array** → expands to every element |
+| `s_inputs[0:8]` | half-open slice → elements 0..7 |
+
+Expansion is capped at 256 elements. A spec that lands on an aggregate (struct
+with no trailing index) is reported as `unresolved`, not fatal. See
+[reference/signals.md](reference/signals.md) for the CrossPad-specific cheat sheet
+(pads, ADC channels, and the built-in `g_trace_demo.*` self-test signals).
+
+## Quick self-test (no real inputs needed)
+
+If the firmware includes the demo module, `g_trace_demo.demo_sine` draws a clean
+sine — the fastest "is the whole pipeline alive?" check:
+```
+crosspad_trace action=start signals=["g_trace_demo.demo_sine","g_trace_demo.tick"] rate_hz=200
+crosspad_trace action=read max_points=50
+```
+
+## Troubleshooting
+
+| Symptom | Cause / fix |
+|---|---|
+| `doctor` → `no_probe_detected` | ST-Link not on USB. Plug it in. If it *vanished* mid-session (gone from `lsusb`), a prior wedge knocked it off — **physically replug** it; software can't revive it. |
+| `start` returns `device_state: error: no debug probe detected` | Same — replug, re-run `doctor`. |
+| `start` → `device_state: connect_timeout` / daemon exits | Probe wedged in libusb. The daemon fails fast (≤8 s) + exits now; replug and retry. |
+| Values frozen / every signal a flat line | Core was **halted** on connect. The daemon uses `connect_mode=attach` to avoid this; if you see it, the firmware itself may be in a fault/STOP. Check `device_state`. |
+| `device_state: stop_suspected` then `probe_lost` | MCU entered STOP (RAM unreadable) or the probe dropped. Brief STOP recovers automatically; persistent (>10 s) → daemon reports `probe_lost` and exits. |
+| Out-of-bounds index silently "works" | It no longer does — `s_adc_raw[31]` on a `[15]` array is rejected. Use `symbols` to see real `dims`/`count`. |
+| Deep STOP / low-power analysis | `crosspad_trace action=device_state` dumps PWR/RCC/SCB regs + decodes SLEEPDEEP/LPMS. |
+| Permission/USB errors despite `lsusb` showing it | Missing udev rules — run `install-udev-rules.sh`, replug. |
+| Daemon won't die / port stuck | `stop` escalates SIGTERM→SIGKILL on the daemon; the UI server is persistent and keeps listening (it is NOT torn down). If a stale daemon lingers, `pkill -9 -f swd_tracer.py`. |
+
+## Notes
+
+- The web UI is loopback-only (127.0.0.1). The dashboard server is **persistent**:
+  it stays up across start/stop cycles (showing a `trace_end` banner while idle),
+  so an open tab survives between traces.
+- `start` waits for the daemon's first frame and reports the *real* state
+  (`running` / `connecting` / `error`), not an optimistic guess.
+- One active trace per server — `stop` before starting a different signal set,
+  or use `add`/`remove` to edit the live set.

package/skills/swd-tracer/reference/signals.md

@@ -0,0 +1,42 @@
+# CrossPad r20 firmware — handy trace signals
+
+Resolved from the Debug ELF DWARF. Names accept array/struct/expansion syntax
+(`name`, `name[i]`, `name[i][j]`, `name.member`, `name[*]`, `name[a:b]`). Use
+`crosspad_trace action=symbols query=<substr>` to discover more.
+
+## Inputs (reg_map.c, `s_inputs[47]`, uint8)
+| Spec | Meaning |
+|---|---|
+| `s_inputs[0]` | encoder detent index |
+| `s_inputs[1]` | pads 8–15 bitmap (PADS_HI) |
+| `s_inputs[2]` | pads 0–7 bitmap (PADS_LO) |
+| `s_inputs[3..18]` | per-pad pressure 0..127 (pad 0 = `[3]`) |
+| `s_inputs[44]` | buttons bitmap (0x2C) |
+| `s_inputs[*]` | whole input block (expands to 47 scalars) |
+
+## Power / ADC (power.c)
+| Spec | Meaning |
+|---|---|
+| `s_adc_raw` | raw ADC DMA buffer, **15** uint16 channels (`ADC_BUF_SIZE`). `s_adc_raw[*]` plots all |
+| `s_vbat_mv` | battery mV |
+| `s_vbus_stm_mv` | VBUS (STM side) mV |
+| `s_vbus_esp_mv` | VBUS (ESP side) mV |
+| `s_temp_c` | die temp °C |
+
+> NOTE: `s_adc_raw` is `[15]`, not 32 — indices ≥ 15 are rejected as out-of-bounds
+> (the tracer bounds-checks against the DWARF array length).
+
+## Built-in demo signals (trace_demo.c — RTT-style, for a quick self-test)
+Cortex-M0+ has **no ITM/SWO**, so "printf over SWD" here is a RAM ring polled
+non-intrusively. Flash the firmware, then watch:
+
+| Spec | Meaning |
+|---|---|
+| `g_trace_demo.tick` | monotonic main-loop counter |
+| `g_trace_demo.demo_sine` | fixed-point sine, [-1000,+1000] |
+| `g_trace_demo.demo_triangle` | fixed-point triangle, [-1000,+1000] |
+| `g_trace_demo.loop_hz` | estimated main-loop rate |
+| `g_trace_log_wr` | text-ring write count (watch it climb = logging active) |
+
+`g_trace_demo.demo_sine` is the ideal "does the whole pipeline work?" signal —
+it should draw a clean sine in the UI.

package/skills/swd-tracer/scripts/detect-env.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# Detect the tracer environment and print a readiness report + suggested config.
+# Read-only: writes nothing. Run this first to see what (if anything) is missing.
+set -uo pipefail
+
+VENV="${CROSSPAD_TRACE_VENV:-$HOME/.local/share/crosspad-mcp/venv}"
+CFG="${XDG_CONFIG_HOME:-$HOME/.config}/crosspad-mcp/config.json"
+
+ok()   { printf '  \033[32mOK\033[0m   %s\n' "$1"; }
+miss() { printf '  \033[31mMISS\033[0m %s\n' "$1"; }
+
+echo "== SWD tracer environment =="
+
+# 1. pyOCD venv
+if [ -x "$VENV/bin/python" ] && "$VENV/bin/python" -c "import pyocd, elftools" 2>/dev/null; then
+  ok "pyOCD venv: $VENV/bin/python ($("$VENV/bin/python" -c 'import pyocd;print(pyocd.__version__)' 2>/dev/null))"
+else
+  miss "pyOCD venv at $VENV — run scripts/setup-venv.sh"
+fi
+
+# 2. user config
+if [ -f "$CFG" ]; then
+  ok "config: $CFG"
+  sed 's/^/      /' "$CFG"
+else
+  miss "config $CFG — set keys via crosspad_trace action=config_set (stm_elf_path, pyocd_python)"
+fi
+
+# 3. Debug ELF (look in common spots if not configured)
+ELF="${CROSSPAD_STM_ELF:-}"
+if [ -z "$ELF" ]; then
+  ELF=$(ls "${CROSSPAD_STM_ROOT:-$HOME/GIT/CrossPad_STM32_r20}"/build/Debug/*.elf 2>/dev/null | head -1)
+fi
+if [ -n "$ELF" ] && [ -f "$ELF" ]; then
+  if "${VENV}/bin/python" - "$ELF" <<'PY' 2>/dev/null
+import sys
+from elftools.elf.elffile import ELFFile
+sys.exit(0 if ELFFile(open(sys.argv[1],'rb')).has_dwarf_info() else 1)
+PY
+  then ok "Debug ELF with DWARF: $ELF"
+  else miss "ELF $ELF has no DWARF — build the Debug preset with -g"
+  fi
+else
+  miss "Debug ELF not found — build it (cmake --preset Debug && cmake --build build/Debug)"
+fi
+
+# 4. ST-Link on USB
+if lsusb 2>/dev/null | grep -qiE '0483:(3744|3748|374b|374d|374e|374f|3753)'; then
+  ok "ST-Link present on USB"
+else
+  miss "ST-Link NOT on USB — plug it in (or replug if it vanished after a wedged session)"
+fi
+
+# 5. udev rules
+if ls /etc/udev/rules.d/*stlink* >/dev/null 2>&1; then
+  ok "ST-Link udev rules present"
+else
+  miss "no ST-Link udev rules — run scripts/install-udev-rules.sh (needs sudo)"
+fi
+
+echo "== done =="

package/skills/swd-tracer/scripts/install-udev-rules.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Install ST-Link udev rules so pyOCD/libusb can claim the probe without root.
+# Requires sudo. Without these, pyOCD may fail with permission/USB errors even
+# though `lsusb` shows the device (st-info succeeding only proves the CURRENT
+# user already happens to have access).
+set -euo pipefail
+
+RULE=/etc/udev/rules.d/49-stlink.rules
+echo "[udev] writing $RULE (needs sudo)"
+sudo tee "$RULE" >/dev/null <<'EOF'
+# ST-Link/V1
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="3744", MODE="0666", TAG+="uaccess"
+# ST-Link/V2
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="3748", MODE="0666", TAG+="uaccess"
+# ST-Link/V2-1
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="374b", MODE="0666", TAG+="uaccess"
+# ST-Link/V3
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="374d", MODE="0666", TAG+="uaccess"
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="374e", MODE="0666", TAG+="uaccess"
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="374f", MODE="0666", TAG+="uaccess"
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="3753", MODE="0666", TAG+="uaccess"
+EOF
+sudo udevadm control --reload-rules
+sudo udevadm trigger
+echo "[udev] DONE. Replug the ST-Link for the new rules to take effect."

package/skills/swd-tracer/scripts/setup-venv.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# Create the pyOCD virtualenv the SWD tracer daemon runs in.
+#
+# The system Python is usually PEP-668 "externally managed" (Debian/Ubuntu), so
+# pyocd/pyelftools cannot be pip-installed globally — a venv is required. The
+# tracer's user config key `pyocd_python` must point at this venv's python.
+set -euo pipefail
+
+VENV="${CROSSPAD_TRACE_VENV:-$HOME/.local/share/crosspad-mcp/venv}"
+
+echo "[setup-venv] target venv: $VENV"
+if [ ! -x "$VENV/bin/python" ]; then
+  python3 -m venv "$VENV"
+fi
+"$VENV/bin/pip" install --quiet --upgrade pip
+# pyocd 0.44+ for the SWD backend; pyelftools for DWARF symbol resolution.
+"$VENV/bin/pip" install --quiet "pyocd>=0.44" pyelftools
+
+echo "[setup-venv] installed:"
+"$VENV/bin/python" - <<'PY'
+import pyocd, elftools
+print("  pyocd     ", pyocd.__version__)
+print("  pyelftools", getattr(elftools, "__version__", "?"))
+PY
+echo "[setup-venv] DONE. Set the tracer config:"
+echo "  crosspad_trace action=config_set key=pyocd_python value=$VENV/bin/python"

package/tracer/PROTOCOL.md

@@ -0,0 +1,260 @@
+# CrossPad SWD tracer — wire protocol v2
+
+Single source of truth shared by the Python daemon (`tracer/swd_tracer.py`), the
+Node session/webui layer (`src/tools/trace-*.ts`), and the browser UI
+(`tracer/ui/index.html`). v2 adds **runtime-editable watching** (add/remove
+signals on a live trace) and richer **signal-spec resolution**.
+
+**v2.1 additions** (this revision): whole-array / vector / matrix **expansion**
+(§1.1), richer **symbol metadata** for UI autocomplete (§8), a `/symbols` HTTP
+endpoint (§9), and a hard rule that `add`/`remove` return the **post-reconcile**
+signal set (§4, §6) and that **Fs is reported ONCE globally** (§10).
+
+All daemon I/O is NDJSON — one JSON object per line. stdout = machine frames,
+stderr = human logs only.
+
+## 1. Signal spec grammar (resolved from the Debug ELF DWARF)
+
+A *signal spec* names a memory location to poll. Supported syntax:
+
+| Form | Meaning |
+|---|---|
+| `name` | global / static variable (base type, struct, or array) |
+| `name[i]` | array element (existing) |
+| `name[i][j]` | multi-dimensional array element |
+| `name.member` | struct / union member |
+| `name.a.b` | nested member chain |
+| `name[i].member` / `name.member[j]` | any mix of `[index]` and `.member` |
+
+Resolution walks DWARF: base symbol → `DW_AT_type`; `[i]` consumes an
+`DW_TAG_array_type` dimension (stride = element byte size, multi-dim handled via
+successive `DW_TAG_subrange_type`); `.member` consumes a `DW_TAG_structure_type`/
+`DW_TAG_union_type` member (offset = `DW_AT_data_member_location`). The final
+node must resolve to a scalar (`DW_TAG_base_type`, pointer, or enum) — a spec
+that lands on an aggregate is **unresolved** UNLESS it expands (see §1.1).
+Result: `{name: <original spec>, address, size, encoding}`.
+
+## 1.1 Whole-array / vector / matrix expansion
+
+A spec that lands on (or leaves trailing) an array dimension **expands** into one
+concrete scalar spec per element instead of being unresolved:
+
+| Form | Expands to |
+|---|---|
+| `vec` (bare array name, element scalar) | `vec[0]`, `vec[1]`, … `vec[N-1]` |
+| `vec[*]` | same as bare — all elements of that dimension |
+| `vec[a:b]` | half-open slice `vec[a]` … `vec[b-1]` |
+| `mat` (2-D array of scalar) | every cell `mat[0][0]` … `mat[R-1][C-1]` (row-major) |
+| `mat[*][k]` / `mat[i][*]` | the selected row/column |
+| `arr.field` where `arr` is array-of-struct | `arr[0].field` … (array dim before a member also expands) |
+
+Expanded element names use the concrete `name[i]` / `name[i][j]` form so the
+buffer/UI see distinct scalars. **Cap:** an expansion exceeding **256** elements
+is skipped and reported in the `signals` frame's `unresolved` as
+`"<spec> (expands to <N> > 256)"`. A spec landing on a struct/union (no trailing
+array) is still unresolved. Expansion is computed daemon-side (DWARF knows the
+bounds) for both the initial `--signals` set and live `add` commands.
+
+`encoding ∈ {int, uint, float, bool, char, uchar, address}`.
+
+## 2. Daemon stdin commands (Node → daemon, NDJSON)
+
+```jsonc
+{"cmd":"stop"}                              // graceful shutdown (existing)
+{"cmd":"add","signals":["s_vbat_mv","s_inputs[3]"]}   // add to live poll set
+{"cmd":"remove","signals":["s_inputs[3]"]}            // drop from live poll set
+```
+
+`add`/`remove` mutate the poll set on the running daemon. The poll loop
+re-coalesces ranges on the next iteration. Unknown / unresolvable specs in an
+`add` are skipped (reported via a `signals` frame's `unresolved`), never fatal.
+`remove` of an unknown name is a no-op.
+
+## 3. Daemon stdout frames (daemon → Node, NDJSON)
+
+```jsonc
+// emitted once right after connect, AND after every successful add/remove:
+{"type":"signals","signals":[{"name","address","size","encoding"}],"unresolved":["..."]}
+
+{"type":"sample","t":<seconds float>,"values":{"<name>":<number>, ...}}
+{"type":"status","device_state":"stop_suspected|stopped|...","t"?,"samples"?}
+{"type":"error","error":"<message>"}
+```
+
+`values` only contains the currently-watched signals; after an add the next
+sample includes the new names, after a remove they disappear.
+
+## 4. Node TraceSession API (TS)
+
+- `addSignals(string[]): Promise<string[]>` — writes `{"cmd":"add",...}` to
+  daemon stdin and resolves with the **post-reconcile** signal-name set once the
+  next `{"type":"signals"}` frame arrives (timeout ~2 s → resolves with the
+  current `buffer.signalNames()`). This kills the old race where the immediate
+  return showed the pre-reconcile set.
+- `removeSignals(string[]): Promise<string[]>` — same, for remove.
+- On a `{"type":"signals"}` frame: reconcile `buffer` signal set
+  (`buffer.addSignal`/`removeSignal`) and forward the frame to `onFrame`
+  subscribers (so the WS rebroadcasts the new set to browsers), then resolve any
+  pending add/remove promise.
+- `TraceBuffer` gains `addSignal(name)` / `removeSignal(name)` updating
+  `signalNames()`. Stored samples already key values by name, so history of a
+  removed signal stays until it ages out of the ring.
+
+## 5. Node TraceWebUi — bidirectional WS
+
+- Inbound browser → server messages (JSON): `{"cmd":"add"|"remove","signals":[...]}`.
+  Validate shape + cmd; forward to `session.addSignals/removeSignals`. Keep the
+  loopback-Origin check. Ignore malformed messages silently.
+- Outbound server → browser: forwards every daemon frame (`sample`, `status`,
+  `error`, **`signals`**) plus the initial `{"type":"hello","signals":[...]}`.
+
+## 6. MCP tool (`crosspad_trace`) actions
+
+- `add` / `remove`: require an active session; `await` the session promise and
+  return the **post-reconcile** `signals` (so the MCP response matches reality,
+  including any array expansion and dropped `unresolved` specs).
+- `symbols`: return the richer metadata of §8.
+- All other actions unchanged.
+
+## 7. Browser UI (talks §3/§5 over WS)
+
+Receives `hello` → `signals` (live set updates) → `sample`/`status`. Sends
+`add`/`remove`. Fetches `/symbols` (§9) for autocomplete. UI feature scope is
+owned by the UI implementer; the hard contracts are the WS message shapes, the
+`/symbols` shape (§8), and §10 (Fs shown once).
+
+## 8. Symbol metadata (richer `symbols` output — for autocomplete)
+
+The daemon `symbols` subcommand and the `/symbols` endpoint return, per symbol,
+in ADDITION to the existing `{name, address, encoding, size}`:
+
+```jsonc
+{
+  "name": "s_adc_raw", "address": ..., "encoding": "uint", "size": 64,
+  "kind": "array",            // "scalar" | "array" | "struct" | "union" | "other"
+  "dims": [32],               // array only: per-dimension element counts
+  "count": 32,                // array only: total elements (product of dims)
+  "elem_size": 2,             // array only: one element's byte size
+  "elem_encoding": "uint",    // array only: element scalar encoding
+  "members": ["a","b"]        // struct/union only: member names (one level)
+}
+```
+
+`kind`/`dims`/`count`/`elem_*`/`members` are best-effort and may be omitted for
+`other`. Back-compat: old consumers that read only `{name,address,encoding,size}`
+keep working. The UI uses this to suggest base names, `name[i]`/`name[*]` for
+arrays, and `name.member` for structs.
+
+## 9. `/symbols` HTTP endpoint (browser → Node)
+
+`GET /symbols[?query=substr]` on the same loopback origin as the UI returns
+`{"symbols":[ ... §8 entries ... ]}` (Content-Type `application/json`). The
+webui obtains it via the existing Node `listSymbols()` bridge against the active
+session's ELF. Loopback-bound like the rest of the UI server.
+
+## 10. Fs is reported ONCE, globally
+
+Sample rate (Fs / actual_fs) is a property of the **whole trace**, not per
+signal — every signal is sampled in the same poll loop. So Fs must be shown in
+exactly ONE place (a single global readout / one `actual_fs` field), never
+duplicated into each per-signal stats row. Per-signal stats keep value-domain
+metrics only (min/max/mean/p2p/RMS/n/slope); the shared Fs lives outside them.
+
+## 11. Robustness contract (v2.2 — fail fast, never wedge)
+
+The probe (ST-Link V2) can vanish from USB or wedge libusb after an unclean
+session. The tracer MUST fail fast and surface it, never hang or require
+`pkill -9`. Hard rules:
+
+### 11.1 Daemon connect
+- `session_with_chosen_probe` is called with `blocking=False, return_first=True`
+  so a **missing probe returns immediately** → emit
+  `{"type":"error","error":"no debug probe detected (replug ST-Link)"}` and exit
+  code 3.
+- Creating + opening the session runs inside a **watchdog thread** bounded by
+  `--connect-timeout` (default 8 s). If it does not complete in time the worker
+  is wedged in uninterruptible C (libusb) — flush an
+  `{"type":"error","error":"connect timeout after Ns (probe wedged? replug)"}`
+  frame and `os._exit(2)`. The main process dies; the OS reclaims the wedged
+  thread. This is the ONLY correct recovery for a libusb wedge.
+- Any other connect exception → `{"type":"error","error":...}` + exit 1.
+- Applies to BOTH `trace` and `device-state` (device-state uses a shorter 6 s).
+
+### 11.2 Daemon run-loop disconnect
+- A read fault emits `{"type":"status","device_state":"stop_suspected"}` as
+  before, BUT the daemon now tracks fault duration. If faults persist longer
+  than `--lost-timeout` (default 10 s) it emits
+  `{"type":"error","error":"probe/target lost (persistent read fault Ns)"}` and
+  exits — instead of looping `stop_suspected` forever. A successful read resets
+  the fault timer (a genuine MCU STOP that resumes keeps tracing).
+
+### 11.3 ELF / DWARF guard
+- `build_symbol_table` / symbol resolution is wrapped: a bad/missing ELF emits
+  `{"type":"error","error":...}` (not a raw traceback) and the daemon exits.
+
+### 11.4 device_state vocabulary
+`connecting` (before first frame) · `running` · `stop_suspected` · `probe_lost`
+· `connect_timeout` · `stopped` · `error: <msg>` · `exited`.
+
+### 11.5 Node teardown — guaranteed kill
+`TraceSession.stop()`: write `{"cmd":"stop"}`, then `SIGTERM` after ~1.5 s, then
+**`SIGKILL` after a further ~3 s if the process is still alive** (a wedged daemon
+ignores SIGTERM). Always tear down the web UI first (existing behavior).
+
+### 11.6 Node diagnostics + start truthfulness
+- The daemon's **stderr is captured** (ring of the last ~30 lines), exposed as
+  `session.stderrTail()` and folded into the device_state/error surfaced by the
+  MCP `status`/`start`.
+- MCP `start` **waits up to ~3 s for the first frame** (`signals`|`sample`|
+  `error`) and returns a device_state reflecting reality
+  (`running` vs `connect_timeout` vs `error: …`) instead of an optimistic
+  `running` that masks a dead connect.
+- If the daemon exits non-zero with no error frame, `device_state` becomes
+  `error: <stderr tail>`.
+
+### 11.7 Doctor probe presence
+`doctor` runs a real probe-presence check (`pyocd list` via the daemon python,
+or `st-info --probe`) and reports a **blocking** issue
+`no_probe_detected` when none is connected (distinct from the udev warning).
+`start` refuses (clear error) when doctor reports `no_probe_detected`.
+
+## 12. Persistent dashboard + reconnect + auto-open (v2.3)
+
+The dashboard must feel permanent: open it once (ideally as a VS Code **Simple
+Browser** tab) and it survives every trace start/stop without going dead.
+
+### 12.1 Persistent UI server (decoupled from the session)
+- The web UI HTTP+WS server is a **module-level singleton that OUTLIVES trace
+  sessions** — `stop` ends the daemon but the server keeps listening. A
+  browser/VS Code tab stays connected across start→stop→start cycles.
+- The singleton holds a mutable `currentSession`. `start` binds the new session
+  (subscribes to its frames); `stop` unbinds (server goes idle but stays up).
+- `TraceSession.stop()` no longer tears the UI down; the singleton owns the
+  server lifecycle. The port (7373) is therefore stable across traces.
+
+### 12.2 WS messages — new server→client
+- `hello` gains fields: `{"type":"hello","active":bool,"signals":[...]}`.
+- `{"type":"trace_start","signals":[...]}` — a new trace began; UI resets and
+  starts plotting the new set.
+- `{"type":"trace_end"}` — the trace stopped; UI keeps the last data but shows an
+  idle/"waiting for next trace" state. The WS stays connected (server is up).
+- `sample`/`status`/`error`/`signals` continue, scoped to the bound session.
+
+### 12.3 `/symbols` when idle
+With no active session, `/symbols` falls back to the **configured default ELF**
+so autocomplete keeps working between traces.
+
+### 12.4 Auto-open on `start` (unless already open)
+On `start`, after ensuring the singleton server is up, open the dashboard in the
+user's browser **only if no WS client is currently connected** (i.e. it isn't
+already open — covers both an external browser and a VS Code Simple Browser tab).
+Platform opener (`xdg-open`/`open`/`start`), detached, best-effort, never throws.
+Skip when headless (no `DISPLAY`/`WAYLAND_DISPLAY` on Linux) or when
+`CROSSPAD_TRACE_NO_BROWSER` is set. Because the server persists, a VS Code tab
+opened once stays connected, so auto-open never re-pops it.
+
+### 12.5 UI reconnect
+The UI has a visible **Reconnect** button AND an automatic reconnect loop (with
+backoff) that survives server restarts and `trace_end`. Idle shows "waiting for
+trace…"; `trace_end` shows a "trace ended" banner; reconnect re-establishes the
+WS and re-syncs the signal set from the fresh `hello`.