signalk-pypilot-newui 2.9.0 → 2.11.0

package/CHANGELOG.md

@@ -1,5 +1,103 @@
 # Changelog
 
+## 2.10.0 — 2026-09-27 — Sea-trial wind-mode fixes + maneuver forensics
+
+Rolls up Rev309 through Rev323. Between 2.9.0 (Rev280) and 2.10.0 the
+plugin absorbed a sea trial (2026-09-25) that surfaced several critical
+gaps in the wind-mode workflow, plus a new forensics module so future
+sea trials can be audited offline.
+
+### Added
+
+- **Maneuver Trace Log** (Rev322, opt-in). Every user-driven action from
+  the visor — aproado / empopado pick, tack tap, mode change, target PUT,
+  engage / disengage — is recorded together with pypilot state right
+  before the command AND 300 ms after. Pair pre/post makes it trivial
+  to answer "did the pilot actually obey?". Files land as JSONL under
+  `<plugin data dir>/maneuver-trace/`. New endpoints:
+  `GET|POST /maneuver-trace/{status,start,stop,event}` +
+  `GET /maneuver-trace/tail?n=N`. Setup card "Maneuver trace
+  (sea-trial forensics)" toggles it on the fly, off by default.
+- **Empopado pseudo-mode** (Rev313 → Rev320) — mirror of Aproado for the
+  other extreme: bring the boat to TWA ≈ 180° so the mainsail flogs the
+  least while striking sail. Full HUD (choosing → transit → active),
+  hot gains at latch (P × 1.5, D × 1.7, servo slew × 1.3), audible
+  warning when `|TWA| < 160°` sustained 1 s ("empopado inestable"),
+  auto-cancel when `|TWA| < 140°` sustained 2.5 s. Restore in order
+  hot gains → profile → mode → target → engaged on SALIR / cancel.
+- **Attitude safety alarms** (Rev299 / I1) — `attitude-heel-extreme` and
+  `attitude-pitch-extreme` rules with configurable thresholds
+  (`alarmAttitudeHeelDeg`, `alarmAttitudePitchDeg`), off by default so
+  a fresh install never disarms on the dock.
+- **Roll feed-forward** (Rev282+) and **Post-tack catch-up** (Rev299)
+  publish diagnostic paths under
+  `steering.autopilot.pypilot.tuning.rollFf.*` and `.tackCatchup.*`.
+  Both are currently `appliedToAp: false` — computed and observable
+  but not yet fed to the pilot; a later release flips the switch after
+  sea trial validation.
+- **Leeway estimator** (Rev298 / H4) publishing
+  `steering.autopilot.pypilot.derived.leewayRad` from the classical
+  `drift_deg = adj * heel_deg / bsp_kn²` formula. Opt-in via
+  `leewayAdjustment > 0`, kept off the canonical `performance.leeway`
+  path so it never overwrites `signalk-derived-data`.
+- **Failsafe boat speed** (Rev299 / H2) — when both BSP and SOG go
+  missing, the plugin injects a configurable knots value so downstream
+  wind / leeway calculations keep producing plausible numbers.
+- **Profile default persistence fix** (Rev310) — opening the visor from
+  a second device no longer silently overwrites the pypilot profile with
+  `default`; the select is now primed from the HTTP snapshot before the
+  WebSocket delta arrives.
+
+### Fixed (critical — from the 2026-09-25 sea trial)
+
+- **Tack in wind mode** (Rev309) — pressing VIRAR to a specific side now
+  reliably rotates the bow to that side, even when the "short arc" would
+  go the other way. Root cause: `planned = -refRad` in the countdown
+  path was ignoring the sign; now `_tackCountdownToExecuting` delegates
+  to `ap.tack.direction` + `ap.tack.state=begin` so pypilot honours the
+  band the sailor chose.
+- **Aproado without countdown** (Rev311) — pressing POR PROA / POR POPA
+  starts the maneuver on the same tap (previously 5 s delay). Sustain
+  3 s for the "achieved" latch avoids false positives on brief AWA
+  oscillations.
+- **Alarm silence during maneuvers** (Rev311 → Rev312 → Rev323) — the
+  `heading-deviation`, `cruise-drift` and `unable-to-steer` rules now
+  respect both pypilot's own `ap.tack.state != "none"` AND a visor-side
+  pseudo-mode flag posted to `POST /maneuver-state` when Aproado /
+  Empopado are running. Independent flag needed because pypilot does
+  not always update `ap.tack.state` when the sailor uses one of the
+  pseudo-modes.
+- **Heading-deviation false positives in wind mode** (Rev323) —
+  threshold raised to 35° and sustain to 30 s when the pilot mode is
+  `wind` / `true wind`. In waves and gusts the AWA target legitimately
+  oscillates ±20-30° while the AP is still correcting; the 20°/15 s
+  default of compass mode was disarming the alarm several times per
+  hour on Tunatunes.
+- **Tack countdown stability close-out** (Rev312) — if the tack overshoots
+  the plan but the boat is clearly settled (rate-of-turn < 3°/s for 2 s),
+  the overlay closes on its own instead of counting up to the 120 s
+  timeout.
+
+### Changed
+
+- **Alarms OFF by default** (Rev317) — a fresh install no longer arms
+  every rule; the sailor opts in via Setup → Alarms. Pre-Rev299 installs
+  keep legacy behaviour (undefined = all-on) so nothing changes silently
+  under an existing boat.
+- **Terminology cleanup** (Rev321) — all references to third-party
+  autopilot brands / dashboards in code, comments, docs, UI hints and
+  package metadata have been rewritten as neutral descriptions of the
+  mechanism ("downstream Signal K clients", "wind-response damping
+  bands", "classical heel-over-speed² formula"). No behavioural change.
+- **Tablet vertical crop hardening** (Rev314) — `100vh` → `100dvh` in
+  every fullscreen modal, `-webkit-overflow-scrolling: touch`, safe-area
+  padding. Fixes bottom-of-card clipping on Android tablets in portrait.
+
+### Removed
+
+- `docs/PROMPT_FOR_LLM_maneuver_catalog.md` — obsolete Rev209 audit
+  prompt, superseded by the current tack design.
+
 ## 2.9.0 — 2026-09-23 — Relicensed to AGPL-3.0-or-later
 
 ### License change (see NOTICE for details)

package/README.md

@@ -3,12 +3,12 @@
 **This plugin enhances and extends the magic of [pypilot](https://github.com/pypilot/pypilot)**,
 Sean D'Epagnier's open-source autopilot, with more functions, a modern
 touch-first user experience on tablets and phones, first-class
-**Signal K integration** so tools like [KIP](https://kip.signalk.org),
-WilhelmSK and freeboard can drive and monitor the autopilot out of the
-box, and a strong focus on **reliability, ease of use and ease of
-tuning**: the plugin itself watches how your autopilot is behaving and
-quietly suggests how to sharpen its settings, so you spend more time
-sailing and less time guessing which slider to move.
+**Signal K integration** so any downstream Signal K client can drive
+and monitor the autopilot out of the box, and a strong focus on
+**reliability, ease of use and ease of tuning**: the plugin itself
+watches how your autopilot is behaving and quietly suggests how to
+sharpen its settings, so you spend more time sailing and less time
+guessing which slider to move.
 
 Runs alongside [`pypilot-autopilot-provider`](https://www.npmjs.com/package/pypilot-autopilot-provider)
 by Panaaj — see [Working alongside pypilot-autopilot-provider](#working-alongside-pypilot-autopilot-provider).
@@ -78,8 +78,8 @@ by Panaaj — see [Working alongside pypilot-autopilot-provider](#working-alongs
 18. **Alarm engine — 9 rules** — heading deviation, cruise drift,
     unable-to-steer, servo overcurrent, servo temp, motor temp, high
     AP load, low voltage, sensor lost, pypilot disconnected — all
-    published as canonical `notifications.autopilot.*` for KIP /
-    WilhelmSK.
+    published as canonical `notifications.autopilot.*` for any
+    downstream Signal K client.
 19. **Head-to-wind pseudo-mode** — a "raise the sails" mode not
     present in pypilot, with countdown and bow / stern swing
     selection.
@@ -112,16 +112,16 @@ by Panaaj — see [Working alongside pypilot-autopilot-provider](#working-alongs
     stored as JSONL with tags (wind, sea state, propulsion, point of
     sail, crew), shareable for advice.
 28. **Full Signal K path catalog viewer** in the visor with
-    copy-to-clipboard for KIP.
+    copy-to-clipboard for downstream widgets.
 
 ### Signal K integration — 8 new added functions
 
 29. **~110 Signal K paths** under `steering.autopilot.pypilot.*`,
     opt-in per path so you never flood the bus.
-30. **Autopilot API v2 provider** (absorbable) — WilhelmSK,
-    freeboard and KIP talk to this plugin as the canonical
+30. **Autopilot API v2 provider** (absorbable) — any downstream
+    Signal K autopilot client talks to this plugin as the canonical
     autopilot.
-31. **KIP action paths** — Simple Switch for engage, nudge, tack,
+31. **Simple Switch action paths** — engage, nudge, tack,
     mode selector, profile selector.
 32. **9 momentary switches** — nudge ±10 / ±1, tack port / starboard
     / cancel — as KIP boolean paths.
@@ -152,8 +152,8 @@ history.
 2.0.0 is a **breaking release** addressing feedback from Sean D'Epagnier
 (pypilot author). Every pypilot key now maps 1:1 to
 `steering.autopilot.pypilot.<key>` verbatim - no more hand-picked renames
-or C -> K / deg -> rad conversions. If you have KIP widgets or WilhelmSK
-dashboards wired to 1.0.0 paths, see the full migration table in
+or C -> K / deg -> rad conversions. If you have Signal K dashboards
+wired to 1.0.0 paths, see the full migration table in
 [`CHANGELOG.md`](./CHANGELOG.md) - most notable examples:
 
 - `.servo.controllerTemperature` (K) -> `.servo.controller_temp` (C)
@@ -241,7 +241,7 @@ We build on top of the excellent
 [`pypilot-autopilot-provider`](https://www.npmjs.com/package/pypilot-autopilot-provider)
 by Panaaj — the plugin that gives Signal K the standard
 **Autopilot API v2** surface (`/signalk/v2/api/vessels/self/autopilots/*`) so
-WilhelmSK, freeboard and other clients can drive pypilot through the canonical
+any downstream Signal K autopilot client can drive pypilot through the canonical
 interface. Panaaj focuses tightly on that API and opens its own socket.io
 connection to `pypilot_web`.
 
@@ -260,7 +260,7 @@ register the same ID and behaviour is undefined). Valid setups:
 | Enabled | Off (default) | Both run happily side by side. Panaaj owns the AP v2 API; this plugin adds the extra paths + UI. **2 sockets** to `pypilot_web`. |
 | Disabled | **On** | Only this plugin. Same AP v2 API + all the extras. **1 socket**. Handy on Pi Zero W. |
 | Enabled | On | Both try to register the same AP ID — leave one off. |
-| Disabled | Off | WilhelmSK / freeboard / KIP won't see the AP. Only useful if you exclusively use this plugin's own webapp. |
+| Disabled | Off | No downstream Signal K client will see the AP. Only useful if you exclusively use this plugin's own webapp. |
 
 Absorb mode lives in **Setup → Autopilot Provider (one-socket mode)**.
 

package/dist/alarms.js

@@ -12,10 +12,10 @@
 //   - Rules never share state - a rule that says "true" this tick can
 //     later say "false" without any cleanup dance.
 //   - Every fire increments a per-rule counter used to add jitter to
-//     the emitted notification timestamp, so KIP/WilhelmSK never
-//     collapse two consecutive alerts into one.
+//     the emitted notification timestamp, so downstream SK clients
+//     never collapse two consecutive alerts into one.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AlarmEngine = exports.DEFAULT_RULES = exports.RULE_PYPILOT_DISC_SEC = exports.RULE_RUDDER_TRIM_RAD = exports.RULE_SERVO_TRIM_FRAC = exports.RULE_LOW_VOLTAGE_V = exports.RULE_SERVO_TEMP_C = exports.RULE_SERVO_OVERCURR_A = exports.RULE_UNABLE_DUTY_MIN = exports.RULE_UNABLE_ERR_RAD = exports.RULE_HEADING_ERR_RAD = exports.DEFAULT_MOTOR_TEMP_C = void 0;
+exports.AlarmEngine = exports.RULE_ATTITUDE_PITCH_DEG = exports.RULE_ATTITUDE_HEEL_DEG = exports.DEFAULT_RULES = exports.RULE_PYPILOT_DISC_SEC = exports.RULE_RUDDER_TRIM_RAD = exports.RULE_SERVO_TRIM_FRAC = exports.RULE_LOW_VOLTAGE_V = exports.RULE_SERVO_TEMP_C = exports.RULE_SERVO_OVERCURR_A = exports.RULE_UNABLE_DUTY_MIN = exports.RULE_UNABLE_ERR_RAD = exports.RULE_HEADING_ERR_RAD = exports.DEFAULT_MOTOR_TEMP_C = void 0;
 const SEV_TO_SK = {
     info: "nominal",
     warn: "warn",
@@ -53,13 +53,35 @@ exports.DEFAULT_RULES = [
         label: "Heading deviation",
         severity: "warn",
         defaultEnabled: true,
-        sustainSec: 15,
-        description: `RMS heading error exceeds ${(exports.RULE_HEADING_ERR_RAD * 180 / Math.PI) | 0}° with the AP engaged.`,
+        // Rev323 (Carlos, 2026-09-27): sustain subido de 15 s a 30 s. Con
+        // 15 s cualquier ola grande / racha corta metía la RMS 20 s por
+        // encima del umbral y disparaba la alarma; 30 s filtra el ruido
+        // legítimo de un mar entrecortado sin perder la señal de un AP
+        // realmente descolgado.
+        sustainSec: 30,
+        description: `RMS heading error exceeds ${(exports.RULE_HEADING_ERR_RAD * 180 / Math.PI) | 0}° (compass) / 35° (wind) with the AP engaged.`,
         evaluate: (c) => {
             if (!c.kpis || !c.sample || !c.sample.engaged)
                 return false;
+            // Rev311: durante una maniobra nativa del pypilot silenciamos.
+            if (c.maneuverInProgress)
+                return false;
+            // Rev323 (Carlos, 2026-09-27): pseudo-modo visor-side (Aproado /
+            // Empopado) también silencia — el visor está pilotando la
+            // maniobra por su cuenta y el "error" que reporta pypilot es
+            // el gap intencionado durante el swing.
+            if (c.maneuverPseudoActive)
+                return false;
+            // Rev323 mode-aware threshold. En wind / true-wind el heading
+            // command es un AWA/TWA target, que oscila naturalmente ±20-30°
+            // en olas y ráfagas mientras el AP sí está corrigiendo. Subir
+            // el umbral en esos modos elimina el disparo por doquier que
+            // Carlos reportó 2026-09-27.
+            const mode = (c.sample.mode || "").toLowerCase();
+            const isWind = mode.includes("wind");
+            const threshold = isWind ? (35 * Math.PI / 180) : exports.RULE_HEADING_ERR_RAD;
             const r = c.kpis.window1m.rmsErrorRad;
-            return typeof r === "number" && r > exports.RULE_HEADING_ERR_RAD;
+            return typeof r === "number" && r > threshold;
         },
         message: (c) => {
             const r = c.kpis?.window1m.rmsErrorRad ?? 0;
@@ -81,6 +103,10 @@ exports.DEFAULT_RULES = [
         evaluate: (c) => {
             if (!c.kpis || !c.sample || !c.sample.engaged)
                 return false;
+            if (c.maneuverInProgress)
+                return false; // Rev311: silencio en maniobra
+            if (c.maneuverPseudoActive)
+                return false; // Rev323: idem pseudo-modo
             const mean = c.kpis.window1m.meanErrorRad;
             return typeof mean === "number" && Math.abs(mean) > (5 * Math.PI / 180);
         },
@@ -100,6 +126,10 @@ exports.DEFAULT_RULES = [
         evaluate: (c) => {
             if (!c.kpis || !c.sample || !c.sample.engaged)
                 return false;
+            if (c.maneuverInProgress)
+                return false; // Rev311: silencio en maniobra
+            if (c.maneuverPseudoActive)
+                return false; // Rev323: idem pseudo-modo
             const r = c.kpis.window1m.rmsErrorRad;
             const d = c.kpis.window1m.servoDutyPct;
             return typeof r === "number" && r > exports.RULE_UNABLE_ERR_RAD
@@ -213,9 +243,10 @@ exports.DEFAULT_RULES = [
     {
         // Rev156 (Carlos): ServoHealth already grades the drive as
         // learning/good/elevated/high on the deviation ratio (recent avg
-        // vs learned baseline). Surface "high" as a notification so KIP /
-        // WilhelmSK show the same red banner the visor card does. Only
-        // fires once the baseline is actually learned (deviation != null).
+        // vs learned baseline). Surface "high" as a notification so
+        // downstream SK clients show the same red banner the visor card
+        // does. Only fires once the baseline is actually learned
+        // (deviation != null).
         id: "servo-load-high",
         label: "Autopilot load high",
         severity: "warn",
@@ -318,7 +349,55 @@ exports.DEFAULT_RULES = [
             return `Pypilot desconectado desde hace ${tail}`;
         },
     },
+    // Rev299 (I1): attitude safety envelope. These rules watch what the
+    // sailor cares about — is the boat pinned on its side, is the bow
+    // buried — not just what the servo is doing. Both are opt-in
+    // (defaultEnabled=false) because a heavy-weather passage will trip
+    // them and we do not want a fresh install screaming across a
+    // deliberate rail-in-the-water broach. Thresholds live in
+    // AlarmThresholds so the sailor can tune per-boat.
+    {
+        id: "attitude-heel-extreme",
+        label: "Escora extrema",
+        severity: "warn",
+        defaultEnabled: false,
+        sustainSec: 5,
+        description: "Heel angle sostenido por encima del umbral configurado (por defecto 45°). Sirve como envoltura de seguridad: no reemplaza el criterio del navegante ni desengancha el piloto.",
+        evaluate: (c) => {
+            if (!c.sample || typeof c.sample.heel !== "number")
+                return false;
+            const thrDeg = c.thresholds?.attitudeHeelDeg ?? exports.RULE_ATTITUDE_HEEL_DEG;
+            return Math.abs(c.sample.heel) * 180 / Math.PI > thrDeg;
+        },
+        message: (c) => {
+            const heelDeg = Math.abs((c.sample?.heel ?? 0) * 180 / Math.PI);
+            const thrDeg = c.thresholds?.attitudeHeelDeg ?? exports.RULE_ATTITUDE_HEEL_DEG;
+            return `Escora ${heelDeg.toFixed(0)}° (umbral ${thrDeg}°)`;
+        },
+    },
+    {
+        id: "attitude-pitch-extreme",
+        label: "Cabeceo extremo",
+        severity: "warn",
+        defaultEnabled: false,
+        sustainSec: 3,
+        description: "Pitch (cabeceo) sostenido por encima del umbral configurado. Suele indicar embarque de proa o clavado en ola.",
+        evaluate: (c) => {
+            if (!c.sample || typeof c.sample.pitch !== "number")
+                return false;
+            const thrDeg = c.thresholds?.attitudePitchDeg ?? exports.RULE_ATTITUDE_PITCH_DEG;
+            return Math.abs(c.sample.pitch) * 180 / Math.PI > thrDeg;
+        },
+        message: (c) => {
+            const pitchDeg = Math.abs((c.sample?.pitch ?? 0) * 180 / Math.PI);
+            const thrDeg = c.thresholds?.attitudePitchDeg ?? exports.RULE_ATTITUDE_PITCH_DEG;
+            return `Cabeceo ${pitchDeg.toFixed(0)}° (umbral ${thrDeg}°)`;
+        },
+    },
 ];
+// Rev299 (I1): defaults for the attitude envelope.
+exports.RULE_ATTITUDE_HEEL_DEG = 45;
+exports.RULE_ATTITUDE_PITCH_DEG = 25;
 class AlarmEngine {
     constructor(rules = exports.DEFAULT_RULES, opts = {}) {
         this.rules = new Map();
@@ -394,6 +473,20 @@ class AlarmEngine {
         }
         return changed;
     }
+    /** Rev342 (Carlos, 2026-09-28): override the severity of one rule
+     *  at runtime. The RuleDef default is preserved so subsequent boots
+     *  without an override recover the shipped severity. Returns true
+     *  on success, false if the rule id or severity is unknown. */
+    setRuleSeverity(ruleId, severity) {
+        const rule = this.rules.get(ruleId);
+        const s = this.state.get(ruleId);
+        if (!rule || !s)
+            return false;
+        if (severity !== "info" && severity !== "warn" && severity !== "alarm")
+            return false;
+        s.severity = severity;
+        return true;
+    }
     /** Rev292: change the sustain window of one rule at runtime, e.g.
      *  when the sailor updates alarmPypilotDiscSec in /supervisor/config.
      *  Returns true on success, false if the rule id is unknown. Values
@@ -491,7 +584,16 @@ class AlarmEngine {
             out.push({
                 id,
                 label: rule.label,
-                severity: rule.severity,
+                // Rev375 (Carlos, 2026-09-30): was `rule.severity` (default),
+                // which made the frontend severity dropdown revert to default
+                // on every _alFetch poll. `s.severity` reflects setRuleSeverity
+                // overrides applied at boot from props.alarmSeverityOverrides
+                // and by runtime POSTs to /alarms/severity/:id.
+                severity: s.severity,
+                // Rev376 (Carlos, 2026-09-30): expose the shipped default so
+                // the frontend dropdown can mark it (★) — sailor asked to see
+                // which option is "the default" before changing it.
+                defaultSeverity: rule.severity,
                 enabled: s.enabled,
                 description: rule.description,
                 sustainSec: rule.sustainSec,

package/dist/autopilot-provider.js

@@ -101,6 +101,7 @@ class AutopilotProvider {
         if (opts?.allowDodge)
             this.allowDodge = true;
         this.onDataChanged = opts?.onDataChanged;
+        this.onStageEvent = opts?.onStageEvent;
     }
     notifyChanged(fields) {
         try {
@@ -108,10 +109,23 @@ class AutopilotProvider {
         }
         catch { /* silent */ }
     }
-    // Called from PypilotClient 'value' event. Returns true if apData changed
-    // and an autopilotUpdate should be pushed.
+    // Called from PypilotClient 'value' event. Returns the field that
+    // changed (so the caller can push a field-scoped delta and avoid
+    // dragging siblings with stale values), or null if nothing changed.
+    //
+    // Rev352 (Carlos, 2026-09-30, trace analysis): previously returned
+    // boolean and the caller line 729 defaulted to fields="all" — that
+    // emitted state+engaged+target+mode+availableActions with whatever
+    // apProvider.data held at that instant. When pypilot took seconds
+    // to echo an engage (external tack from mando/nativo), any other
+    // pypilot value arriving in the meantime triggered fields="all"
+    // publishes with the stale engaged=false. The next echo produced
+    // fields="all" with engaged=true, but subscription manager's
+    // minPeriod:500 collapsed the pair and the visor saw only false.
+    // Field-scoping the push kills the collision at source.
     receiveValue(name, value) {
         let changed = false;
+        let changedField = null;
         switch (name) {
             case "ap.heading_command":
                 if (typeof value === "number") {
@@ -132,30 +146,105 @@ class AutopilotProvider {
                             // Real echo landed - clear pending, keep our value (may be
                             // slightly more precise than the echo). No change signal
                             // needed since data.target already equals the pending value.
+                            this.onStageEvent?.("provider", {
+                                path: "ap.heading_command",
+                                decision: "echo_dropped_match",
+                                reason: "diff_within_tol",
+                                rawValue: value,
+                                normalizedValue: rad,
+                                pendingValue: this.pendingTarget.value,
+                                diffRad: diff,
+                            });
                             this.pendingTarget = null;
+                            break;
+                        }
+                        // Rev350 (Carlos, 2026-09-29, cross-check LLM audit): diff
+                        // GRANDE dentro de la ventana pending. Antes: descartábamos
+                        // el valor y no limpiábamos pending → si pypilot no volvía
+                        // a publicar tras el drop, data.target quedaba rancio hasta
+                        // que expiraba pending Y pypilot re-emitía. Confirmado por
+                        // GPT-Codex: "la ventana dura 2.5 s pero el valor descartado
+                        // puede perderse indefinidamente". Ver memoria
+                        // [[backend-echo-cancel-drops-external-override]].
+                        //
+                        // Ahora: interpretamos diff > TOL como OVERRIDE EXTERNO
+                        // genuino (mando físico / UI nativo cambió target mientras
+                        // nuestra escritura estaba pendiente). Aplicamos el valor,
+                        // liberamos el gate, notificamos cambio. El caso Rev68
+                        // original (echo con mismo valor) sigue funcionando: cae en
+                        // la rama `<= TOL` y limpia pending sin cambiar target.
+                        const pendingSnap = this.pendingTarget.value;
+                        this.pendingTarget = null;
+                        this.onStageEvent?.("provider", {
+                            path: "ap.heading_command",
+                            decision: "external_override_applied",
+                            reason: "diff_over_tol_in_pending_window",
+                            rawValue: value,
+                            normalizedValue: rad,
+                            pendingValue: pendingSnap,
+                            diffRad: diff,
+                        });
+                        if (rad !== this.data.target) {
+                            this.data.target = rad;
+                            changed = true;
+                            changedField = "target";
                         }
-                        // Whether match or stale, do not overwrite data.target inside
-                        // the pending window.
                         break;
                     }
-                    if (rad !== this.data.target) {
-                        this.data.target = rad;
-                        changed = true;
+                    {
+                        const prev = this.data.target;
+                        if (rad !== prev) {
+                            this.data.target = rad;
+                            changed = true;
+                            changedField = "target";
+                        }
+                        this.onStageEvent?.("provider", {
+                            path: "ap.heading_command",
+                            decision: changed ? "accepted_change" : "accepted_noop",
+                            reason: "no_pending_window",
+                            rawValue: value,
+                            normalizedValue: rad,
+                            prevValue: prev,
+                        });
                     }
                 }
                 else if (value === false && this.data.target !== null) {
+                    const prev = this.data.target;
                     this.data.target = null;
                     this.pendingTarget = null;
                     changed = true;
+                    changedField = "target";
+                    this.onStageEvent?.("provider", {
+                        path: "ap.heading_command",
+                        decision: "accepted_change",
+                        reason: "value_false_cleared_target",
+                        rawValue: value,
+                        prevValue: prev,
+                    });
                 }
                 break;
             case "ap.mode":
-                if (typeof value === "string" && value !== this.data.mode) {
-                    this.data.mode = value;
-                    if (this.data.options.modes.length === 0) {
-                        this.data.options.modes.push(value);
+                if (typeof value === "string") {
+                    const prev = this.data.mode;
+                    if (value !== prev) {
+                        this.data.mode = value;
+                        if (this.data.options.modes.length === 0) {
+                            this.data.options.modes.push(value);
+                        }
+                        changed = true;
+                        // Rev352: mode change also affects recomputeActions (some
+                        // actions like courseCurrentPoint gate on mode). Push "all"
+                        // so state+engaged+target+mode+availableActions stay in
+                        // sync. This IS a genuine multi-field change, not a
+                        // spurious drag.
+                        changedField = "all";
                     }
-                    changed = true;
+                    this.onStageEvent?.("provider", {
+                        path: "ap.mode",
+                        decision: changed ? "accepted_change" : "accepted_noop",
+                        rawValue: value,
+                        prevValue: prev,
+                    });
                 }
                 break;
             case "ap.modes":
@@ -171,6 +260,7 @@ class AutopilotProvider {
                     // stayed unavailable until the next engage/disengage.
                     this.recomputeActions();
                     changed = true;
+                    changedField = "all";
                 }
                 break;
             case "ap.enabled": {
@@ -185,23 +275,51 @@ class AutopilotProvider {
                 // engage-disengage-engage. Ignore echoes that don't match the
                 // pending intent while the pending window is open.
                 if (this.pendingEngaged && Date.now() < this.pendingEngaged.until) {
-                    if (eng === this.pendingEngaged.value) {
+                    const pendVal = this.pendingEngaged.value;
+                    if (eng === pendVal) {
                         this.pendingEngaged = null;
+                        this.onStageEvent?.("provider", {
+                            path: "ap.enabled",
+                            decision: "echo_dropped_match",
+                            rawValue: value,
+                            normalizedValue: eng,
+                            pendingValue: pendVal,
+                        });
+                    }
+                    else {
+                        this.onStageEvent?.("provider", {
+                            path: "ap.enabled",
+                            decision: "echo_dropped_stale",
+                            rawValue: value,
+                            normalizedValue: eng,
+                            pendingValue: pendVal,
+                        });
                     }
                     break;
                 }
                 const st = eng ? "enabled" : "disabled";
+                const prevState = this.data.state;
+                const prevEngaged = this.data.engaged;
                 if (this.data.state !== st || this.data.engaged !== eng) {
                     this.data.state = st;
                     this.data.engaged = eng;
                     changed = true;
+                    changedField = "engaged";
                 }
+                this.onStageEvent?.("provider", {
+                    path: "ap.enabled",
+                    decision: changed ? "accepted_change" : "accepted_noop",
+                    rawValue: value,
+                    normalizedValue: eng,
+                    prevValue: prevEngaged,
+                    prevState,
+                });
                 break;
             }
         }
         if (changed)
             this.recomputeActions();
-        return changed;
+        return changedField;
     }
     markOffline() {
         if (this.data.state !== "off-line" || this.data.engaged) {
@@ -266,33 +384,58 @@ class AutopilotProvider {
         // the retry backoff, the stale isStale() check aborts the retry
         // and we throw without mutating optimistic state.
         const gen = this._bumpEngageGen();
-        // Rev254 (Carlos audit): reject the write BEFORE mutating optimistic
-        // state if the pypilot socket is offline. Previously the visor was
-        // told the order succeeded even though nothing left the plugin.
+        // Rev351 (Carlos, 2026-09-29, sea-trial QA Rev350): optimist STATE
+        // + pending window BEFORE the await. Antes: pendingEngaged sólo se
+        // seteaba tras el ACK de pypilot. Durante ese await (~10 s en engage
+        // observados por Carlos en localhost), el watch 2 Hz de pypilot
+        // seguía emitiendo `ap.enabled=false` (stale) y el receiveValue lo
+        // aplicaba como estado real → push SK engaged=false → visor
+        // revertía la UI optimista. Disengage no lo sufría porque pypilot
+        // aplica disable en < 500 ms y el echo real llegaba inmediato.
+        //
+        // Fix: setear pendingEngaged + data.state/engaged + notifyChanged
+        // ANTES del _setWithRetry, con ventana extendida a 15 s para cubrir
+        // el peor caso de latencia pypilot. Si el set falla, revertimos.
+        const prevState = this.data.state;
+        const prevEngaged = this.data.engaged;
+        this.pendingEngaged = { value: eng, until: Date.now() + 15000 };
+        this.data.state = apSt;
+        this.data.engaged = eng;
+        this.recomputeActions();
+        // Rev84: publish ONLY the engaged/state/actions delta - do NOT
+        // include target. If setTarget was called in parallel, its own
+        // notifyChanged("target") will publish the new target value
+        // independently. Publishing target here would carry the STALE
+        // apProvider.data.target and clobber JS state.target if this
+        // delta happens to land second.
+        this.notifyChanged("engaged");
+        // Rev254 (Carlos audit): reject the write on offline socket.
         // Rev255: retry with backoff to tolerate socket.io reconnects.
+        // Rev351: on failure, revert the optimist so the UI reflects
+        // reality (unless a newer bump has already overwritten us).
         if (!(await this._setWithRetry("ap.enabled", eng, () => this.engageGen !== gen))) {
+            if (this.engageGen === gen) {
+                this.pendingEngaged = null;
+                this.data.state = prevState;
+                this.data.engaged = prevEngaged;
+                this.recomputeActions();
+                this.notifyChanged("engaged");
+            }
             if (this.engageGen !== gen) {
                 throw new Error("engage/disengage superseded by newer order");
             }
             throw new Error("pypilot offline: engage/disengage not delivered");
         }
         // Rev271: last-check after the successful set - a newer bump could
-        // have won the race between the emit and this line. Do not mutate
-        // optimistic state in that case; the winner's own setState will.
+        // have won the race between the emit and this line. If superseded,
+        // the winning order has already published its own optimist; leave
+        // state alone and let the winner's echo reconcile.
         if (this.engageGen !== gen) {
             throw new Error("engage/disengage superseded after write");
         }
-        this.data.state = apSt;
-        this.data.engaged = eng;
+        // Rev351: pypilot ACK-eó el set. Reduce la ventana pending al
+        // valor normal (2.5 s) porque el eco real llegará en < 1 s típico.
         this.pendingEngaged = { value: eng, until: Date.now() + TARGET_PENDING_MS };
-        this.recomputeActions();
-        // Rev84: publish ONLY the engaged/state/actions delta - do NOT
-        // include target. If setTarget was called in parallel, its own
-        // notifyChanged("target") will publish the new target value
-        // independently. Publishing target here would carry the STALE
-        // apProvider.data.target and clobber JS state.target if this
-        // delta happens to land second.
-        this.notifyChanged("engaged");
         return eng;
     }
     async setMode(mode) {