rinchen · Jul 21, 2026 · Jul 21, 2026 · Jul 21, 2026 · Jul 21, 2026 · Jul 21, 2026
diff --git a/.githooks/pre-commit b/.githooks/pre-commit
@@ -178,10 +178,7 @@ pnpm run check:licenses || fail 'pnpm run check:licenses'
 
 # Audit only when dependency manifests change (CI / release still audit as configured).
 if [ "$deps_changed" -eq 1 ]; then
-  # npm retired legacy audit APIs (HTTP 410); pnpm 10.x still calls them. Use pnpm 11+ audit
-  # via dlx until packageManager is bumped (pnpm.io migration / issue #11265).
-  pnpm dlx --config.minimumReleaseAge=0 pnpm@11.13.0 --config.manage-package-manager-versions=false --config.pm-on-fail=ignore audit --audit-level=high \
-    || fail 'pnpm audit --audit-level=high'
+  pnpm audit --audit-level=high || fail 'pnpm audit --audit-level=high'
 else
   printf 'pre-commit: skip pnpm audit (no package.json / lockfile staged)\n' >&2
 fi

diff --git a/AGENTS.md b/AGENTS.md
@@ -8,7 +8,7 @@ This file is self-contained. ARCHITECTURE.md and CONTRIBUTING.md are human refer
 - **Testing:** Ship a passing test for behavioral changes; do not call the task done without it.
 - **Stateful/I/O code:** Preserve integrity on failure; document failure point, fallback, and logging where it matters.
 - **Pre-commit patience:** Pre-commit runs staged-related Vitest (`pnpm run test:staged`), staged ESLint, full typecheck, and path-gated `check:*` scripts. Typical small commits are much faster than a full suite; vitest infra / lockfile changes still force a full Vitest run. Be patient and let hooks finish — do not interrupt or force-skip. **PR CI** ([`tests.yaml`](.github/workflows/tests.yaml)) and **`pnpm run release`** (`scripts/release.sh`) always run the **full** Vitest suite (`pnpm run test:run`) plus ungated `check:*` scanners — never `test:staged` / `test:changed` / `vitest related`. Green pre-commit ≠ green CI or release.
-- **Fresh clone:** Before other setup work, run `node scripts/check-environment.mjs` (works before pnpm is installed). After `pnpm install`, re-run `pnpm run check:environment`. Fix required failures using the printed hints and `setup:*` scripts; optional warnings can wait.
+- **Fresh clone:** Before other setup work, run `node scripts/check-environment.mjs` (works before pnpm is installed). After `pnpm install`, re-run `pnpm run check:environment`. Fix required failures using the printed hints and `setup:*` scripts; optional warnings can wait. Wrong/outdated pnpm is also blocked by `scripts/check-package-manager.mjs` on `preinstall` and `pnpm run dev` (prints `corepack prepare` for the pinned version).
 
 ### Platform parity
 
@@ -115,7 +115,7 @@ Adding a cross-boundary feature:
 
 **Local Linux CI (optional):** Container mode — `act:ci`, `act:tests`, `act:pr`, … (needs Docker + act). Host mode — `act:ci:native`, `act:tests:native`, … (no Docker). See [docs/ci-cd.md](docs/ci-cd.md). macOS/Windows packaging uses native `dist:mac` / `dist:win`. **`dist:mac`** / **`dist:mac:publish`** always run **`scripts/verify-mac-packaging.mjs`** (ZIP + DMG symlink asserts, no raw `.app` CI uploads). macOS signing env (`CSC_LINK`, `CSC_KEY_PASSWORD`, `APPLE_ID`, `APPLE_APP_SPECIFIC_PASSWORD`, `APPLE_TEAM_ID`, `CSC_IDENTITY_AUTO_DISCOVERY`) is scoped to **`macos-latest`** jobs in `release.yaml` / `build.yaml`; partial-secret validation fails the release job when `CSC_LINK` is set but notarization secrets are missing.
 
-> **Update script sync:** When adding or removing packages from `patchedDependencies` in `package.json:230-237`, keep `WATCH_ENTRIES` in `scripts/update.sh:129-137` in sync so the script warns on version changes to every patched dependency. When adding or removing Ratspeak overlays under `reticulum-sidecar/patches/`, keep `RATSPEAK_PATCH_ENTRIES` in `scripts/update.sh` (`check_ratspeak_patches`) in sync — `pnpm run update` queries upstream PRs (rsReticulum / rsLXMF / rsNomad) and warns when a local overlay can be removed. `pnpm run update` also runs `rustup update` (or Homebrew `rust` on macOS without rustup) and `cargo build` in `reticulum-sidecar/` when `cargo` is on `PATH` (full-feature build includes `nomad-core` / rsNomad).
+> **Update script sync:** When adding or removing packages from `patchedDependencies` in `pnpm-workspace.yaml`, keep `WATCH_ENTRIES` in `scripts/update.sh` in sync so the script warns on version changes to every patched dependency. When adding or removing Ratspeak overlays under `reticulum-sidecar/patches/`, keep `RATSPEAK_PATCH_ENTRIES` in `scripts/update.sh` (`check_ratspeak_patches`) in sync — `pnpm run update` queries upstream PRs (rsReticulum / rsLXMF / rsNomad) and warns when a local overlay can be removed. `pnpm run update` also runs `rustup update` (or Homebrew `rust` on macOS without rustup) and `cargo build` in `reticulum-sidecar/` when `cargo` is on `PATH` (full-feature build includes `nomad-core` / rsNomad).
 
 **Pre-commit hook order:**
 

diff --git a/README.md b/README.md
@@ -409,7 +409,7 @@ See [Troubleshooting; macOS: File is damaged…](docs/troubleshooting.md#macos-f
 
 ## Run Locally
 
-**Prerequisites:** [Node.js 22.13.0+](https://nodejs.org/) and [pnpm 10+](https://pnpm.io/installation).
+**Prerequisites:** [Node.js 22.13.0+](https://nodejs.org/) and [pnpm 11+](https://pnpm.io/installation) (repo pins an exact `packageManager` — use Corepack). After a pnpm major bump, `pnpm install` / `pnpm run dev` print upgrade instructions if your local pnpm is too old.
 
 ```bash
 git clone https://github.com/Colorado-Mesh/mesh-client

diff --git a/docs/development-environment.md b/docs/development-environment.md
@@ -9,7 +9,7 @@ These requirements apply to all platforms.
 ### 1) Required software
 
 - Git
-- Node.js **22.13.0+** and pnpm **10+** (`package.json` `engines`; the repo pins **`packageManager`** to a specific pnpm release — use [Corepack](https://nodejs.org/api/corepack.html) or install a matching pnpm 10.x). `pnpm install` fails on engine mismatch.
+- Node.js **22.13.0+** and pnpm **11+** (`package.json` `engines`; the repo pins **`packageManager`** to a specific pnpm release — use [Corepack](https://nodejs.org/api/corepack.html) or install a matching pnpm 11.x). `pnpm install` fails on engine mismatch. After pulling a pnpm major bump, `preinstall` and `pnpm run dev` print an upgrade banner with the exact `corepack prepare` command if your local pnpm is too old or the wrong major.
 - [CI](https://github.com/Colorado-Mesh/mesh-client/blob/main/.github/workflows/ci.yaml) uses Node 22
 - Python 3 + `pip` (needed for MkDocs documentation build and yamllint)
 
@@ -441,14 +441,14 @@ flatpak run --command=flatpak-builder-lint org.freedesktop.Sdk \
 
 #### Lifecycle (automatic)
 
-| Script        | Description                                                   |
-| ------------- | ------------------------------------------------------------- |
-| `preinstall`  | Enforce pnpm as package manager (`only-allow pnpm`)           |
-| `postinstall` | Rebuild native Node modules for Electron + apply pnpm patches |
-| `prepare`     | Enable git hooks (`core.hooksPath = .githooks`)               |
-| `predist`     | Run `dedupe:dist` before `dist` packaging                     |
+| Script        | Description                                                           |
+| ------------- | --------------------------------------------------------------------- |
+| `preinstall`  | Require pnpm 11+ (`check-package-manager.mjs`) then `only-allow pnpm` |
+| `postinstall` | Rebuild native Node modules for Electron + apply pnpm patches         |
+| `prepare`     | Enable git hooks (`core.hooksPath = .githooks`)                       |
+| `predist`     | Run `dedupe:dist` before `dist` packaging                             |
 
-`postinstall` runs `scripts/rebuild-native.mjs` for Electron native addons and applies `pnpm.patchedDependencies` (Meshtastic JSR transports, MeshCore, Noble, `readable-stream`, `usb`, etc.). When bumping patched packages, update hashes under `patches/` and keep `WATCH_ENTRIES` in `scripts/update.sh` in sync — see [AGENTS.md](../AGENTS.md#6-commands--ci-checks).
+`postinstall` runs `scripts/rebuild-native.mjs` for Electron native addons and applies `patchedDependencies` from `pnpm-workspace.yaml` (Meshtastic JSR transports, MeshCore, Noble, `readable-stream`, `usb`, etc.). When bumping patched packages, update hashes under `patches/` and keep `WATCH_ENTRIES` in `scripts/update.sh` in sync — see [AGENTS.md](../AGENTS.md#6-commands--ci-checks).
 
 ### Dependabot dependency updates
 

diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
@@ -194,7 +194,7 @@ CI builds avoid both issues by using short paths and clean agents; local Windows
 
 **Symptom**: On Linux, the installed or AppImage build shows a main-process error when loading MQTT (`bl` → `mqtt-packet` → `mqtt` require stack).
 
-**Cause**: pnpm 10.29.3+ marks some `pnpm list --json` nodes as deduped; electron-builder can omit those transitive packages from `app.asar` unless a full copy exists at a predictable path. `mqtt` is loaded from `node_modules` at runtime (not bundled into the main esbuild output).
+**Cause**: With a hoisted `nodeLinker`, electron-builder can omit some transitive packages from `app.asar` unless a full copy exists at a predictable path (historically worsened when `pnpm list --json` marked nodes as deduped). `mqtt` is loaded from `node_modules` at runtime (not bundled into the main esbuild output).
 
 **Fix in this repo**: `readable-stream@^4.7.0` is a **direct** production dependency (with the existing `patches/readable-stream@4.7.0.patch` for Windows `process/` resolution). Do not remove it when bumping `mqtt` or pnpm. After `pnpm run dist:linux`, verify the asar contains `node_modules/readable-stream`, `node_modules/bl`, and `node_modules/mqtt`. See [electron-builder#9603](https://github.com/electron-userland/electron-builder/issues/9603) and [pnpm#10601](https://github.com/pnpm/pnpm/issues/10601).
 

diff --git a/org.coloradomesh.MeshClient.yml b/org.coloradomesh.MeshClient.yml
@@ -37,10 +37,11 @@ modules:
       prepend-path: /run/build/mesh-client/.pnpm-bin
       env:
         PNPM_HOME: /run/build/mesh-client/.pnpm
-        npm_config_cache: /run/build/mesh-client/.npm
+        pnpm_config_cache: /run/build/mesh-client/.npm
     build-commands:
-      # Install pnpm standalone binary (no network needed)
-      - install -Dm755 pnpm-standalone /run/build/mesh-client/.pnpm-bin/pnpm
+      # Install pnpm standalone binary from archived release (no network needed).
+      # Archive extracts to pnpm-vendor/ so the bundled dist/ does not collide with app dist/.
+      - install -Dm755 pnpm-vendor/pnpm /run/build/mesh-client/.pnpm-bin/pnpm
       # Offline install using generated-sources.json (retries @jsr temp-dir races).
       # --store-dir must use the sandbox-absolute path because the type:shell
       # source that writes .npmrc runs outside the sandbox, so $PWD there is
@@ -76,15 +77,15 @@ modules:
       - type: dir
         path: .
       - flatpak/generated-sources.json
-      - type: file
-        url: https://github.com/pnpm/pnpm/releases/download/v10.34.3/pnpm-linux-x64
-        sha256: d2529ffa064e08237a6d8344a3c54e12800a663d9976d481b2c441c10e914fc9
-        dest-filename: pnpm-standalone
+      - type: archive
+        url: https://github.com/pnpm/pnpm/releases/download/v11.15.1/pnpm-linux-x64.tar.gz
+        sha256: 0c1373b6390f6b89ff8b896d3647c9826577ddc49173a2f732da69b36569f9e0
+        dest: pnpm-vendor
         only-arches: [x86_64]
-      - type: file
-        url: https://github.com/pnpm/pnpm/releases/download/v10.34.3/pnpm-linux-arm64
-        sha256: ca4a85a4eb830713f1c37297d1a2b9fb9953719442bdb26daa8c64fadcc6c0b8
-        dest-filename: pnpm-standalone
+      - type: archive
+        url: https://github.com/pnpm/pnpm/releases/download/v11.15.1/pnpm-linux-arm64.tar.gz
+        sha256: 361e385867146972d0635a41a1871cb44c9c23f65acce78a5f1ca1d44ac0afcd
+        dest: pnpm-vendor
         only-arches: [aarch64]
       - type: archive
         url: https://github.com/electron/electron/releases/download/v41.10.2/electron-v41.10.2-linux-x64.zip

diff --git a/package.json b/package.json
@@ -87,7 +87,7 @@
     "format:check": "prettier --check \"**/*.{ts,tsx,js,jsx,json,css,md,sh}\" && sort-package-json --check --ignore \"**/*.md\"",
     "i18n:auto-translate": "node scripts/i18n-auto-translate.mjs",
     "i18n:prune-unused": "node scripts/prune-i18n-unused.mjs",
-    "preinstall": "pnpm dlx only-allow pnpm",
+    "preinstall": "node scripts/check-package-manager.mjs && pnpm dlx only-allow pnpm",
     "postinstall": "node scripts/rebuild-native.mjs",
     "lint": "eslint . --max-warnings 0",
     "lint:fix": "eslint . --fix --max-warnings 0",
@@ -216,54 +216,9 @@
     "vitest-axe": "1.0.0-pre.5",
     "zustand": "^5.0.14"
   },
-  "packageManager": "pnpm@10.34.3+sha512.f2c531b08829d7be7f03c90addc266615f9c5477463e4bf1d275cb263ce9ea57cf0d5599110d94649a9bb3fed9f0b5efcea74a7016b61532a24cb9ad87860c1d",
+  "packageManager": "pnpm@11.15.1+sha512.81350b07e53c9538a02f1f2303b4290fa2d7be04e56e2a970c4cc4b417dc761de196edabd49d55c7dc9580db81007c44143e4e3d7e462b3000d23c255122d065",
   "engines": {
     "node": ">=22.13.0",
-    "pnpm": ">=10.0.0"
-  },
-  "pnpm": {
-    "peerDependencyRules": {
-      "allowedVersions": {
-        "eslint": "10"
-      }
-    },
-    "onlyBuiltDependencies": [
-      "@meshtastic/core",
-      "@serialport/bindings-cpp",
-      "@stoprocent/bluetooth-hci-socket",
-      "@stoprocent/noble",
-      "electron",
-      "electron-winstaller",
-      "esbuild",
-      "usb"
-    ],
-    "overrides": {
-      "@babel/core": "^7.29.6",
-      "@electron/asar": "^4.0.1",
-      "@meshtastic/core": "npm:@jsr/meshtastic__core@^2.6.6",
-      "cacheable-request": "^10.0.0",
-      "form-data": "^4.0.6",
-      "js-yaml": "^4.2.0",
-      "markdown-it@<=14.1.1": ">=14.2.0",
-      "shell-quote": "^1.8.4",
-      "tar": "^7.5.16",
-      "tmp": "^0.2.6",
-      "undici": "^7.28.0",
-      "undici-types": "^7.28.0",
-      "ws": "^8.21.0"
-    },
-    "patchedDependencies": {
-      "@jsr/meshtastic__core@2.6.6": "patches/@jsr__meshtastic__core@2.6.6.patch",
-      "@jsr/meshtastic__transport-web-serial@0.2.5": "patches/@jsr__meshtastic__transport-web-serial@0.2.5.patch",
-      "@liamcottle/meshcore.js@1.13.0": "patches/@liamcottle__meshcore.js@1.13.0.patch",
-      "@stoprocent/noble@2.5.7": "patches/@stoprocent__noble@2.5.7.patch",
-      "debug@4.4.3": "patches/debug@4.4.3.patch",
-      "readable-stream@4.7.0": "patches/readable-stream@4.7.0.patch",
-      "usb@2.18.0": "patches/usb@2.18.0.patch"
-    },
-    "minimumReleaseAgeExclude": [
-      "lodash",
-      "lodash-es"
-    ]
+    "pnpm": ">=11.0.0"
   }
 }
diff --git a/patches/README.md b/patches/README.md
@@ -1,6 +1,6 @@
 # pnpm patchedDependencies
 
-Local overlays applied via `package.json` → `pnpm.patchedDependencies`. When bumping a patched package version, regenerate the patch hash under `patches/` and keep `WATCH_ENTRIES` in `scripts/update.sh` in sync.
+Local overlays applied via `pnpm-workspace.yaml` → `patchedDependencies`. When bumping a patched package version, regenerate the patch hash under `patches/` and keep `WATCH_ENTRIES` in `scripts/update.sh` in sync.
 
 | Patch | Upstream | Upstream PR / status |
 | ----- | -------- | -------------------- |