@alteriom/painlessmesh 1.9.19 → 1.10.0

package/CHANGELOG.md

@@ -7,12 +7,180 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.10.0] - 2026-08-12
+
+Feature release making the TCP connect-retry envelope tunable per mesh instance
+(#378), alongside two documentation corrections that retire long-standing claims
+the library never actually implemented (#385) and an example build fix (#360).
+
+**Upgrading is behaviour-neutral.** Every new setting defaults to the value that
+was previously hardcoded, so a sketch that does not call `setTcpRetryConfig()`
+behaves exactly as it did on 1.9.21. Nothing was removed: the deprecated queue
+macros keep their historical values for source compatibility.
+
+> **Note for npm users:** v1.9.21 was never published to npm — the `NPM_TOKEN`
+> used by CI had expired (#381), which failed the npm publish job while the
+> GitHub Release, GitHub Packages, PlatformIO and Arduino channels all succeeded.
+> npm's previous version is therefore **1.9.20**, and upgrading from npm brings
+> in both 1.9.21 and 1.10.0. See the 1.9.21 entry below for what that release
+> contained — it was a crash-fix release, and npm users have been missing it.
+
 ### Added
 
+- **User-configurable TCP retry parameters (#378)** — the five TCP connect
+  retry values that were hardcoded as `static const` in
+  `src/painlessmesh/tcp.hpp` are now tunable per mesh instance via
+  `mesh.setTcpRetryConfig()` / `mesh.getTcpRetryConfig()`, using the new
+  `painlessmesh::tcp::TcpRetryConfig` struct (`maxRetries`, `retryDelayMs`,
+  `stabilizationDelayMs`, `exhaustionReconnectDelayMs`,
+  `failureBlockDurationMs`). This lets latency-sensitive meshes (see
+  discussion #368), high-reliability industrial deployments and
+  battery-powered nodes each pick their own retry envelope without forking
+  the library.
+
+  The struct's defaults are spelled as the existing constants, so **behaviour
+  is unchanged for any sketch that does not call the new setter**, and the
+  constants themselves remain in place. `maxRetries` is clamped to 10 and
+  `retryDelayMs` to 50–60000 ms, since an unbounded retry count is a
+  heap/recursion hazard and a zero delay produces a hot reconnect loop; the
+  remaining fields accept 0 as a meaningful "disable this step" value.
+  New `examples/tcpRetryConfig/` demonstrates real-time, high-reliability and
+  battery-saver profiles.
+
 ### Changed
 
+- **`MessageQueue` documented honestly as a manual buffer (#385)** —
+  removed the "messages are automatically delivered when connection is
+  restored" claim from `MessageQueue` and the `mesh.enableMessageQueue`
+  / `queueMessage` / `flushMessageQueue` doc comments. Nothing in the
+  library ever transmitted queued messages or observed connectivity
+  changes; the app has always owned the send loop. The docs now say so,
+  and the `flushMessageQueue` example shows the intended pattern of
+  wiring the drain into `onLocalInternetChanged`.
+
+### Deprecated
+
+- **Compatibility queue macros kept as ignored no-ops (#385)** —
+  `MIN_FREE_MEMORY` and `MAX_MESSAGE_QUEUE` remain defined in
+  `painlessmesh/configuration.hpp` (and `test/boost/Arduino.h`) for
+  source compatibility, but nothing in the library reads them. They were
+  placeholders for the auto-flush behavior that never landed.
+  `MessageQueue` has always taken its own per-instance `maxSize`
+  constructor argument. Their historical default values
+  (`MIN_FREE_MEMORY 4000`, `MAX_MESSAGE_QUEUE 50`) are preserved so any
+  downstream code that referenced the macros keeps its prior behavior.
+
+### Fixed
+
+- **`bridge_failover` example failed to compile (#360)** — the two
+  `mesh.onBridgeCoordination*` lambdas referenced
+  `plugin::BridgeCoordinationPackage` with a bare `plugin::` prefix, but
+  `painlessMesh.h` only lifts `painlessmesh::logger` to global scope, so
+  the type did not resolve (`'plugin' does not name a type`). Both lambda
+  parameters are now fully qualified as
+  `painlessmesh::plugin::BridgeCoordinationPackage`, matching the
+  convention used across every other example (otaSender, namedMesh,
+  alteriom_*).
+
+## [1.9.21] - 2026-08-04
+
+Crash-fix release resolving a family of use-after-free bugs in the task and
+TCP-connection lifecycle. Root-caused and fixed by @vaz82 (PR #376) with
+reports and field testing from @fidla73 and @miloshev (issue #373); finalized
+with TaskScheduler's native self-destruct mechanism and regression coverage.
+
 ### Fixed
 
+- **Use-after-free in `Task::disable()` on connection teardown (#373)** —
+  `scheduleAsyncClientDeletion()`'s cleanup task deleted itself inside its
+  own `onDisable` callback, but TaskScheduler's `Task::disable()` writes to
+  the task object after `onDisable` returns. Crashed nodes (StoreProhibited,
+  `EXCVADDR 0x8`) on every peer disconnect. The cleanup task now uses
+  TaskScheduler's `_TASK_SELF_DESTRUCT` support (enabled in
+  `painlessTaskOptions.h`): the Scheduler deletes the task from within
+  `execute()`, safely outside the `disable()` call stack.
+- **`PackageHandler::stop()` destroying the currently-executing task** —
+  when `stop()` runs from within a task's own callback (bridge promotion
+  path), it destroyed that task's closure mid-execution via
+  `setCallback(NULL)`/`shared_ptr` release. `stop()` now accepts the
+  scheduler, detects the running task via `getCurrentTask()`, and leaves it
+  in `taskList` for safe reuse by `addTask()`.
+- **Stale `_pcb` window in `~BufferedConnection()`** — `client->close()` was
+  skipped when `freeable()` returned true, leaving a non-null-but-stale pcb
+  that lwIP's timers could recycle during the deferred-deletion window
+  (`heap_caps_free`/`memp_free` assertion failures, `tcp_arg()` wild-pointer
+  stores). `close()` is now called unconditionally at destruction.
+- **`onError`/`onConnect` double-handling race in `tcp::connect()`** — if
+  WiFi dropped as the TCP handshake completed, AsyncTCP could fire both
+  callbacks for the same `AsyncClient`, handing it to two owners and
+  scheduling its deletion twice. A shared claim guard now ensures exactly
+  one callback processes the client.
+- **Bridge promotion state capture** — the deferred stop/reinit lambda in
+  `promoteToBridge()` (and the isolated-node variant) now captures mesh
+  credentials, scheduler, and callback by value so `stop()` cannot mutate
+  them before the reinit reads them.
+- **Off-by-one buffer overflow in `ReceiveBuffer::push()`** — when a
+  received chunk was ≥ `TCP_MSS`, the null terminator was written one byte
+  past the end of the shared temp buffer, corrupting adjacent memory on
+  every large read. Found by the new AddressSanitizer CI job on its first
+  run; `read_len` now reserves one byte for the terminator.
+
+### Added
+
+- Regression test `catch_connection_cleanup.cpp` covering the #373
+  schedule → fire → self-destruct cleanup lifecycle and
+  `~BufferedConnection` churn.
+- AddressSanitizer job in CI (gcc + `-fsanitize=address`) so use-after-free
+  and double-free regressions in the task/connection lifecycle fail the
+  build instead of crashing devices in the field.
+
+## [1.9.20] - 2026-03-27
+
+### Added
+
+- **Bridge Coordination Monitoring Callbacks** - User-facing API for observing bridge coordination events
+  - `mesh.onBridgeCoordination(cb)` — fires on every coordination message (~30s per bridge)
+  - `mesh.onBridgeCoordinationChanged(cb)` — fires on state changes: "new", "updated", "lost"
+  - Works on both bridge and non-bridge nodes (monitoring is not bridge-only)
+  - Lost bridge detection with 60-second timeout
+  - 5 new test scenarios with 18 assertions for change detection logic
+
+### Fixed
+
+- **Full Repo Cleanup** - Comprehensive audit and cleanup of the entire codebase (#357)
+  - Fix double-free of mScheduler in ~Mesh() destructor
+  - Fix int8_t RSSI aggregation overflow (widened to int32_t)
+  - Fix Task object memory leak in scheduleAsyncClientDeletion
+  - Replace blocking delay(1000) with yield-based approach in bridge init
+  - Add max-iteration guard to getPathToNode (prevents infinite loop)
+  - Move static vars from connection.hpp to connection.cpp (ODR violation fix)
+  - Initialize shouldContainRoot to false (undefined behavior fix)
+  - Fix getAccurateTime() to always return seconds
+  - Fix cancelInternetRequest reentrancy via scheduled callback
+  - Widen BFS hop counter from uint8_t to uint16_t
+  - Remove dead revert path in promoteToBridge
+  - Cap knownBridgePeers at 32 entries
+  - Increase WiFi event semaphore timeout from 100 to 1000 ticks
+  - Inline getGatewayCount() to avoid temporary vector allocation
+  - Remove MessageQueue::reserve(1000) (wasted heap on ESP8266)
+  - Fix Timer::elapsed_us() to return microseconds on ESP32
+  - Cache hasActualInternetAccess() with 60s TTL
+  - Remove ~3,600 lines of dead code (unused classes, stubs, AI-generated shelf code)
+  - Remove 40 AI-generated markdown files from root directory
+  - Delete abandoned documentation systems (docs-website/, website/)
+  - Fix all CI/CD workflow action versions
+  - Remove 15 fake test files (only REQUIRE(true) assertions)
+  - Fix millis()/micros() test mocks to prevent uint32_t overflow
+- **Documentation Consistency** - Feature audit and doc fixes (#358)
+  - Fix README version (1.9.17 -> 1.9.20)
+  - Fix 6 broken documentation links
+  - Fix Message Queue API examples to use real enableMessageQueue/queueMessage API
+  - Remove non-existent onBridgeCoordination callback from examples
+  - Fix EnhancedStatusPackage type ID comment (203 -> 604)
+  - Rewrite Quick Start example to use TaskScheduler instead of delay()
+  - Remove dead conditional includes from painlessMesh.h
+  - Add missing examples to library.json
+
 ## [1.9.19] - 2025-12-21
 
 ### Fixed

package/README.md

@@ -4,7 +4,7 @@
 
 <div align="center">
 
-**Version 1.9.19** - Gateway connectivity error non-retryable fix for infrastructure issues
+**Version 1.10.0** - Tunable TCP connect-retry behaviour via `setTcpRetryConfig()` (#378)
 
 [![CI/CD Pipeline](https://github.com/Alteriom/painlessMesh/actions/workflows/ci.yml/badge.svg)](https://github.com/Alteriom/painlessMesh/actions/workflows/ci.yml)
 [![Documentation](https://github.com/Alteriom/painlessMesh/actions/workflows/docs.yml/badge.svg)](https://github.com/Alteriom/painlessMesh/actions/workflows/docs.yml)
@@ -209,11 +209,25 @@ mesh.initAsBridge(MESH_PREFIX, MESH_PASSWORD,
                   ROUTER_SSID, ROUTER_PASSWORD,
                   &userScheduler, MESH_PORT, 10);
 
-// Configure load balancing strategy
-mesh.setBridgeSelectionStrategy(ROUND_ROBIN);
+// Enable bridge failover for high availability
+mesh.enableBridgeFailover(true);
+
+// Monitor bridge coordination (fires every ~30s per bridge)
+mesh.onBridgeCoordination(
+  [](const plugin::BridgeCoordinationPackage& pkg, uint32_t fromNode) {
+    Serial.printf("Bridge %u: priority=%d, load=%d%%\n",
+                  fromNode, pkg.priority, pkg.load);
+  }
+);
 
-// Monitor bridge coordination
-mesh.onBridgeCoordination(&bridgeCoordinationCallback);
+// Get notified when bridge state changes
+mesh.onBridgeCoordinationChanged(
+  [](const plugin::BridgeCoordinationPackage& pkg, uint32_t fromNode,
+     TSTRING changeType) {
+    Serial.printf("Bridge %s: %u (role=%s)\n",
+                  changeType.c_str(), fromNode, pkg.role.c_str());
+  }
+);
 ```
 
 See [BRIDGE_TO_INTERNET.md](BRIDGE_TO_INTERNET.md) for multi-bridge documentation.
@@ -239,16 +253,11 @@ See [BRIDGE_TO_INTERNET.md](BRIDGE_TO_INTERNET.md) for multi-bridge documentatio
 **Example:**
 ```cpp
 // Enable message queue with max 100 messages
-mesh.enableMessageQueue(true);
-mesh.setMaxQueueSize(100);
+mesh.enableMessageQueue(true, 100);
 
 // Queue critical alarm message
 String criticalAlarm = "{\"sensor\":\"O2\",\"value\":2.5,\"alarm\":true}";
-mesh.queueMessage(criticalAlarm, CRITICAL);
-
-// Set callbacks
-mesh.onQueueFull(&queueFullCallback);
-mesh.onQueueFlushed(&queueFlushedCallback);
+mesh.queueMessage(bridgeNodeId, criticalAlarm);
 ```
 
 See [BRIDGE_TO_INTERNET.md](BRIDGE_TO_INTERNET.md) for message queue documentation.
@@ -393,46 +402,34 @@ If platformio is used to install the library, then the dependencies will be inst
 
 ```cpp
 #include "painlessMesh.h"
-#include "examples/alteriom/alteriom_sensor_package.hpp"
-
-using namespace alteriom;
 
-#define MESH_PREFIX     "AlteriomMesh"
-#define MESH_PASSWORD   "your_password"
-#define MESH_PORT       5555
+#define MESH_PREFIX "whateverYouLike"
+#define MESH_PASSWORD "somethingSneaky"
+#define MESH_PORT 5555
 
 Scheduler userScheduler;
 painlessMesh mesh;
 
-void setup() {
-    Serial.begin(115200);
-    mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT);
-    mesh.onReceive(&receivedCallback);
+Task taskSendMessage(TASK_SECOND * 30, TASK_FOREVER, []() {
+  String msg = "Hello from node ";
+  msg += mesh.getNodeId();
+  mesh.sendBroadcast(msg);
+});
+
+void receivedCallback(uint32_t from, String &msg) {
+  Serial.printf("Received from %u: %s\n", from, msg.c_str());
 }
 
-void loop() {
-    mesh.update();
-    
-    // Create and send sensor data
-    SensorPackage sensor;
-    sensor.temperature = 25.5;
-    sensor.humidity = 60.0;
-    sensor.sensorId = mesh.getNodeId();
-    sensor.timestamp = mesh.getNodeTime();
-    
-    mesh.sendBroadcast(sensor.toJsonString());
-    delay(30000); // Send every 30 seconds
+void setup() {
+  Serial.begin(115200);
+  mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT);
+  mesh.onReceive(&receivedCallback);
+  userScheduler.addTask(taskSendMessage);
+  taskSendMessage.enable();
 }
 
-void receivedCallback(uint32_t from, String& msg) {
-    JsonDocument doc;  // ArduinoJson v7
-    deserializeJson(doc, msg);
-    
-    if (doc["type"] == 200) { // SensorPackage
-        SensorPackage sensor(doc.as<JsonObject>());
-        Serial.printf("Sensor %u: %.1f°C, %.1f%% RH\n", 
-                     sensor.sensorId, sensor.temperature, sensor.humidity);
-    }
+void loop() {
+  mesh.update();
 }
 ```
 
@@ -563,14 +560,36 @@ These are the message types used by applications built on painlessMesh:
 - **Event Coordination** - Synchronized displays, distributed processing
 - **Bridge Networks** - Connect mesh to WiFi/Internet/MQTT - [📖 Bridge Guide](BRIDGE_TO_INTERNET.md)
 
-## Latest Release: v1.9.17 (December 21, 2025)
+## Latest Release: v1.10.0 (August 12, 2026)
+
+**Tunable TCP Connect-Retry Behaviour (issue #378)**
+
+- The five TCP connect-retry values that were hardcoded in `tcp.hpp` are now tunable per mesh instance via `mesh.setTcpRetryConfig()` / `mesh.getTcpRetryConfig()` (#378, PR #395)
+- Defaults match the previous constants exactly — **no behaviour change unless you call the setter**
+- New `examples/tcpRetryConfig/` with real-time, high-reliability and battery-saver profiles
+- `MessageQueue` documentation corrected: it is a manual buffer, never an auto-flush queue (#385)
+- `MIN_FREE_MEMORY` / `MAX_MESSAGE_QUEUE` deprecated as ignored no-ops, values preserved for source compatibility (#385)
+- Fixed `bridge_failover` example failing to compile on an unqualified `plugin::` type (#360)
+
+> **npm users:** v1.9.21 was never published to npm ([#381](https://github.com/Alteriom/painlessMesh/issues/381) — expired token). npm's previous version is 1.9.20, so upgrading from npm picks up both releases. GitHub, PlatformIO and Arduino were unaffected.
+
+**Previous Release: v1.9.21 (August 4, 2026)**
+
+**Crash Fixes: Task & TCP Connection Lifecycle (issue #373)**
+
+- Fixed use-after-free in `Task::disable()` that crashed nodes on every peer disconnect (#373, PR #376 by @vaz82)
+- Fixed `PackageHandler::stop()` destroying the currently-executing task during bridge promotion
+- Fixed stale-pcb heap corruption window in `~BufferedConnection()` and an `onError`/`onConnect` double-handling race
+- New AddressSanitizer CI job and regression test for the task/connection cleanup lifecycle
 
-**Documentation Enhancement & Package Organization**
+**Previous Release: v1.9.20 (March 27, 2026)** — Full repo cleanup, bug fixes & bridge coordination callbacks:
 
-- 📚 **Production-Level Documentation** - Removed phase terminology for clearer product positioning
-- 📦 **Complete Package Catalog** - All 19 application-level package types documented in numerical order
-- 🎯 **Enhanced Feature Clarity** - Improved Advanced Features section with comprehensive capability list
-- ✨ **Professional Quality** - Documentation suitable for enterprise adoption and production deployments
+- New `onBridgeCoordination()` and `onBridgeCoordinationChanged()` monitoring callbacks
+- Fixed 13 critical/high/medium bugs (double-free, RSSI overflow, memory leaks, blocking delays)
+- Removed ~3,600 lines of dead code and 40 AI-generated docs
+- Fixed all CI/CD workflows (corrected action versions)
+- Removed 15 fake test files, fixed test infrastructure
+- Documentation consistency audit — fixed broken links, API examples, version references
 
 **Recent Key Features (v1.9.0 - v1.9.16):**
 
@@ -578,16 +597,16 @@ These are the message types used by applications built on painlessMesh:
 - 🌉 **Improved Bridge Detection** - `getPrimaryBridge()` returns last known bridge when disconnected
 - ⚡ **Enhanced TCP Reliability** - Exponential backoff and increased retries for mesh connections
 - 🛡️ **Race Condition Fixes** - Improved bridge status and connection validation
-- 📦 **Consolidated Examples** - Streamlined to 14 essential examples
+- 📦 **Consolidated Examples** - Streamlined to 15 essential examples
 - ⚙️ **Configurable Election Timing** - Prevent split-brain with `setElectionStartupDelay()` and `setElectionRandomDelay()`
 
 **[📋 Full CHANGELOG](CHANGELOG.md)**
 
 ## Getting Help
 
-- **[FAQ](docs/troubleshooting/faq.md)** - Common questions and solutions
-- **[Common Issues](docs/troubleshooting/common-issues.md)** - Troubleshooting guide
-- **[GitHub Issues](https://github.com/Alteriom/painlessMesh/issues)** - Bug reports and feature requests  
+- **[FAQ](USER_GUIDE.md)** - Common questions and solutions
+- **[Common Issues](USER_GUIDE.md)** - Troubleshooting guide
+- **[GitHub Issues](https://github.com/Alteriom/painlessMesh/issues)** - Bug reports and feature requests
 - **[Community Forum](https://groups.google.com/forum/#!forum/painlessmesh-user)** - Community support
 - **[API Documentation](https://alteriom.github.io/painlessMesh/#/api/doxygen)** - Generated API docs
 
@@ -610,6 +629,28 @@ run-parts --regex catch_ bin/  # Run tests
 - **Dependencies**: ArduinoJson 7.x, TaskScheduler 4.x  
 - **Development**: CMake, Ninja, Boost (for desktop testing)
 
+### Testing Bridge/Internet Functionality
+
+painlessMesh includes a **Mock HTTP Server** for testing `sendToInternet()` functionality without requiring actual Internet connectivity. This enables:
+
+- 🚀 **Fast testing cycles** - Instant responses instead of waiting for external APIs
+- 🔧 **Offline development** - No Internet connection required
+- ✅ **Reproducible scenarios** - Control all test conditions precisely
+- 🤖 **CI/CD automation** - Automated testing in pipelines
+
+```bash
+# Start mock server
+cd test/mock-http-server
+python3 server.py
+
+# Test various HTTP scenarios
+curl http://localhost:8080/status/200     # Success
+curl http://localhost:8080/status/404     # Not Found
+curl http://localhost:8080/whatsapp?...   # WhatsApp API simulation
+```
+
+See [Mock HTTP Server Documentation](test/mock-http-server/README.md) for complete usage guide.
+
 ### CI/CD Pipeline
 
 painlessMesh features a state-of-the-art automated CI/CD pipeline:
@@ -651,8 +692,6 @@ We try to follow the [git flow](https://www.atlassian.com/git/tutorials/comparin
 
 If you like the library please consider supporting its development. Your contributions help me spend more time improving painlessMesh.
 
-[![PayPal Donation](paypal/qrcode.png)](https://www.paypal.com/paypalme/domlavoie)
-
 **[Donate via PayPal](https://www.paypal.com/paypalme/domlavoie)** • [dominic.lavoie@gmail.com](mailto:dominic.lavoie@gmail.com)
 
 ## 📚 Documentation
@@ -669,18 +708,18 @@ If you like the library please consider supporting its development. Your contrib
 ### 🚀 Quick Links
 
 **New to AlteriomPainlessMesh?**
-- [Quick Start](docs/getting-started/quickstart.md) - Get your first mesh running in 5 minutes
-- [Installation](docs/getting-started/installation.md) - Arduino IDE and PlatformIO setup
-- [First Mesh](docs/getting-started/first-mesh.md) - Build a multi-node network
+- [Quick Start](USER_GUIDE.md) - Get your first mesh running in 5 minutes
+- [Installation](USER_GUIDE.md) - Arduino IDE and PlatformIO setup
+- [First Mesh](USER_GUIDE.md) - Build a multi-node network
 
 **Reference Documentation:**
-- [Core API](docs/api/core-api.md) - painlessMesh class methods
-- [Alteriom Extensions](docs/alteriom/overview.md) - SensorPackage, CommandPackage, StatusPackage
-- [Examples](examples/) - 16 working examples for common scenarios
+- [Core API](USER_GUIDE.md) - painlessMesh class methods
+- [Alteriom Extensions](examples/alteriom/README.md) - SensorPackage, CommandPackage, StatusPackage
+- [Examples](examples/) - 15 working examples for common scenarios
 
 **Need Help?**
-- [FAQ](docs/troubleshooting/faq.md) - Frequently asked questions
-- [Common Issues](docs/troubleshooting/common-issues.md) - Troubleshooting guide
+- [FAQ](USER_GUIDE.md) - Frequently asked questions
+- [Common Issues](USER_GUIDE.md) - Troubleshooting guide
 - [GitHub Issues](https://github.com/Alteriom/painlessMesh/issues) - Bug reports and support
 
 ## 🔧 Quick API Reference

package/RELEASE_GUIDE.md

@@ -209,11 +209,22 @@ Each release triggers the **PlatformIO Library Publishing** workflow:
 
 #### Automatic Workflow Trigger
 
-The PlatformIO workflow automatically triggers on:
+The PlatformIO workflow is started by:
 
-- New GitHub releases (tags)
+- The `platformio-dispatch` job in **Automated Release**, which calls
+  `gh workflow run platformio-publish.yml --ref v<version> -f version=<version>`
+  right after the release is created
+- A GitHub release published by a human (via the UI or a PAT)
 - Manual workflow dispatch for testing
 
+> **Why the explicit dispatch?** `platformio-publish.yml` also listens for
+> `release: published`, but that event never fires for releases created by
+> `release.yml`: GitHub suppresses events raised by the built-in `GITHUB_TOKEN`.
+> `workflow_dispatch` is one of the two documented exceptions to that rule, so
+> the release workflow dispatches the publish explicitly and then verifies a run
+> actually appeared. Before this was added, PlatformIO publication silently did
+> not happen and had to be dispatched by hand (v1.9.21).
+
 ### PlatformIO Package Contents
 
 Published package includes:
@@ -454,13 +465,127 @@ npm run build
 npm run test
 ```
 
-**NPM Token Invalid**
+**NPM Token Expired / Invalid (`E401 Unauthorized`)**
+
+Symptom: the `npm-publish` job fails at *Verify NPM authentication* with
+`401 Unauthorized - GET https://registry.npmjs.org/-/whoami`. npm tokens
+expire; everything else in the release (tag, GitHub Release, zip asset,
+GitHub Packages, PlatformIO) succeeds independently, so **the release can look
+green-ish while npmjs.org is missing the version**. Always confirm with
+`npm view @alteriom/painlessmesh version`.
+
+Rotating the token is operator-only — it cannot be automated from CI:
+
 ```bash
-# Verify NPM authentication
-npm whoami
-# If not logged in: npm login
+# 1. Mint a fresh granular token, scoped to @alteriom/painlessmesh, with
+#    "Read and write" AND the "Bypass 2FA" option enabled  <-- see EOTP below
+#    https://www.npmjs.com/settings/tokens
+# 2. Verify the new token before saving it (recommended).
+#    Ask the registry directly — do NOT use a bare `npm whoami`, which answers
+#    for whatever credential your local ~/.npmrc already holds and will happily
+#    pass while the new token is bad:
+curl -sS -H "Authorization: Bearer <new-token>" \
+  https://registry.npmjs.org/-/whoami          # -> {"username":"..."} , not 401
+
+# 3. Update the NPM_TOKEN *organisation* secret — NOT a repository secret.
+#    painlessMesh has no repo-level NPM_TOKEN and must not gain one; see
+#    "Where NPM_TOKEN actually lives" below.
+#    https://github.com/organizations/Alteriom/settings/secrets/actions
+
+# 4a. Re-run the failed release job (keeps the original run's context)
+gh run rerun <run-id> --failed --repo Alteriom/painlessMesh
+
+# 4b. …or republish a missed version out-of-band. Pass the TAG as ref:
+#     without it the workflow builds the default branch, and if main has moved
+#     on since the tag it would upload today's code under the old version
+#     number. The workflow now refuses that outright — pass ref so you never
+#     have to rely on the guard catching it.
+gh workflow run manual-publish.yml --repo Alteriom/painlessMesh \
+  -f ref=v1.9.21 -f publish_npm=true -f publish_github=false
+
+# 5. Confirm the version actually landed
+npm view @alteriom/painlessmesh version
 ```
 
+#### Where NPM_TOKEN actually lives
+
+`NPM_TOKEN` is an **organisation** secret on `Alteriom`, shared by every repo
+that publishes to npm. painlessMesh has **no repository-level copy**, and adding
+one is a trap rather than a tightening:
+
+> A repository secret silently takes precedence over an organisation secret of
+> the same name. The repo then stops seeing org-wide rotations and keeps using
+> its own copy until that copy expires — which is invisible until a release day
+> fails.
+
+Two sibling repos already sit in that state, with repo-level `NPM_TOKEN` copies
+that shadow the org secret (`webhook-client`, `repository-metadata-manager`).
+Rotate the org secret and those two are still broken; delete the repo-level copy
+and they inherit the fresh one. Check before assuming a rotation reached a repo:
+
+```bash
+# Empty output = good (inherits the org secret)
+gh api repos/Alteriom/<repo>/actions/secrets \
+  --jq '.secrets[] | select(.name=="NPM_TOKEN") | "SHADOWED, updated \(.updated_at)"'
+```
+
+While rotating `NPM_TOKEN`, check `PLATFORMIO_AUTH_TOKEN` too — it expires the
+same way and `platformio-publish.yml` hard-fails on an invalid one.
+
+**NPM asks for a one-time password (`EOTP`)**
+
+Symptom: authentication *succeeds* — `npm whoami` prints the username — and then
+`npm publish` fails with:
+
+```
+npm error code EOTP
+npm error This operation requires a one-time password from your authenticator.
+```
+
+The token is valid but is not allowed to bypass 2FA, and CI has no authenticator
+to answer the challenge with. **A rotation that fixes `E401` lands here if the
+replacement token is minted without the bypass option** — which is what happened
+on the second rotation attempt for #381.
+
+npm removed the legacy token types (`read-only` / `automation` / `publish`) in
+**November 2025**; only granular access tokens exist now. The old *Automation*
+token bypassed 2FA by virtue of its type, so this was never a decision anyone had
+to make. On a granular token it is an explicit checkbox, and a token minted from
+muscle memory does not have it:
+
+> **Bypass 2FA** — required. Takes precedence over account-level and
+> package-level 2FA settings for publishing.
+
+Re-mint at <https://www.npmjs.com/settings/tokens> with *Read and write* on
+`@alteriom/painlessmesh` **and Bypass 2FA enabled**, update the secret, re-run.
+`npm whoami` cannot detect this ahead of time — it passes for both token kinds,
+so the failure necessarily surfaces at the publish call.
+
+### Trusted publishing (OIDC) — the way out of token rotation
+
+Both failures above are symptoms of the same thing: a long-lived credential that
+expires silently and is only exercised on release day. npm's replacement is
+**trusted publishing** — the workflow authenticates to npm over OIDC, and
+`NPM_TOKEN` stops existing.
+
+This is on a clock rather than merely being nicer: as of **2026-07-31** bypass-2FA
+tokens can no longer manage tokens, package access, or trusted-publishing config,
+and npm has targeted **January 2027** for removing *direct publish* from them —
+after which they can only stage a publish for a maintainer to approve with 2FA.
+The current setup stops working at that point.
+
+Requirements, none of which this repo blocks on today:
+
+| Requirement | Status here |
+|---|---|
+| `id-token: write` permission | ✅ already set in `release.yml` and `manual-publish.yml` |
+| npm CLI ≥ 11.5.1, Node ≥ 22.14.0 | ❌ workflows pin `node-version: '18'` — needs a bump |
+| Trusted publisher registered on npmjs.com | ❌ operator, one-time, per workflow file |
+
+The npmjs.com side is under *Package settings → Trusted publisher*: org
+`Alteriom`, repository `painlessMesh`, workflow filename `release.yml` (add a
+second entry for `manual-publish.yml` if that path should keep working).
+
 **GitHub Packages Authentication**
 ```bash
 # Check if GITHUB_TOKEN has packages:write permission
@@ -508,11 +633,18 @@ If this happens, you can manually publish packages:
 4. Click **Run workflow**
 
 The manual workflow will:
-- Read the current version from `library.properties`
+- Read the current version from `library.properties` and refuse to run if it
+  disagrees with `package.json` (npm publishes the `package.json` version)
+- Validate `NPM_TOKEN` against the registry before attempting to publish, so an
+  expired token fails immediately with rotation instructions
 - Publish to NPM (if selected)
 - Publish to GitHub Packages (if selected)
 - Show success/failure status for each
 
+It does **not** publish to the PlatformIO registry — use
+`gh workflow run platformio-publish.yml --ref v<version> -f version=<version>`
+for that.
+
 Alternatively, from command line:
 ```bash
 # Trigger via GitHub CLI
@@ -647,9 +779,16 @@ Monitor your releases:
 ### Required GitHub Secrets
 
 - `GITHUB_TOKEN`: Automatically provided by GitHub Actions
-- `NPM_TOKEN`: Required for NPM publishing (add in repository secrets)
+- `NPM_TOKEN`: Required for NPM publishing. Lives in the **Alteriom
+  organisation** secrets and is inherited — do not add a repository-level copy,
+  which would shadow it (see [Where NPM_TOKEN actually lives](#where-npm_token-actually-lives))
 - `PLATFORMIO_AUTH_TOKEN`: Required for PlatformIO Library Registry publishing
 
+Both `NPM_TOKEN` and `PLATFORMIO_AUTH_TOKEN` are user-minted tokens that
+**expire**. Their expiry is invisible until a release fails, so rotate them
+together and re-check after any expiry date you set. See
+[NPM Token Expired / Invalid](#-troubleshooting) for the rotation runbook.
+
 ### Repository Settings
 - **Actions**: Enabled with write permissions
 - **Packages**: Enabled for GitHub Packages publication

package/examples/alteriom/README.md

@@ -34,7 +34,7 @@ Broadcast package for sharing device health and status information.
 - `wifiStrength` - WiFi signal strength (0-100)
 - `firmwareVersion` - Current firmware version string
 
-### EnhancedStatusPackage (Type 203) - Phase 1
+### EnhancedStatusPackage (Type 604)
 Extended status package with comprehensive health metrics (18 fields).
 
 **Additional Fields:**
@@ -177,12 +177,12 @@ Complete Arduino sketch demonstrating:
 - Message type discrimination
 - Integration with painlessMesh
 
-### `phase1_features.ino` (NEW)
-Phase 1 OTA enhancement example demonstrating:
+### `phase1_features.ino`
+OTA enhancement example demonstrating:
 - Compressed OTA transfer infrastructure
 - Enhanced status reporting with comprehensive metrics
 - Alert system implementation
-- Usage patterns for Phase 1 features
+- Usage patterns for advanced features
 
 ### `metrics_health_node.ino` (NEW in v1.7.7)
 Comprehensive monitoring node example demonstrating: