de-shell 0.2.0__py3-none-any.whl

de_shell/ipc.py

@@ -0,0 +1,236 @@
+"""
+ipc.py — stdin/stdout JSON-lines protocol between the Python backend and Electron.
+
+All messages from Python to Electron are prefixed with "PLOTAPP:" and contain
+JSON on a single line, matching the protocol anyplotlib._electron already uses.
+
+Messages from Electron arrive on stdin as JSON lines (no prefix).
+
+Usage
+-----
+    from de_shell.ipc import emit, read_messages
+
+    # send a message to Electron
+    emit({"type": "status", "text": "Cluster ready"})
+
+    # read messages (async, called from the asyncio event loop)
+    async for msg in read_messages(loop):
+        handle(msg)
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import math
+import sys
+import threading
+from typing import Any
+
+
+def _sanitize_nonfinite(o: Any) -> Any:
+    """Replace NaN/Inf floats with None, recursively. Slow path only."""
+    if isinstance(o, float):
+        return o if math.isfinite(o) else None
+    if isinstance(o, dict):
+        return {k: _sanitize_nonfinite(v) for k, v in o.items()}
+    if isinstance(o, (list, tuple)):
+        return [_sanitize_nonfinite(v) for v in o]
+    return o
+
+
+def _dumps(obj: Any) -> str:
+    """json.dumps that never emits bare ``NaN``/``Infinity`` tokens.
+
+    Python's json happily writes ``NaN``, which is NOT JSON: the Electron
+    demuxer's ``JSON.parse`` throws and the runner drops the whole message on
+    the floor (``catch { /* malformed line — ignore */ }``) — one non-finite
+    fit value or detector temperature silently swallowed an entire state
+    update. Fast path is plain dumps with ``allow_nan=False``; only a payload
+    that actually contains a non-finite float pays for the recursive
+    sanitize (→ null, which the renderer already renders as "—").
+    """
+    try:
+        return json.dumps(obj, default=str, allow_nan=False)
+    except ValueError:
+        try:
+            return json.dumps(_sanitize_nonfinite(obj), default=str,
+                              allow_nan=False)
+        except ValueError:
+            # A non-finite the sanitizer could not reach: keep the message
+            # rather than crash the emitter (old behavior, dropped downstream).
+            return json.dumps(obj, default=str)
+
+# Logging goes to stderr (default), never the PLOTAPP stdout protocol channel.
+log = logging.getLogger(__name__)
+
+_stdout_lock = threading.Lock()
+
+# Capture the *real* stdout at import time. This is the dedicated protocol
+# channel; emit() always writes here even after stray prints are redirected.
+_PROTOCOL_OUT = sys.stdout
+
+
+def _write_line(line: str) -> None:
+    """Write one protocol line, flushed immediately (thread-safe)."""
+    with _stdout_lock:
+        _PROTOCOL_OUT.write(line)
+        _PROTOCOL_OUT.flush()
+
+
+def _write_binary(frame: bytes) -> None:
+    """Write one raw binary frame to the protocol channel's BINARY stream, under
+    the same lock as text lines so a PLOTBIN frame never interleaves with a
+    PLOTAPP: line. Uses ``_PROTOCOL_OUT.buffer`` (the real stdout's binary fd) so
+    the bytes are NOT newline-translated / re-encoded (Windows text mode would
+    corrupt binary — the '\\n' bytes in the pixels would become '\\r\\n')."""
+    buf = getattr(_PROTOCOL_OUT, "buffer", None)
+    if buf is None:
+        return
+    with _stdout_lock:
+        _PROTOCOL_OUT.flush()      # flush any pending text first (ordering)
+        buf.write(frame)
+        buf.flush()
+
+
+def redirect_stray_stdout() -> None:
+    """Send all `print()` output to stderr so it can never interleave with the
+    PLOTAPP protocol on stdout, while keeping BOTH protocol emitters — the shell's
+    own ``emit`` and anyplotlib's ``_electron.emit`` — pointed at the real
+    stdout protocol channel.
+
+    anyplotlib._electron.emit writes to ``sys.stdout`` dynamically, so simply
+    redirecting sys.stdout would send its state_update/event_json messages to
+    stderr (where the runner never parses them). We therefore monkeypatch
+    anyplotlib's emit to share the shell's locked protocol channel, then redirect
+    sys.stdout so stray prints go to stderr.
+
+    Call once at backend startup, after _PROTOCOL_OUT is captured.
+    """
+    try:
+        import anyplotlib._electron as _ael
+
+        def _shared_emit(obj: dict) -> None:
+            _write_line("PLOTAPP:" + _dumps(obj) + "\n")
+
+        _ael.emit = _shared_emit
+
+        # anyplotlib's emit_binary writes raw PLOTBIN frames to sys.stdout.buffer,
+        # but after the redirect below sys.stdout IS stderr — so without this the
+        # binary pixels would spew to the terminal (garbled) and never reach the
+        # Electron demuxer. Route it through the locked BINARY protocol channel.
+        if hasattr(_ael, "emit_binary"):
+            from anyplotlib._binary_frame import encode_frame as _encode_frame
+
+            _bin_logged = [False]
+
+            def _shared_emit_binary(fig_id, key, header, payload) -> None:
+                if not _bin_logged[0]:
+                    _bin_logged[0] = True
+                    log.info("binary transport active: PLOTBIN %s %d bytes",
+                             key, len(payload))
+                _write_binary(_encode_frame(fig_id, key, header, payload))
+
+            _ael.emit_binary = _shared_emit_binary
+    except Exception as e:
+        log.debug("redirecting anyplotlib emit to shared protocol channel failed: %s", e)
+
+    sys.stdout = sys.stderr
+
+
+def emit(obj: dict[str, Any]) -> None:
+    """Write a PLOTAPP: message to the protocol channel (thread-safe, flushed
+    immediately from any thread)."""
+    _write_line("PLOTAPP:" + _dumps(obj) + "\n")
+
+
+def emit_status(text: str) -> None:
+    emit({"type": "status", "text": text})
+
+
+def emit_error(text: str) -> None:
+    emit({"type": "error", "text": text})
+
+
+def emit_progress(done: int, total: int, label: str = "") -> None:
+    emit({"type": "progress", "done": done, "total": total, "label": label})
+
+
+def emit_window_computing(window_id: int | None, computing: bool) -> None:
+    """Per-window compute-lifecycle marker — drives the renderer's floating
+    "Calculating…" overlay (centered, translucent, pointer-events:none) on the
+    plot window while a long compute (e.g. the progressive navigator fill, a
+    streamed virtual image) is filling it in.
+
+    ``window_id`` is None-guarded (a plot may not have a window yet, e.g. very
+    early in construction) — silently a no-op rather than sending a malformed
+    message. Callers MUST pair every ``True`` with a matching ``False`` in a
+    ``finally`` block so a cancelled/failed compute still clears the overlay;
+    see ``de_shell.actions.lifecycle.window_computing`` for the context-manager
+    helper that guarantees this.
+    """
+    if window_id is None:
+        return
+    emit({"type": "window_computing", "window_id": window_id, "computing": bool(computing)})
+
+
+async def read_messages(loop: asyncio.AbstractEventLoop | None = None):
+    """
+    Async generator that yields parsed JSON dicts from stdin.
+    Each line on stdin must be a valid JSON object.
+    Exits when stdin closes.
+
+    Implementation note (cross-platform): stdin is read on a dedicated daemon
+    thread that pushes raw lines into an ``asyncio.Queue``, rather than via
+    ``loop.connect_read_pipe(sys.stdin)`` — the latter raises
+    ``OSError: [WinError 6] The handle is invalid`` under Windows'
+    ``ProactorEventLoop`` (it can't register a console/pipe stdin handle with the
+    IOCP), which silently broke every Electron→backend message on Windows. A
+    blocking ``readline`` on a thread works identically on Windows, macOS, Linux.
+
+    Encoding note: we read the BINARY stream (``sys.stdin.buffer``) and decode
+    each line as UTF-8 ourselves. ``sys.stdin`` (the text layer) decodes with the
+    platform-default encoding — cp1252 on Windows — so a UTF-8 payload from
+    Electron carrying any non-ASCII character (e.g. ``εxx`` strain labels, the
+    ``Å`` unit) was mojibake'd: the bytes ``0xCE 0xB5`` (UTF-8 ``ε``) decoded to
+    ``ε`` and downstream string matches (tile_views' label lookup) silently
+    failed. Reading bytes + explicit UTF-8 decode is correct on every platform.
+    """
+    if loop is None:
+        loop = asyncio.get_event_loop()
+
+    q: asyncio.Queue[str | None] = asyncio.Queue()
+    # Prefer the raw byte stream; fall back to the text stream (some test
+    # harnesses replace sys.stdin with a StringIO that has no .buffer).
+    stream = getattr(sys.stdin, "buffer", None)
+    binary = stream is not None
+    if not binary:
+        stream = sys.stdin
+
+    def _pump() -> None:
+        try:
+            while True:
+                raw = stream.readline()
+                if not raw:   # EOF — pipe closed by Electron
+                    break
+                if binary:
+                    raw = raw.decode("utf-8", errors="replace")
+                loop.call_soon_threadsafe(q.put_nowait, raw)
+        except Exception as e:
+            log.debug("stdin pump stopped: %s", e)
+        finally:
+            loop.call_soon_threadsafe(q.put_nowait, None)
+
+    threading.Thread(target=_pump, daemon=True, name="de-shell-stdin-pump").start()
+
+    while True:
+        raw = await q.get()
+        if raw is None:   # EOF sentinel
+            break
+        line = raw.strip()
+        if not line:
+            continue
+        try:
+            yield json.loads(line)
+        except json.JSONDecodeError:
+            log.debug("skipping non-JSON line from frontend: %r", line[:200])

de_shell/js/__init__.py

@@ -0,0 +1,38 @@
+"""The TypeScript half of the shell, shipped inside the wheel.
+
+Four folders, one per Electron target, each a self-contained tree of
+TypeScript that the consuming app's bundler compiles:
+
+* ``main/``     — the Electron main process: the window and menus, the Python
+                  sidecar and its stdout demuxer, the managed environment, the
+                  updater, the problem reporter.
+* ``preload/``  — the contextBridge surface (``exposeShellBridge``).
+* ``renderer/`` — React: the figure bridge over anyplotlib, ``FigureFrame``,
+                  the chrome slice of the reducer.
+* ``testing/``  — the Playwright harness (``launchApp``) the e2e specs use.
+
+They live HERE rather than on npm so that the JavaScript that speaks the
+sidecar protocol ships in the same artifact as the Python that speaks it: one
+``pip install -U de-shell`` moves both halves together, and two versions of the
+protocol in one app cannot happen. An app finds the tree by asking this module
+(``python -m de_shell.js``) and links it into its Electron project — see the
+README — which also makes an editable install live-editable.
+
+The peer dependencies (react, electron, electron-updater, @playwright/test) are
+the app's to declare; every app already does.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+TARGETS = ("main", "preload", "renderer", "testing")
+
+
+def path(target: str | None = None) -> Path:
+    """The directory holding the TypeScript, or one target's folder."""
+    root = Path(__file__).resolve().parent
+    if target is None:
+        return root
+    if target not in TARGETS:
+        raise ValueError(f"unknown shell target {target!r}; one of {TARGETS}")
+    return root / target

de_shell/js/__main__.py

@@ -0,0 +1,4 @@
+"""``python -m de_shell.js`` prints where the TypeScript is, for build scripts."""
+from . import path
+
+print(path())

de_shell/js/main/backendProcess.test.ts

@@ -0,0 +1,70 @@
+/**
+ * backendProcess.test.ts — node:test unit tests for the sidecar spawn-error path.
+ *
+ * Guards the `spawn uv ENOENT` trap: a backend command that does not exist must
+ * surface a READABLE stream line and a synthetic `backend_exited` message — not
+ * crash the Electron main process with an unhandled ChildProcess 'error' event,
+ * which is exactly what an unlisted 'error' emitter does.
+ *
+ * Run: `node --test src/backendProcess.test.ts` (from packages/shell-main/), or
+ * via the `test:unit` npm script.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { configureShell } from './config.ts'
+import { startBackend, stopBackend } from './backendProcess.ts'
+
+configureShell({
+  appId: 'testapp',
+  appName: 'Test App',
+  pythonModule: 'testapp',
+})
+
+function collectBackend(cmd: string[]) {
+  const streams: string[] = []
+  const messages: Array<Record<string, unknown>> = []
+  startBackend(cmd, {
+    onMessage: (m) => messages.push(m),
+    onStream: (t) => streams.push(t),
+  })
+  return { streams, messages }
+}
+
+async function waitFor(pred: () => boolean, ms = 5000): Promise<void> {
+  const t0 = Date.now()
+  while (!pred()) {
+    if (Date.now() - t0 > ms) throw new Error('timed out waiting for condition')
+    await new Promise((r) => setTimeout(r, 25))
+  }
+}
+
+test('a nonexistent backend command reports readably instead of crashing', async () => {
+  const { streams, messages } = collectBackend(['definitely-not-a-real-command-xyz'])
+  try {
+    await waitFor(() => messages.some((m) => m.type === 'backend_exited'))
+  } finally {
+    stopBackend()
+  }
+  const text = streams.join('')
+  // The failing command is named — "something went wrong" is not a report.
+  assert.match(text, /definitely-not-a-real-command-xyz/)
+  // And the cause is stated in words, not only an errno.
+  assert.match(text, /not found|could not be started/i)
+})
+
+test('a missing uv names uv and says how to fix it', async () => {
+  // The dev-mode backend command is `uv run …`; when uv is absent the operator
+  // needs "install uv / put it on PATH", not a bare ENOENT stack.
+  const { streams, messages } = collectBackend([
+    'uv-definitely-not-installed-xyz.exe', 'run', 'python', '-m', 'testapp',
+  ])
+  try {
+    await waitFor(() => messages.some((m) => m.type === 'backend_exited'))
+  } finally {
+    stopBackend()
+  }
+  const exited = messages.find((m) => m.type === 'backend_exited')
+  assert.ok(exited, 'no backend_exited message arrived')
+  const text = streams.join('')
+  assert.match(text, /PATH/i)
+})

de_shell/js/main/backendProcess.ts

@@ -0,0 +1,330 @@
+/**
+ * backendProcess.ts — the Python sidecar process manager.
+ *
+ * Spawns the resolved backend command (see pythonEnv.ts) and maintains
+ * the bidirectional PLOTAPP: JSON protocol over stdin/stdout.
+ */
+import { spawn, spawnSync, ChildProcess } from 'child_process'
+import process from 'process'
+// Extension spelled out so node:test can load this module without a bundler
+// (native type-stripping resolves relative imports literally).
+import { shellConfig } from './config.ts'
+
+export interface BackendHandlers {
+  onMessage: (msg: Record<string, unknown>) => void
+  onStream:  (text: string, kind: 'stdout' | 'stderr') => void
+  // A raw PLOTBIN binary frame: the decoded header (fig_id/key/dims/…) plus the
+  // raw pixel bytes (NOT base64). Forwarded to the renderer as a transferable
+  // ArrayBuffer so large image frames skip the base64/JSON/atob cost.
+  onBinary?: (header: Record<string, unknown>, payload: Buffer) => void
+}
+
+const PLOTBIN = Buffer.from('PLOTBIN:')
+const NL = 0x0a
+
+let proc: ChildProcess | null = null
+let tickTimer: ReturnType<typeof setInterval> | null = null
+
+/**
+ * The sidecar's last few hundred output lines, for a problem report.
+ *
+ * The renderer's log panel has the same text, but it lives in a window that a
+ * crash may have taken down, and it is not reachable from the main process
+ * where a report is assembled. Bounded so a chatty run cannot grow it without
+ * limit; long lines are clipped because a report is meant to be read.
+ */
+const MAX_OUTPUT_LINES = 300
+const MAX_OUTPUT_LINE_CHARS = 1000
+const backendOutput: string[] = []
+
+function rememberOutput(text: string): void {
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue
+    backendOutput.push(line.slice(0, MAX_OUTPUT_LINE_CHARS))
+  }
+  if (backendOutput.length > MAX_OUTPUT_LINES) {
+    backendOutput.splice(0, backendOutput.length - MAX_OUTPUT_LINES)
+  }
+}
+
+/** The sidecar's recent output, oldest first. */
+export function recentBackendOutput(): string[] {
+  return [...backendOutput]
+}
+
+export function startBackend(
+  pythonCmd: string[],
+  handlers: BackendHandlers,
+  cwd?: string,
+): void {
+  if (proc) {
+    // Two live backends would both write the protocol channel and neither
+    // would be the one stopBackend() knows about. Stop the first explicitly.
+    throw new Error('startBackend: the backend is already running')
+  }
+  stopping = false  // fresh process — allow a future stopBackend() to run
+  const [cmd, ...args] = pythonCmd
+  const child = spawn(cmd, args, {
+    cwd,   // run from the project root so `uv run` finds the app's pyproject.toml
+    // APL_BINARY_TRANSPORT=1: anyplotlib ships large image pixels as raw PLOTBIN
+    // binary frames (no base64/JSON) which this runner demuxes — see the stdout
+    // parser below. Verified end-to-end (pixel-correct via GPU readback); cuts the
+    // ~200 ms/frame base64+JSON+atob transport on a 4k movie. Set to "0" to force
+    // the base64 fallback.
+    env: {
+      ...process.env, PYTHONUNBUFFERED: '1',
+      APL_BINARY_TRANSPORT: process.env.APL_BINARY_TRANSPORT ?? '1',
+    },
+    stdio: ['pipe', 'pipe', 'pipe'],
+  })
+  proc = child
+
+  // BACKEND TICK (0.5 Hz): Windows throttles timer delivery to the hidden
+  // Python child so aggressively that its timer waits (time.sleep,
+  // Event.wait, event-loop timers — incl. dask's task-delivery flushes) can
+  // freeze INDEFINITELY, waking only when process I/O arrives. Measured
+  // end-to-end (SpyDE: spyde/tests/repro_batch_stall.py + _probe_fv_stall.spec.ts):
+  // distributed computes sat idle forever hands-off, and EVERY unstick
+  // followed a stdin message within ~4 s — a user click "fixing" it was this
+  // pipe write, not the click. Electron's own timers are healthy (foreground
+  // app), so this interval is reliable; the backend handles 'tick' as a
+  // silent no-op. Two lines of traffic per second, bounded staleness ~6 s.
+  if (tickTimer) clearInterval(tickTimer)
+  tickTimer = setInterval(() => {
+    try { sendAction('tick') } catch { /* backend gone — stop ticking */ }
+    if (!proc && tickTimer) { clearInterval(tickTimer); tickTimer = null }
+  }, 2000)
+
+  // Custom stdout demuxer: the stream interleaves text lines (PLOTAPP: JSON and
+  // plain log output, both '\n'-terminated) with raw PLOTBIN binary frames
+  // (PLOTBIN:<hlen>:<plen>\n<header_json><payload>). readline can't carry binary,
+  // so we parse the raw Buffer stream ourselves, accumulating partial reads.
+  let acc: Buffer = Buffer.alloc(0)
+  child.stdout!.on('data', (chunk: Buffer) => {
+    acc = acc.length ? Buffer.concat([acc, chunk]) : chunk
+    // Process as many complete units as are buffered; stop when we need more.
+    for (;;) {
+      if (acc.length === 0) break
+      // A binary frame if the buffer starts with the PLOTBIN marker.
+      if (acc.length >= PLOTBIN.length &&
+          acc.subarray(0, PLOTBIN.length).equals(PLOTBIN)) {
+        const nl = acc.indexOf(NL)
+        if (nl < 0) break                       // prefix line incomplete
+        const prefix = acc.subarray(PLOTBIN.length, nl).toString('ascii')
+        const [hlenS, plenS] = prefix.split(':')
+        const hlen = parseInt(hlenS, 10), plen = parseInt(plenS, 10)
+        if (!(hlen >= 0) || !(plen >= 0)) {     // malformed → drop the line
+          handlers.onStream(`[sidecar protocol] malformed PLOTBIN prefix: ${prefix}\n`, 'stderr')
+          acc = acc.subarray(nl + 1); continue
+        }
+        const bodyStart = nl + 1
+        const end = bodyStart + hlen + plen
+        if (acc.length < end) break             // body not fully arrived yet
+        let header: Record<string, unknown> = {}
+        try {
+          header = JSON.parse(acc.subarray(bodyStart, bodyStart + hlen).toString('utf8'))
+        } catch { /* malformed header — still consume the frame */ }
+        // Copy the payload out so it survives `acc` being sliced/reused.
+        const payload = Buffer.from(acc.subarray(bodyStart + hlen, end))
+        acc = acc.subarray(end)
+        try { handlers.onBinary?.(header, payload) } catch { /* ignore */ }
+        continue
+      }
+      // Otherwise a text line up to the next '\n'.
+      const nl = acc.indexOf(NL)
+      if (nl < 0) break                         // line incomplete
+      const line = acc.subarray(0, nl).toString('utf8')
+      acc = acc.subarray(nl + 1)
+      if (line.startsWith('PLOTAPP:')) {
+        try {
+          handlers.onMessage(JSON.parse(line.slice(8)) as Record<string, unknown>)
+        } catch {
+          // Say so rather than swallow it: a truncated frame is how a backend
+          // bug presents, and silence turns it into "the UI just stopped".
+          handlers.onStream(`[sidecar protocol] malformed JSON message: ${line.slice(0, 200)}\n`, 'stderr')
+        }
+      } else if (line.trim()) {
+        rememberOutput(line)
+        handlers.onStream(line + '\n', 'stdout')
+      }
+    }
+  })
+
+  child.stderr!.on('data', (d: Buffer) => {
+    rememberOutput(d.toString())
+    handlers.onStream(d.toString(), 'stderr')
+  })
+
+  // SPAWN-ERROR TRAP: a command that cannot be started (uv missing from PATH is
+  // the recurring case) emits 'error' on the ChildProcess — and an 'error' event
+  // with no listener CRASHES the Electron main process. 'close' never fires for
+  // a failed spawn, so this is the only place the failure can be reported.
+  child.on('error', (err: NodeJS.ErrnoException) => {
+    if (proc === child) proc = null
+    if (tickTimer) { clearInterval(tickTimer); tickTimer = null }
+    const enoent = err.code === 'ENOENT'
+    handlers.onStream(
+      `[${shellConfig().appName}] backend command could not be started: ` +
+      `${cmd} (${err.code ?? err.message})` +
+      (enoent ? ` — ${cmd} was not found. Is it installed and on PATH?` : '') +
+      '\n',
+      'stderr')
+    handlers.onMessage({ type: 'backend_exited', code: null, error: String(err.message ?? err) })
+  })
+
+  child.on('close', (code) => {
+    // Only forget THIS child. After stopBackend() + startBackend(), the old
+    // process's late close event must not null the new backend's handle —
+    // every sendAction() after that would silently no-op.
+    if (proc === child) proc = null
+    rememberOutput(`[exited with code ${code}]`)
+    handlers.onStream(`[${shellConfig().appName} exited with code ${code}]\n`, 'stderr')
+    // Surface the death to the renderer so the UI doesn't silently freeze —
+    // every sendAction() after this no-ops (proc is null), so without this the
+    // user gets no indication the analysis backend stopped. Routed through the
+    // same onMessage path as a synthetic message (not a PLOTAPP: line).
+    handlers.onMessage({ type: 'backend_exited', code })
+  })
+}
+
+/** Send a JSON action message to the Python backend. */
+export function sendAction(
+  action: string,
+  payload: Record<string, unknown> = {},
+  windowId?: number,
+): void {
+  if (!proc?.stdin) return
+  const msg: Record<string, unknown> = { type: 'action', action, payload }
+  if (windowId !== undefined) msg.window_id = windowId
+  proc.stdin.write(JSON.stringify(msg) + '\n')
+}
+
+/** Forward a figure interaction event back to Python. */
+export function sendFigureEvent(figId: string, eventJson: string): void {
+  if (!proc?.stdin) return
+  proc.stdin.write(JSON.stringify({ type: 'figure_event', fig_id: figId, event_json: eventJson }) + '\n')
+}
+
+/** Notify Python that a figure's container resized. */
+export function sendResize(figId: string, width: number, height: number): void {
+  if (!proc?.stdin) return
+  proc.stdin.write(JSON.stringify({ type: 'resize', fig_id: figId, width, height }) + '\n')
+}
+
+/**
+ * Stop the Python backend, leaving NO orphaned worker subprocesses.
+ *
+ * Strategy:
+ *  1. GRACEFUL: write `{type:'quit'}` to stdin. The backend's asyncio loop
+ *     (app.py) handles this by breaking and calling `session.shutdown()`, which
+ *     tears down the Dask cluster cleanly.
+ *  2. BACKSTOP TREE-KILL: the backend may not exit promptly (mid-compute) or
+ *     stdin may already be closed, and `proc.kill()` on Windows only kills the
+ *     DIRECT child — leaving the Dask worker/nanny GRANDCHILDREN orphaned. So
+ *     after a short grace period we kill the whole tree:
+ *       - win32: `taskkill /pid <pid> /T /F` (whole tree, force).
+ *       - posix: SIGTERM, then SIGKILL after a short timer.
+ *
+ * This composes with the PYTHON-side process_guard.py: that installs a Windows
+ * kill-on-close Job Object so the OS reaps the worker tree whenever the backend
+ * process itself dies for ANY reason (clean exit, crash, or our taskkill). The
+ * graceful quit here is the preferred path (clean cluster shutdown); the
+ * tree-kill is the backstop for when Electron must hard-stop the backend before
+ * it can reach its own shutdown(). Both ultimately guarantee no leaked workers.
+ *
+ * Idempotent and null-safe: callable from window-all-closed, before-quit, and a
+ * signal handler without double-killing.
+ *
+ * `immediate` skips the grace period and tree-kills BEFORE returning. Step 2's
+ * timers only fire while this process is still alive, so a caller that is about
+ * to end the process (the update handoff — see updater.ts) would otherwise leave
+ * the sidecar and its Dask workers running: the graceful `quit` is written, the
+ * timer is armed, and Electron exits before it can fire. The Windows installer
+ * that starts moments later then finds processes still holding the install
+ * directory and refuses to continue.
+ */
+let stopping = false
+export function stopBackend(options: { immediate?: boolean } = {}): void {
+  const p = proc
+  if (!p || stopping) {
+    proc = null
+    return
+  }
+  stopping = true
+  proc = null  // every sendAction() after this no-ops; prevents re-entrant kills
+  // KNOWN BUG (open): quitting while a find-vectors batch is still streaming can
+  // WEDGE shutdown on Windows. Clearing the tick timer here stops the stdin tick
+  // that keeps the hidden backend scheduled (the very starvation the tick was
+  // added for), so a mid-batch backend may never get scheduled long enough to
+  // process the graceful `quit` — only the 1.5 s taskkill backstop ends it. The
+  // e2e specs work around it by waiting for the '[fv-batch] finalized' log line
+  // before closing the app. The app-side fix (keep ticking until the backend
+  // exits, or force-reap the batch) is still open.
+  if (tickTimer) { clearInterval(tickTimer); tickTimer = null }
+
+  // 1. Ask the backend to quit gracefully (clean Dask shutdown).
+  try {
+    if (p.stdin && p.stdin.writable) {
+      p.stdin.write(JSON.stringify({ type: 'quit' }) + '\n')
+    }
+  } catch { /* stdin may already be torn down — fall through to tree-kill */ }
+
+  const pid = p.pid
+
+  // 2. Backstop: if it hasn't exited shortly, kill the whole process tree so no
+  //    Dask worker/nanny grandchildren are left behind.
+  if (options.immediate) {
+    killTreeNow(p, pid)
+    return
+  }
+  if (process.platform === 'win32') {
+    if (pid !== undefined) {
+      setTimeout(() => {
+        if (p.exitCode !== null || p.signalCode !== null) return  // already gone
+        try {
+          spawn('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore' })
+        } catch { try { p.kill() } catch { /* nothing else to do */ } }
+        // 5 s, not 1.5: Ground Crew's shutdown must send deapi's disconnect
+        // before dying — a taskkilled backend leaves a dead client session on
+        // the DE Server, which outlives the app. (Vendored change — hand-sync
+        // to the monorepo, where 1.5 s was sized for Dask teardown only.)
+      }, 5000)
+    } else {
+      try { p.kill() } catch { /* */ }
+    }
+  } else {
+    setTimeout(() => {
+      if (p.exitCode !== null || p.signalCode !== null) return
+      try { p.kill('SIGTERM') } catch { /* */ }
+      setTimeout(() => {
+        if (p.exitCode !== null || p.signalCode !== null) return
+        try { p.kill('SIGKILL') } catch { /* */ }
+      }, 1500)
+    }, 1500)
+  }
+}
+
+/**
+ * Kill the sidecar's whole process tree and return once the request has been
+ * made — no timers, so it still runs when the caller is about to end this
+ * process. `spawnSync` is the point: a detached `spawn` would only be queued.
+ */
+function killTreeNow(p: ChildProcess, pid: number | undefined): void {
+  if (p.exitCode !== null || p.signalCode !== null) return
+  if (process.platform === 'win32') {
+    if (pid !== undefined) {
+      try {
+        spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore' })
+        return
+      } catch { /* fall through to the direct kill */ }
+    }
+    try { p.kill() } catch { /* nothing else to do */ }
+    return
+  }
+  try { p.kill('SIGKILL') } catch { /* nothing else to do */ }
+  // The workers are grandchildren, so also target the child's process group
+  // when it leads one. A pid that leads no group simply has no group to match.
+  if (pid !== undefined) {
+    try { process.kill(-pid, 'SIGKILL') } catch { /* no such group */ }
+  }
+}