arrayview 0.31.2__tar.gz → 0.31.3__tar.gz

{arrayview-0.31.2 → arrayview-0.31.3}/.github/workflows/launch-contracts.yml

@@ -30,12 +30,12 @@ jobs:
         os: [ubuntu-latest, macos-latest, windows-latest]
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.12"
-      - uses: astral-sh/setup-uv@v6
-      - uses: actions/setup-node@v4
+      - uses: astral-sh/setup-uv@v8
+      - uses: actions/setup-node@v6
         with:
           node-version: "22"
       - run: uv sync --frozen --group dev --group test

{arrayview-0.31.2 → arrayview-0.31.3}/.mex/context/lifecycle.md

@@ -70,6 +70,13 @@ This contract describes who owns the backend, when it starts, and what closes it
 - `release_session()` is the session-release primitive.
 - Viewer WebSocket connect/disconnect owns active viewer counts.
 - URL panel disposal must release every SID encoded in the URL: `sid`, `compare_sid`, `compare_sids`, and `overlay_sid`.
+- Tunnel panel disposal posts release requests to the local backend immediately;
+  the forwarded public URL is display-only and is not the cleanup authority.
+- Reused file and collection sessions acquire one lease per tab, so closing one
+  tab cannot invalidate another tab that shares the same SID.
+- A VS Code readiness ACK includes the live opener version and is terminal only
+  after the requested SID exists and the viewer reports its first rendered frame.
+- Older ArrayView packages must not delete or downgrade a newer installed opener.
 - Tunnel registration cleanup must not remove live same-tunnel sibling windows.
 - Explicit cleanup wins over implicit disappearance.
 - Any VS Code extension source change must rebuild `src/arrayview/arrayview-opener.vsix` and keep the packaged version in sync.

{arrayview-0.31.2 → arrayview-0.31.3}/.mex/context/project-state.md

@@ -7,7 +7,7 @@ triggers:
   - "recent work"
   - "active feature"
   - "shipped recently"
-last_updated: 2026-06-30
+last_updated: 2026-07-13
 ---
 
 # Project State
@@ -21,7 +21,7 @@ last_updated: 2026-06-30
 - Backend transport: FastAPI HTTP/WebSocket is the single viewer transport; shared helpers keep route modules small for metadata/analysis, compare/diff, overlay compositing, and vector field layout/arrow sampling.
 - NIfTI spatial metadata, RAS resampling
 - Directory collections are header-scanned and lazy by default: compatible files form a dense virtual stack, mixed shapes use a ragged collection, and `--load lazy|eager` plus `--stack-policy auto|dense|ragged` make both choices explicit. Compressed NIfTI volumes use a byte-bounded LRU cache; `view_dir()` exposes the same controls.
-- VS Code extension v0.14.27 — stable window ID via `EnvironmentVariableCollection`; `arrayview.openInFloatingWindow` setting moves new tabs to a floating window; `view(arr, floating=True)` and `arrayview file.npy --floating` open in a floating window per-call regardless of global setting; remote/tunnel display uses the same forwarded HTTP/WebSocket path as local VS Code; floating mode uses a single persistent shell hub panel (`_shell.html`) so all arrays share one floating window as tabs instead of opening separate windows; second CLI calls inject tabs via `new_tab` postMessage relay (extension -> hub wrapper -> shell iframe)
+- VS Code extension v0.14.41 — stable per-window routing, queued concurrent requests, remote-only tunnel claims, live opener-version ACKs, first-frame readiness, and immediate local-backend session release. An installed-but-stale extension host now fails with a clear one-time reload instruction instead of opening an unverified blank tab; older cached ArrayView packages never delete a newer opener.
 - Colorbar refactor: `ColorBar` JS class partially migrated (in progress)
 - Colormap picker: `c` opens an expanded colorbar-island grid without changing the colormap; subsequent `c` taps cycle, hover/hjkl/arrows live-preview, Enter/click commits, Esc cancels, and auto-dismiss pauses while hovered
 - Cold-start loading spinner in VS Code and native shell
@@ -48,9 +48,10 @@ last_updated: 2026-06-30
   patient/modality directory layouts pair automatically. `--case-regex` remains
   an override for unusual layouts. CLI header scans show an in-place file counter
   and elapsed time on interactive terminals.
-- Reused collection sessions are protected by per-tab leases, including their
-  overlay sessions, and VS Code opener readiness now verifies the requested
-  session metadata before acknowledging `backend_ready`.
+- Reused file and collection sessions are protected by per-tab leases, including
+  collection overlay sessions. The VS Code opener verifies the local SID before
+  creating a panel and waits for the viewer's first rendered frame before
+  acknowledging `backend_ready`.
 - Filesystem picker endpoint (`GET /fs/list`) clamped to `$HOME`. Accepts `base_sid` + `mode` (`overlay` | `vectorfield`) to filter entries by a cheap header-shape peek (`.npy`, `.nii`/`.nii.gz`, `.h5`, `.zarr`); overlay mode requires identical shape, vectorfield mode requires base shape plus one axis of size 3
 - Island collapse affordance: inline `~` at the island's top-right animates the panel into the bottom-left `~` hint circle; external `~` hint only visible while the island is actually collapsed. New `/` hint circle at bottom-right opens the tool menu
 - Compare center tool menu: `/` now re-opens the last-used compare center mode from the tool menu, while compare pane header buttons select diff / overlay / wipe directly. Eligible two-array compare layouts can switch into a big-left arrangement with a wider center pane, and the diff colorbar now matches that center-pane width.

{arrayview-0.31.2 → arrayview-0.31.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arrayview
-Version: 0.31.2
+Version: 0.31.3
 Summary: Fast multi-dimensional array viewer
 Project-URL: Home, https://github.com/oscarvanderheide/arrayview
 Project-URL: Source, https://github.com/oscarvanderheide/arrayview

{arrayview-0.31.2 → arrayview-0.31.3}/docs/index.md

@@ -30,6 +30,8 @@ MATLAB and Julia setup: [MATLAB and Julia](foreign-hosts.md).
 
 Remote and tunnel setup: [Remote](remote.md).
 
+Stacked patient collections and masks: [Stack and Overlay Collections](stack-overlays.md).
+
 ## Formats
 
 `.npy` `.npz` `.nii` `.nii.gz` `.zarr` `.pt` `.h5` `.tif` `.mat`

{arrayview-0.31.2 → arrayview-0.31.3}/docs/loading.md

@@ -85,7 +85,7 @@ Native windows also show a static preview while the live viewer warms up.
 ```bash
 uvx arrayview base.npy moving.npy           # compare mode
 uvx arrayview volume.nii.gz --overlay mask.nii.gz
-uvx arrayview volume.nii.gz --overlay "ground truth=mask.nii.gz"
+uvx arrayview volume.nii.gz --overlay "ground truth=mask_gt.nii.gz" --overlay "prediction=mask_pred.nii.gz"
 ```
 
 An unnamed overlay uses the filename stem as its display name (`mask` above).
@@ -99,8 +99,7 @@ shows all overlays at once.
 
 ## Directory Pattern Collections
 
-Use `--stack` when reviewing many arrays. Passing a directory scans supported
-files recursively; passing patterns keeps the aligned channel/overlay workflow.
+Use `--stack` when reviewing many arrays.
 
 ```bash
 uvx arrayview --stack scans/
@@ -115,48 +114,8 @@ dense` requires matching shapes, while `--stack-policy ragged` forces collection
 semantics. `--load eager` is intended for small datasets that should be loaded
 up front.
 
-Positional patterns become a channel/modality axis:
-
-```bash
-uvx arrayview --stack "data/**/*_0000.nii.gz" "data/**/*_0001.nii.gz"
-```
-
-Overlays become named recursive patterns:
-
-```bash
-uvx arrayview --stack \
-  "data/**/*_0000.nii.gz" \
-  "data/**/*_0001.nii.gz" \
-  --overlay "gt=data/**/labels/**/*.nii.gz" \
-  --overlay "pred=data/**/pred/**/*.nii.gz"
-```
-
-When every case has a directory containing separately named masks,
-`--overlay-dir` discovers one overlay role per filename. Masks that are absent
-for a case are shown as empty. ArrayView infers the shared case directory from
-layouts such as `sub-0001/T1_W/` and `sub-0001/masks/`:
-
-```bash
-uvx arrayview --stack "data/*/T1_W/*.nii.gz" \
-  --overlay-dir "data/*/masks"
-```
-
-Repeat `--overlay-dir` to combine masks from multiple per-case directories.
-
-ArrayView pairs files by sorted match order. The first match from each pattern
-belongs to the first case, the second match belongs to the second case, and so
-on. Use `--dry-run` to inspect matches without opening a viewer.
-
-```bash
-uvx arrayview --stack "data/**/*_0000.nii.gz" --overlay "gt=data/**/labels/*.nii.gz" --dry-run
-```
-
-For unusual or ambiguous layouts, pass a regex with a `case` group to override
-automatic directory inference:
-
-```bash
-uvx arrayview --stack "data/**/*.nii.gz" --case-regex "(?P<case>patient-[0-9]+)"
-```
+Pattern collections, named overlays, multiple overlays, and `--overlay-dir`:
+[Stack and Overlay Collections](stack-overlays.md).
 
 ## NIfTI Series (4D/5D from a directory)
 

arrayview-0.31.3/docs/stack-overlays.md

@@ -0,0 +1,129 @@
+# Stack and Overlay Collections
+
+Review many arrays with aligned image and mask patterns.
+
+## Patient Stack
+
+```bash
+uvx arrayview --stack "data/*/T1w.nii.gz"
+```
+
+`*` matches one path segment. `**` matches recursively:
+
+```bash
+uvx arrayview --stack "data/**/*.nii.gz"
+```
+
+ArrayView sorts matches and adds a collection index dimension. Use `--dry-run`
+to inspect pairings without opening the viewer:
+
+```bash
+uvx arrayview --stack "data/*/T1w.nii.gz" --dry-run
+```
+
+## MR Contrasts
+
+```bash
+uvx arrayview --stack \
+  "data/*/T1w.nii.gz" \
+  "data/*/T2w.nii.gz" \
+  "data/*/FLAIR.nii.gz"
+```
+
+Each positional pattern becomes a contrast dimension. The first `T1w`, first
+`T2w`, and first `FLAIR` belong to patient 1; the second match from each pattern
+belongs to patient 2.
+
+For ambiguous layouts, define the patient key:
+
+```bash
+uvx arrayview --stack "data/**/*.nii.gz" \
+  --case-regex "(?P<case>sub-[0-9]+)"
+```
+
+## Ragged Shapes
+
+```bash
+uvx arrayview --stack "data/*/T1w.nii.gz" --stack-policy ragged
+```
+
+`--stack-policy auto` uses a dense stack when shapes match and ragged mode when
+they do not. `--stack-policy dense` requires matching shapes.
+
+## One Overlay
+
+```bash
+uvx arrayview --stack "data/*/T1w.nii.gz" \
+  --overlay "lesion=data/*/masks/lesion.nii.gz"
+```
+
+Use `name=pattern` to control the overlay label. Without `name=`, the filename
+stem is used.
+
+## Multiple Overlays
+
+```bash
+uvx arrayview --stack "data/*/T1w.nii.gz" \
+  --overlay "gt=data/*/masks/gt.nii.gz" \
+  --overlay "pred=data/*/masks/pred.nii.gz"
+```
+
+Overlays are paired to cases by sorted match order unless `--case-regex` is
+provided.
+
+## Overlay Directories
+
+```bash
+uvx arrayview --stack "data/*/T1w.nii.gz" \
+  --overlay-dir "data/*/masks"
+```
+
+`--overlay-dir` creates one overlay role per mask filename inside each matched
+directory. Missing masks are shown as empty overlays.
+
+Repeat it to combine mask folders:
+
+```bash
+uvx arrayview --stack "data/*/T1w.nii.gz" \
+  --overlay-dir "data/*/manual_masks" \
+  --overlay-dir "data/*/model_masks"
+```
+
+## Complete Example
+
+```text
+data/
+  sub-001/
+    anat/T1w.nii.gz
+    anat/T2w.nii.gz
+    masks/lesion.nii.gz
+    masks/edema.nii.gz
+  sub-002/
+    anat/T1w.nii.gz
+    anat/T2w.nii.gz
+    masks/lesion.nii.gz
+```
+
+```bash
+uvx arrayview --stack \
+  "data/*/anat/T1w.nii.gz" \
+  "data/*/anat/T2w.nii.gz" \
+  --overlay-dir "data/*/masks" \
+  --stack-policy auto \
+  --dry-run
+```
+
+Remove `--dry-run` to open the viewer.
+
+## Compressed NIfTI Performance
+
+`.nii.gz` files are lazy through nibabel, but gzip compression limits random
+slice access. Large compressed collections can feel slower when scrolling across
+many patients or contrasts.
+
+For repeated review, prefer uncompressed `.nii`, chunked `.zarr`, or a local
+fast disk cache. Use `--load eager` only for small collections that fit in RAM:
+
+```bash
+uvx arrayview --stack "data/*/T1w.nii.gz" --load eager
+```

{arrayview-0.31.2 → arrayview-0.31.3}/mkdocs.yml

@@ -24,6 +24,7 @@ extra_css:
 nav:
   - Home: index.md
   - Loading Arrays: loading.md
+  - Stack and Overlays: stack-overlays.md
   - Viewing: viewing.md
   - Comparing: comparing.md
   - Display: display.md

{arrayview-0.31.2 → arrayview-0.31.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "arrayview"
-version = "0.31.2"
+version = "0.31.3"
 description = "Fast multi-dimensional array viewer"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.12"

{arrayview-0.31.2 → arrayview-0.31.3}/src/arrayview/_routes_loading.py

@@ -141,7 +141,8 @@ def register_loading_routes(app, *, notify_shells, setup_rgb) -> None:
         else:
             for existing in SESSIONS.values():
                 if existing.filepath and os.path.abspath(existing.filepath) == abs_path:
-                    return {"sid": existing.sid, "name": existing.name, "notified": False}
+                    if acquire_session_leases([existing.sid]):
+                        return {"sid": existing.sid, "name": existing.name, "notified": False}
         if not dir_patterns and not os.environ.get("ARRAYVIEW_SKIP_RAM_GUARD"):
             from ._io import FULL_LOAD_EXTS
 

{arrayview-0.31.2 → arrayview-0.31.3}/src/arrayview/_session.py

@@ -283,6 +283,7 @@ class Session:
         self.fft_original_data = None
         self.fft_axes = None
         self.data_version = 0  # incremented by /reload when file is reloaded
+        self.viewer_leases = 1  # one release is required for each tab using this SID
 
         self.rgb_axis = None  # set by _setup_rgb(); axis index in actual shape
         self.spatial_shape = data.shape  # shape without rgb_axis (set by _setup_rgb)

{arrayview-0.31.2 → arrayview-0.31.3}/src/arrayview/_vscode_browser.py

@@ -16,7 +16,7 @@ from enum import Enum
 
 from arrayview._session import _vprint
 from arrayview._platform import _in_vscode_terminal, _is_vscode_remote
-from arrayview._vscode_extension import _configure_vscode_port_preview, _ensure_vscode_extension, _VSCODE_EXT_FRESH_INSTALL
+from arrayview._vscode_extension import _configure_vscode_port_preview, _ensure_vscode_extension
 from arrayview._vscode_signal import (
     AckState,
     _open_via_signal_file,
@@ -133,9 +133,13 @@ def _open_browser(
         if is_remote:
             # Remote/tunnel: install extension + write signal file.
             ext_ok = _ensure_vscode_extension()
-            if ext_ok and _VSCODE_EXT_FRESH_INSTALL:
-                time.sleep(1.5)
-
+            from arrayview import _vscode_extension as _extension_state
+            if not ext_ok and _extension_state._VSCODE_EXT_RELOAD_REQUIRED:
+                return OpenResult(
+                    OpenState.FAILED,
+                    "vscode-extension",
+                    "ArrayView updated its VS Code opener; reload this VS Code window once, then retry",
+                )
             # URL-based mode: port is forwarded by VS Code and the viewer
             # connects via WebSocket through the devtunnel.
             _configure_vscode_port_preview(parsed_port)
@@ -172,8 +176,13 @@ def _open_browser(
             # Local VS Code terminal (or --window vscode forced): install extension + signal file.
             _configure_vscode_port_preview(parsed_port)
             ext_ok = _ensure_vscode_extension()
-            if ext_ok and _VSCODE_EXT_FRESH_INSTALL:
-                time.sleep(1.5)
+            from arrayview import _vscode_extension as _extension_state
+            if not ext_ok and _extension_state._VSCODE_EXT_RELOAD_REQUIRED:
+                return OpenResult(
+                    OpenState.FAILED,
+                    "vscode-extension",
+                    "ArrayView updated its VS Code opener; reload this VS Code window once, then retry",
+                )
             # Always write the signal file: the extension may already be
             # installed even if _ensure failed (e.g. `code` CLI not found).
             request = _open_via_signal_file(

{arrayview-0.31.2 → arrayview-0.31.3}/src/arrayview/_vscode_extension.py

@@ -5,7 +5,9 @@ from __future__ import annotations
 import json
 import os
 import re
+import signal
 import subprocess
+import time
 import zipfile
 from importlib.resources import files as _pkg_files
 
@@ -44,7 +46,8 @@ def _vscode_app_bundle() -> str | None:
 
 _VSCODE_EXT_INSTALLED = False  # cached so we only check once per process
 _VSCODE_EXT_FRESH_INSTALL = False  # True if we just installed it this session
-_VSCODE_EXT_VERSION = "0.14.40"  # current bundled extension version
+_VSCODE_EXT_RELOAD_REQUIRED = False  # installed files are newer than the live host
+_VSCODE_EXT_VERSION = "0.14.41"  # current bundled extension version
 
 def _bundled_vscode_vsix_version(vsix_path: str) -> str | None:
     """Return the bundled opener extension version recorded inside the VSIX."""
@@ -92,19 +95,43 @@ def _patch_vscode_extension_metadata(version: str) -> None:
             )
 
 
-def _remove_old_extension_versions(current_version: str) -> None:
-    """Delete extension directories for versions older than current_version.
+def _version_tuple(version: str) -> tuple[int, ...] | None:
+    """Return a numeric version tuple, or ``None`` for unknown formats."""
+    try:
+        return tuple(int(part) for part in version.split("."))
+    except (AttributeError, TypeError, ValueError):
+        return None
+
+
+def _extension_bases(*, remote: bool | None = None) -> tuple[str, ...]:
+    """Return extension roots for the active VS Code host."""
+    local = os.path.expanduser("~/.vscode/extensions")
+    remote_base = os.path.expanduser("~/.vscode-server/extensions")
+    if remote is True:
+        if os.path.isdir(os.path.expanduser("~/.vscode-server")):
+            return (remote_base,)
+        # `code tunnel` uses ~/.vscode/extensions on the remote host, while
+        # Remote-SSH uses ~/.vscode-server/extensions.
+        return (local,)
+    if remote is False:
+        return (local,)
+    return (local, remote_base)
+
+
+def _remove_old_extension_versions(
+    current_version: str, *, remote: bool | None = None
+) -> None:
+    """Delete older extension directories without ever deleting a newer build.
 
     When multiple versions of arrayview-opener are installed side-by-side,
     VS Code may load an older version instead of the latest.  Removing stale
     directories ensures the correct version is picked up on the next reload.
+    Cleanup is scoped to the active local or remote extension host.
     """
     import shutil
 
-    for ext_base in (
-        os.path.expanduser("~/.vscode-server/extensions"),
-        os.path.expanduser("~/.vscode/extensions"),
-    ):
+    current_key = _version_tuple(current_version)
+    for ext_base in _extension_bases(remote=remote):
         if not os.path.isdir(ext_base):
             continue
         try:
@@ -118,6 +145,9 @@ def _remove_old_extension_versions(current_version: str) -> None:
             version_str = entry[len(prefix) :]
             if version_str == current_version:
                 continue  # keep
+            version_key = _version_tuple(version_str)
+            if current_key is None or version_key is None or version_key > current_key:
+                continue
             old_dir = os.path.join(ext_base, entry)
             try:
                 shutil.rmtree(old_dir)
@@ -126,7 +156,12 @@ def _remove_old_extension_versions(current_version: str) -> None:
                 _vprint(f"[ArrayView] could not remove {entry}: {exc}", flush=True)
 
 
-def _extension_on_disk(version: str, vsix_path: str | None = None) -> bool:
+def _extension_on_disk(
+    version: str,
+    vsix_path: str | None = None,
+    *,
+    remote: bool | None = None,
+) -> bool:
     """Return True if the extension directory for *version* exists on disk.
 
     When *vsix_path* is given, also verifies that the installed extension
@@ -136,10 +171,7 @@ def _extension_on_disk(version: str, vsix_path: str | None = None) -> bool:
     """
     import hashlib
 
-    for base in (
-        os.path.expanduser("~/.vscode/extensions"),
-        os.path.expanduser("~/.vscode-server/extensions"),
-    ):
+    for base in _extension_bases(remote=remote):
         ext_dir = os.path.join(base, f"arrayview.arrayview-opener-{version}")
         if not os.path.isdir(ext_dir):
             continue
@@ -165,6 +197,88 @@ def _extension_on_disk(version: str, vsix_path: str | None = None) -> bool:
     return False
 
 
+def _newer_extension_on_disk(version: str, *, remote: bool) -> str | None:
+    """Return the newest installed opener newer than *version*, if any."""
+    wanted = _version_tuple(version)
+    if wanted is None:
+        return None
+    prefix = "arrayview.arrayview-opener-"
+    newer: list[tuple[tuple[int, ...], str]] = []
+    for base in _extension_bases(remote=remote):
+        try:
+            entries = os.listdir(base)
+        except OSError:
+            continue
+        for entry in entries:
+            if not entry.startswith(prefix):
+                continue
+            candidate = entry[len(prefix) :]
+            key = _version_tuple(candidate)
+            if key is not None and key > wanted:
+                newer.append((key, candidate))
+    return max(newer)[1] if newer else None
+
+
+def _active_extension_version() -> str | None:
+    """Return the opener version advertised by this terminal's live host."""
+    window_id = os.environ.get("ARRAYVIEW_WINDOW_ID")
+    if not window_id:
+        ipc = _find_vscode_ipc_hook()
+        if ipc:
+            import hashlib
+
+            window_id = hashlib.sha256(ipc.encode()).hexdigest()[:16]
+    if not window_id:
+        return None
+    registration = os.path.expanduser(f"~/.arrayview/window-{window_id}.json")
+    try:
+        with open(registration) as file:
+            value = json.load(file).get("extensionVersion")
+        # An existing registration without a version belongs to a legacy host.
+        return value if isinstance(value, str) else ""
+    except (OSError, TypeError, ValueError):
+        return None
+
+
+def _wait_for_active_extension_version(version: str, timeout: float = 15.0) -> bool:
+    """Wait for an updated extension host registration after installation."""
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if _active_extension_version() == version:
+            return True
+        time.sleep(0.1)
+    return _active_extension_version() == version
+
+
+def _run_extension_installer(command: list[str], env: dict[str, str]) -> subprocess.CompletedProcess:
+    """Run VS Code's installer without leaving its server-cli child behind."""
+    process = subprocess.Popen(
+        command,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        env=env,
+        start_new_session=os.name != "nt",
+    )
+    try:
+        stdout, stderr = process.communicate(timeout=30)
+    except subprocess.TimeoutExpired:
+        if os.name == "nt":
+            process.kill()
+        else:
+            os.killpg(process.pid, signal.SIGTERM)
+        try:
+            process.communicate(timeout=2)
+        except subprocess.TimeoutExpired:
+            if os.name == "nt":
+                process.kill()
+            else:
+                os.killpg(process.pid, signal.SIGKILL)
+            process.communicate()
+        raise
+    return subprocess.CompletedProcess(command, process.returncode, stdout, stderr)
+
+
 def _ensure_vscode_extension() -> bool:
     """Install the bundled arrayview-opener VS Code extension for local VS Code use.
 
@@ -180,9 +294,9 @@ def _ensure_vscode_extension() -> bool:
     The authoritative version is read from the bundled VSIX — no hardcoded
     version constant needed.
     """
-    global _VSCODE_EXT_INSTALLED, _VSCODE_EXT_FRESH_INSTALL
-    if _VSCODE_EXT_INSTALLED:
-        return True
+    global _VSCODE_EXT_INSTALLED, _VSCODE_EXT_FRESH_INSTALL, _VSCODE_EXT_RELOAD_REQUIRED
+    _VSCODE_EXT_FRESH_INSTALL = False
+    _VSCODE_EXT_RELOAD_REQUIRED = False
 
     vsix_path = str(_pkg_files("arrayview").joinpath("arrayview-opener.vsix"))
     if not os.path.isfile(vsix_path):
@@ -195,8 +309,18 @@ def _ensure_vscode_extension() -> bool:
     # Fast path: correct version and content already installed — no reinstall
     # needed.  Reinstalling with --force triggers an extension-host reload,
     # which creates a ~10-15s gap during which the signal file can be missed.
-    _remove_old_extension_versions(ext_version)
-    if _extension_on_disk(ext_version, vsix_path):
+    is_remote = _is_vscode_remote()
+    active_version = _active_extension_version()
+    if _extension_on_disk(ext_version, vsix_path, remote=is_remote):
+        if active_version not in (None, ext_version):
+            _VSCODE_EXT_RELOAD_REQUIRED = True
+            _vprint(
+                f"[ArrayView] opener v{ext_version} is installed, but this VS Code "
+                "window is still running an older extension host; reload this window",
+                flush=True,
+            )
+            return False
+        _remove_old_extension_versions(ext_version, remote=is_remote)
         _VSCODE_EXT_INSTALLED = True
         _vprint(
             f"[ArrayView] extension v{ext_version} already installed — skipping reinstall",
@@ -204,6 +328,23 @@ def _ensure_vscode_extension() -> bool:
         )
         return True
 
+    newer_version = _newer_extension_on_disk(ext_version, remote=is_remote)
+    if newer_version is not None:
+        if active_version not in (None, newer_version):
+            _VSCODE_EXT_RELOAD_REQUIRED = True
+            _vprint(
+                f"[ArrayView] newer opener v{newer_version} is installed, but this "
+                "VS Code window is still running an older extension host; reload this window",
+                flush=True,
+            )
+            return False
+        _VSCODE_EXT_INSTALLED = True
+        _vprint(
+            f"[ArrayView] newer extension v{newer_version} is installed — keeping it",
+            flush=True,
+        )
+        return True
+
     code = _find_code_cli()
     if not code:
         return False
@@ -214,12 +355,8 @@ def _ensure_vscode_extension() -> bool:
         env["VSCODE_IPC_HOOK_CLI"] = ipc
 
     try:
-        r = subprocess.run(
-            [code, "--install-extension", vsix_path, "--force"],
-            capture_output=True,
-            text=True,
-            timeout=30,
-            env=env,
+        r = _run_extension_installer(
+            [code, "--install-extension", vsix_path, "--force"], env
         )
         combined = (r.stdout or "") + (r.stderr or "")
         install_failed = (
@@ -247,9 +384,23 @@ def _ensure_vscode_extension() -> bool:
                 pass  # non-critical
             _VSCODE_EXT_INSTALLED = True
             _VSCODE_EXT_FRESH_INSTALL = True
+            _remove_old_extension_versions(ext_version, remote=is_remote)
+            if active_version not in (None, ext_version):
+                if not _wait_for_active_extension_version(ext_version):
+                    _VSCODE_EXT_RELOAD_REQUIRED = True
+                    _vprint(
+                        "[ArrayView] VS Code installed the new opener, but this window "
+                        "is still running the old extension host; reload this VS Code window",
+                        flush=True,
+                    )
+                    return False
             return True
+        if active_version not in (None, ext_version):
+            _VSCODE_EXT_RELOAD_REQUIRED = True
         print(f"[ArrayView] extension install failed: {combined.strip()!r}", flush=True)
     except Exception as exc:
+        if active_version not in (None, ext_version):
+            _VSCODE_EXT_RELOAD_REQUIRED = True
         print(f"[ArrayView] extension install error: {exc}", flush=True)
     return False