signalk-pypilot-newui 2.7.4 → 2.8.0

package/CHANGELOG.md

@@ -1,5 +1,160 @@
 # Changelog
 
+## 2.8.0 — 2026-09-23 — Sea-trial critical fixes + intelligence layer
+
+### Fixed (critical, from real sea trial)
+
+- **pypilot-disconnected alarm no longer panics on a 1 s hiccup.**
+  The banner used to fire after just 1 second of socket silence at
+  "alarm" severity (audio channel forced). In a marine environment
+  where a 4G router routinely blips for a few seconds on the SIM,
+  this generated constant false positives with unavoidable sound.
+  New default: **15 s sustain, "warn" severity** (silent banner). The
+  window is now runtime-configurable via
+  `POST /supervisor/config` field `alarmPypilotDiscSec` (range
+  3..300 s). Applies to `notifications.autopilot.pypilot-disconnected`.
+
+- **Wind-mode nudge buttons now steer the bow to the labelled side,
+  independent of AWA sign.** Before, `modeSign = -Math.sign(AWA)`
+  meant a `+10` on port-side ceñida (AWA=-45°) inverted the sign and
+  moved the target the wrong way, so the bow swung to the opposite
+  side of the button label. Fixed to `modeSign = -1` always in wind
+  mode; the four cases (AWA±45 × button±10) now all match the
+  physical expectation of "swing the bow to the labelled side".
+
+- **Mode change compass↔wind no longer strands `heading_command` in
+  the previous space.** pypilot's `ap.heading_command` lives in
+  different value spaces per mode (compass=heading, wind=AWA,
+  true wind=TWA). Before, changing modes left the target number
+  unchanged, so a `heading_command=90°` in compass became a 90° AWA
+  target in wind mode and the pilot swung hard to reach it. The
+  provider now **re-anchors** `heading_command` to the current
+  measurement in the destination space (`wind.direction` /
+  `wind.true_direction` / `ap.heading`) right after the mode delta
+  is confirmed. Same-space transitions (compass↔gps↔nav,
+  wind↔true wind) skip the re-anchor. Decision extracted to
+  `src/mode-reanchor.ts` with 24 unit tests.
+
+- **Profile selection cannot be overwritten to "default" when opening
+  the visor on a fresh device.** The `<select id="profile-select">`
+  starts with the DOM-default first option ("default") until the
+  authoritative delta lands. A stray change event fired during that
+  gap could write "default" to pypilot, overriding the sailor's
+  active profile. The visor now refuses to send profile changes
+  until it has received at least one authoritative `profile` delta
+  from the backend, and skips identity writes.
+
+- **Gust temp-heavy strategy respects manual profile changes.** If
+  the sailor picks a different profile during the 30 s temp-heavy
+  window, the automatic restore no longer overwrites that choice.
+  It fires an advisory notification instead.
+
+- **Runaway pilot defence.** `adjustTarget` clamp tightened from
+  573° to 90°. A single adjustTarget above 90° is either a caller
+  bug or a corrupt payload; refused at the boundary before it
+  becomes an untraceable pypilot sweep. Nudges (max 100° per press)
+  and tacks (go through `setTarget` absolute) are unaffected.
+
+### New — Doctor rule set
+
+- **Rule 5: step-response episode analysis.** When ≥3 correction
+  episodes closed during the Doctor session's window, high average
+  overshoot suggests raising D (+15% or +25% if overshoot > 35%),
+  and repeated timeouts flag "AP cannot reach the target — hardware
+  authority".
+- **Rule 6: downwind roll advisory.** With Roll FF disabled and a
+  heel RMS > 5° on downwind engaged samples, Doctor suggests
+  activating the Roll feed-forward slider.
+
+### New — Tuning & profiles
+
+- **Three-slider tuning panel (backend).** New endpoints
+  `GET/POST /tuning/knobs` map Aggressivity + Understeer/Oversteer +
+  Balance-Heading/Rate onto raw P/I/D/DD via `src/tuning-knobs.ts`.
+  Identity at (50, 0, 0); all factors clamped to [0.3×, 3.0×]
+  baseline. 26 unit tests.
+- **Profile metadata.** `GET /profiles/metadata` + `PUT/DELETE
+  /profiles/metadata/:name` for tagging each pypilot profile with a
+  condition (light/medium/heavy/motor/custom) and free-text notes.
+  Persisted via `savePluginOptions`.
+- **Profile advisor.** Watches the 1 min KPI window and notifies
+  when the boat has been tracking sustainedly badly ("consider a
+  more aggressive profile") or over-tightly with high servo duty
+  ("consider a less aggressive profile"). Never applies anything;
+  emits a `notifications.autopilot.pypilot.profileAdvisor` visual
+  banner with 5 min cooldown.
+- **Profile change audit log.** New endpoint
+  `GET /profile-change-log` shows the last 50 profile transitions
+  with attributed source (user / auto-profile / gust-heavy /
+  gust-heavy-restore / doctor / external). Answers "who changed my
+  profile?" for surprise switches.
+
+### New — Correction episodes + config backup
+
+- **Correction episode metrics.** `src/episodes.ts` detects each
+  target-step correction and records step-response metrics
+  (rise time, overshoot %, settling time, steady-state error).
+  Exposed at `GET /episodes` with a good/acceptable/poor quality
+  band. Feeds Rule 5 of the Doctor.
+- **Config backup / restore.** `GET /config/export` downloads a
+  JSON bundle of plugin options + persistent pypilot settings
+  (P/I/D/DD, tack params, servo max_current, etc.). `POST
+  /config/import` accepts a bundle and applies it, filtering runtime
+  telemetry keys defensively.
+
+### New — Physical control terms
+
+- **Roll feed-forward (off by default).** `src/roll-ff.ts` filters
+  the dynamic component of `navigation.attitude.roll` and computes a
+  small pre-emptive shift of the commanded heading, gated to
+  |TWA|>90°. Currently PUBLISHED at
+  `steering.autopilot.pypilot.tuning.rollFf.*` for observation; not
+  applied to the pilot yet — a later Rev flips that switch after sea
+  trial validates the term. Slider lives at `POST
+  /supervisor/config` field `rollFfGain` (0..2).
+- **Gust heel-confirmation gate.** The Rev167 gust supervisor now
+  cross-checks the AWS jump against a >2° heel change during the
+  same 5 s window. A sensor spike that did not physically load the
+  boat is suppressed. Falls open when heel data is absent.
+
+### New — Alarms & telemetry
+
+- **Persistent servo error log.** JSONL under the plugin dataDir
+  records every servo-* alarm transition with a 30 s peak summary
+  of pre-fault telemetry (max A, max °C, min V, max heading error).
+  Exposed at `GET /servo-error-log`.
+- **Pre-fault trim warnings.** New "info"-severity rules
+  `servo-current-trim` (>75% of overcurrent limit) and
+  `rudder-range-trim` (>40° absolute) fire *before* the fault-severity
+  rules to give the sailor time to trim.
+- **Configurable alarm thresholds.** `alarmLowVoltageV` (8..14 V),
+  `alarmServoTempC` (40..85 °C), `alarmServoMotorTempC` (40..90 °C)
+  now exposed via `/supervisor/config` and threaded through the
+  alarm rules per install.
+
+### New — NAV mode observability
+
+- **APB source preview.** `GET /nav/apb-preview` shows the current
+  active-waypoint bearing computed both ways — direct `bearingTrue`
+  and plotter-provided `steerTo` — plus their divergence. Read-only
+  for now; a later Rev may switch to plugin-side NAV mode after sea
+  trial validates the preference.
+
+### Under the hood
+
+- 8 new source modules with 177 unit tests (up from 5). All
+  additive — no existing endpoint or SK path changed contract.
+- Rev sequence 281..297 on branch `feat/blind-batch-sep16`.
+
+## 2.7.5 — 2026-09-15 — Hotfix on 2.7.4 (visor did not load)
+
+**Deprecates 2.7.4.** The restore verdict fix that landed in 2.7.4
+declared `const wantMode` twice in the same block scope
+(`SyntaxError: redeclaration of const wantMode`) which prevented
+`app.js` from loading. This release removes the duplicate and keeps
+everything else in 2.7.4 unchanged. If you installed 2.7.4, please
+update to 2.7.5.
+
 ## 2.7.4 — 2026-09-15 — Async control tightening + uppercase accents
 
 Closes three findings from the external Rev277 review and finishes

package/dist/alarms.js

@@ -15,12 +15,15 @@
 //     the emitted notification timestamp, so KIP/WilhelmSK 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_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 = void 0;
+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;
 const SEV_TO_SK = {
     info: "nominal",
     warn: "warn",
     alarm: "alarm",
 };
+/** Canonical defaults, exposed for the /alarms/thresholds GET and for
+ *  the visor to know the safe range. */
+exports.DEFAULT_MOTOR_TEMP_C = 70;
 // -------- Built-in rules --------
 // Thresholds picked to be sensible defaults for a cruising sailboat.
 // A future Rev exposes them via plugin schema.
@@ -30,12 +33,20 @@ exports.RULE_UNABLE_DUTY_MIN = 0.7; // 70% duty
 exports.RULE_SERVO_OVERCURR_A = 5.0;
 exports.RULE_SERVO_TEMP_C = 60;
 exports.RULE_LOW_VOLTAGE_V = 11.0;
-// Rev256 lowered this from 10 s to 3 s. Rev258 (Carlos): with the new
-// pong-aware `healthy` check the socket is flagged offline after ~8 s
-// of missed pings (much earlier than TCP heartbeat would), so we can
-// afford a very short sustain here. Total from real pypilot power-off
-// to alarm firing: ~8 s + 1 s = 9 s.
-exports.RULE_PYPILOT_DISC_SEC = 1;
+// Rev287 (E1): trim warnings fire BEFORE the corresponding fault
+// so the sailor sees the drift toward the limit and can trim sails
+// or ease pressure before the fault-severity rule kicks in.
+exports.RULE_SERVO_TRIM_FRAC = 0.75; // 75% of overcurrent
+exports.RULE_RUDDER_TRIM_RAD = 40 * Math.PI / 180; // 40 deg absolute
+// Rev292 (Carlos, navigating): the previous 1 s default was too eager
+// in a marine environment where a 4G router routinely blips for a few
+// seconds on the SIM. The severity was also cranked to "alarm" which
+// forced the audio channel and made the pop-up unavoidable. New
+// default: 15 s sustain (comfortable with the 8 s pong-aware healthy
+// check → total ~23 s to fire) and "warn" severity so the visor banner
+// shows but does not force sound. Sailors who want stricter behaviour
+// can drop sustainSec via /supervisor/config.
+exports.RULE_PYPILOT_DISC_SEC = 15;
 exports.DEFAULT_RULES = [
     {
         id: "heading-deviation",
@@ -114,19 +125,68 @@ exports.DEFAULT_RULES = [
         },
         message: (c) => `Servo overcurrent ${(c.sample?.servoCurrent ?? 0).toFixed(1)} A`,
     },
+    {
+        // Rev287 (E1): pre-fault trim warning. Fires when the servo has
+        // been drawing >75% of the overcurrent limit sustained a few
+        // seconds. Info severity - it precedes the fault-severity rule
+        // above by design so the sailor has time to react.
+        id: "servo-current-trim",
+        label: "Servo current approaching limit",
+        severity: "info",
+        defaultEnabled: true,
+        sustainSec: 5,
+        description: `Servo drawing over ${(exports.RULE_SERVO_TRIM_FRAC * 100).toFixed(0)}% of the overcurrent limit — ease pressure or trim sails.`,
+        evaluate: (c) => {
+            if (!c.sample || typeof c.sample.servoCurrent !== "number")
+                return false;
+            const thr = exports.RULE_SERVO_OVERCURR_A * exports.RULE_SERVO_TRIM_FRAC;
+            const a = c.sample.servoCurrent;
+            // Don't double-fire with the fault-severity rule; back off when
+            // already in the overcurrent band.
+            if (a > exports.RULE_SERVO_OVERCURR_A)
+                return false;
+            return a > thr;
+        },
+        message: (c) => `Servo current ${(c.sample?.servoCurrent ?? 0).toFixed(1)} A (limit ${exports.RULE_SERVO_OVERCURR_A.toFixed(1)} A)`,
+    },
+    {
+        // Rev287 (E1): rudder pre-fault trim warning. Fires when the rudder
+        // has been sustainedly close to its stop, which usually precedes a
+        // servo out-of-range fault. Info severity.
+        id: "rudder-range-trim",
+        label: "Rudder near limit",
+        severity: "info",
+        defaultEnabled: true,
+        sustainSec: 3,
+        description: `Rudder deflection above ${(exports.RULE_RUDDER_TRIM_RAD * 180 / Math.PI).toFixed(0)}° — servo is near its end of travel.`,
+        evaluate: (c) => {
+            if (!c.sample || typeof c.sample.rudder !== "number")
+                return false;
+            return Math.abs(c.sample.rudder) > exports.RULE_RUDDER_TRIM_RAD;
+        },
+        message: (c) => {
+            const r = (c.sample?.rudder ?? 0) * 180 / Math.PI;
+            const side = r >= 0 ? "stbd" : "port";
+            return `Rudder ${Math.abs(r).toFixed(0)}° ${side} (limit ${(exports.RULE_RUDDER_TRIM_RAD * 180 / Math.PI).toFixed(0)}°)`;
+        },
+    },
     {
         id: "servo-temp-high",
         label: "Servo temperature high",
         severity: "warn",
         defaultEnabled: true,
         sustainSec: 10,
-        description: `Servo controller temperature above ${exports.RULE_SERVO_TEMP_C} °C.`,
+        description: `Servo controller temperature above the configured threshold (default ${exports.RULE_SERVO_TEMP_C} °C).`,
         evaluate: (c) => {
             if (!c.sample || typeof c.sample.servoTemp !== "number")
                 return false;
-            return c.sample.servoTemp > exports.RULE_SERVO_TEMP_C;
+            const thr = c.thresholds?.servoTempC ?? exports.RULE_SERVO_TEMP_C;
+            return c.sample.servoTemp > thr;
+        },
+        message: (c) => {
+            const thr = c.thresholds?.servoTempC ?? exports.RULE_SERVO_TEMP_C;
+            return `Servo temp ${(c.sample?.servoTemp ?? 0).toFixed(0)} °C (limit ${thr} °C)`;
         },
-        message: (c) => `Servo temp ${(c.sample?.servoTemp ?? 0).toFixed(0)} °C`,
     },
     {
         // Rev156 (Carlos): coil temperature complements servo-temp-high,
@@ -138,13 +198,17 @@ exports.DEFAULT_RULES = [
         severity: "warn",
         defaultEnabled: true,
         sustainSec: 15,
-        description: "Motor coil temperature above 70 C.",
+        description: `Motor coil temperature above the configured threshold (default ${exports.DEFAULT_MOTOR_TEMP_C} °C).`,
         evaluate: (c) => {
             if (!c.sample || typeof c.sample.servoMotorTemp !== "number")
                 return false;
-            return c.sample.servoMotorTemp > 70;
+            const thr = c.thresholds?.servoMotorTempC ?? exports.DEFAULT_MOTOR_TEMP_C;
+            return c.sample.servoMotorTemp > thr;
+        },
+        message: (c) => {
+            const thr = c.thresholds?.servoMotorTempC ?? exports.DEFAULT_MOTOR_TEMP_C;
+            return `Servo motor temp ${(c.sample?.servoMotorTemp ?? 0).toFixed(0)} °C (limit ${thr} °C)`;
         },
-        message: (c) => `Servo motor temp ${(c.sample?.servoMotorTemp ?? 0).toFixed(0)} °C`,
     },
     {
         // Rev156 (Carlos): ServoHealth already grades the drive as
@@ -175,13 +239,17 @@ exports.DEFAULT_RULES = [
         severity: "warn",
         defaultEnabled: true,
         sustainSec: 10,
-        description: `Servo battery voltage below ${exports.RULE_LOW_VOLTAGE_V} V.`,
+        description: `Servo battery voltage below the configured threshold (default ${exports.RULE_LOW_VOLTAGE_V} V).`,
         evaluate: (c) => {
             if (!c.sample || typeof c.sample.servoVoltage !== "number")
                 return false;
-            return c.sample.servoVoltage < exports.RULE_LOW_VOLTAGE_V;
+            const thr = c.thresholds?.lowVoltageV ?? exports.RULE_LOW_VOLTAGE_V;
+            return c.sample.servoVoltage < thr;
+        },
+        message: (c) => {
+            const thr = c.thresholds?.lowVoltageV ?? exports.RULE_LOW_VOLTAGE_V;
+            return `Low voltage ${(c.sample?.servoVoltage ?? 0).toFixed(1)} V (limit ${thr} V)`;
         },
-        message: (c) => `Low voltage ${(c.sample?.servoVoltage ?? 0).toFixed(1)} V`,
     },
     {
         id: "sensor-lost",
@@ -210,10 +278,21 @@ exports.DEFAULT_RULES = [
     {
         id: "pypilot-disconnected",
         label: "Pypilot desconectado",
-        severity: "alarm",
+        // Rev292 (Carlos, navigating): dropped from "alarm" to "warn". A
+        // pypilot socket that stops sending pings does NOT put the boat in
+        // immediate danger — the sailor can still steer manually while the
+        // sailors's phone / router / SIM recovers. Reserve "alarm" (audio
+        // channel) for rules that actually mean "act now" (unable-to-steer,
+        // servo-overcurrent).
+        severity: "warn",
         defaultEnabled: true,
+        // sustainSec is now dynamic: threshold override wins; falls back
+        // to the module default (15 s in Rev292+). We keep the field here
+        // for the description; the actual sustain used is stateful because
+        // AlarmEngine reads it once at register time — see the sustain
+        // override handled by evalWithSustainOverride below.
         sustainSec: exports.RULE_PYPILOT_DISC_SEC,
-        description: `pypilot_web socket has been down for ${exports.RULE_PYPILOT_DISC_SEC} seconds.`,
+        description: `pypilot_web socket has been down for the configured window (default ${exports.RULE_PYPILOT_DISC_SEC} s).`,
         evaluate: (c) => !c.connected,
         message: (c) => {
             if (c.disconnectedSinceMs == null)
@@ -315,6 +394,21 @@ class AlarmEngine {
         }
         return changed;
     }
+    /** 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
+     *  outside a sane band are clamped, never rejected. */
+    setRuleSustain(ruleId, sec) {
+        const rule = this.rules.get(ruleId);
+        if (!rule)
+            return false;
+        const clamped = Math.max(1, Math.min(600, Math.floor(sec)));
+        // Mutate the RuleDef in place. The RuleDef object was captured by
+        // reference in this.rules.set(), so subsequent ticks pick up the
+        // new value on their next evaluate.
+        rule.sustainSec = clamped;
+        return true;
+    }
     fire(s, rule, ctx) {
         s.active = true;
         s.activeSinceMs = ctx.nowMs;

package/dist/autopilot-provider.js

@@ -11,17 +11,20 @@
 // single socket to pypilot_web. See NOTICE + CHANGELOG for attribution.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AutopilotProvider = void 0;
+const mode_reanchor_1 = require("./mode-reanchor");
 const DEG_TO_RAD = Math.PI / 180;
 const RAD_TO_DEG = 180 / Math.PI;
 // Rev68: after a local target write we ignore pypilot echoes that do not
 // match, for up to this many ms. 2 s covers the worst RTT + pypilot apply
 // latency observed on Tunatunes (~500-800 ms). See receiveValue for why.
 const TARGET_PENDING_MS = 2500;
-// Tolerance for treating an echoed heading_command as "the value we asked
-// for" vs "stale echo of the previous value". Pypilot stores heading_command
-// as float and echoes verbatim in practice, but allow a small margin for
-// rounding on the wire.
-const TARGET_ECHO_TOL_RAD = 2 * DEG_TO_RAD;
+// Rev280 (audit T02): tightened from 2° to 0.1°. Pypilot echoes
+// `heading_command` verbatim; the previous 2° window was wide enough
+// that a stale echo of the previous value (e.g. 100°) matched a fresh
+// request of 101°, so the visor kept snapping the target back to the
+// value the user had just replaced. 0.1° covers float32 → double
+// rounding on the wire without accidentally consuming a stale echo.
+const TARGET_ECHO_TOL_RAD = 0.1 * DEG_TO_RAD;
 // Rev272 (audit R07): bounded-cost normalisation. The previous while
 // loop could spin forever on pathological inputs (e.g. |a-b| >= 1e15
 // where 2π is below the mantissa's precision, so subtracting a full
@@ -159,6 +162,15 @@ class AutopilotProvider {
                 if (Array.isArray(value)) {
                     this.pypilotModes = value.map(String);
                     this.data.options.modes = [...this.pypilotModes];
+                    // Rev280 (audit T16): the "courseCurrentPoint" action's
+                    // availability depends on pypilotModes.includes("nav"), so
+                    // a late-arriving ap.modes payload (typical: pypilot
+                    // publishes it once its config loader has finished, a few
+                    // seconds after the initial catalog) must trigger a fresh
+                    // recomputeActions and a delta push. Previously the action
+                    // stayed unavailable until the next engage/disengage.
+                    this.recomputeActions();
+                    changed = true;
                 }
                 break;
             case "ap.enabled": {
@@ -288,6 +300,22 @@ class AutopilotProvider {
             !this.data.options.modes.includes(mode)) {
             throw new Error(`Invalid mode: ${mode}`);
         }
+        // Rev292 (Carlos, navigating - bug C "piloto girando loco"):
+        // snapshot the OLD mode so we can decide whether the transition
+        // needs a heading_command re-anchor. Pypilot's ap.heading_command
+        // lives in different spaces depending on the mode:
+        //   compass/gps/nav   -> compass heading in degrees 0..360
+        //   wind              -> AWA in degrees -180..+180
+        //   true wind         -> TWA in degrees -180..+180
+        // A stale value from the previous mode (say a 90° heading) becomes
+        // a 90° AWA when we cross into wind mode, and pypilot promptly
+        // tries to swing the boat toward it — the "piloto se vuelve loco"
+        // symptom Carlos reported on Rev280 sea trial. The fix: right
+        // after ap.mode changes, force heading_command to the CURRENT
+        // measurement in the destination space, so the pilot has a
+        // sane target and never chases a value that meant something else.
+        const oldMode = String(this.data.mode || "").toLowerCase();
+        const newMode = String(mode || "").toLowerCase();
         // Rev279 (audit follow-up B): bump modeGen so a stale mode retry
         // aborts before overwriting a newer setMode / setState intent.
         const gen = ++this.modeGen;
@@ -302,6 +330,47 @@ class AutopilotProvider {
         if (this.modeGen !== gen) {
             throw new Error("mode change superseded after write");
         }
+        // Rev292: re-anchor. Only when the mode's target-space actually
+        // changed (compass↔gps↔nav share the compass space and don't need
+        // it; wind↔true wind share the wind space; only compass-family ↔
+        // wind-family crossings trigger the re-anchor).
+        if (this.data.engaged) {
+            try {
+                this._reAnchorTargetAfterModeChange(oldMode, newMode);
+            }
+            catch (e) {
+                // Never fail the mode change on the re-anchor path — worst
+                // case we leave the stale target and the sailor corrects with
+                // a nudge. Log so the diagnostic captures it.
+                // eslint-disable-next-line no-console
+                console.log(`[apProvider.setMode] re-anchor failed: ${e?.message || e}`);
+            }
+        }
+    }
+    /** Rev292: after a compass↔wind (or vice-versa) mode change, force
+     *  heading_command to the current measurement in the destination
+     *  space so pypilot never starts a mode with a target that meant
+     *  something else in the previous mode. Rev295: decision extracted
+     *  to src/mode-reanchor.ts (pure, unit-tested). This method only
+     *  glues that decision to the pypilot socket. */
+    _reAnchorTargetAfterModeChange(oldMode, newMode) {
+        const values = this.client.getValues?.() || {};
+        const d = (0, mode_reanchor_1.decideReAnchor)(oldMode, newMode, values);
+        // eslint-disable-next-line no-console
+        console.log(`[apProvider.setMode] re-anchor: ${d.reason}`);
+        if (!d.shouldReAnchor || d.valueDeg == null)
+            return;
+        // Push directly to pypilot without going through setTarget() —
+        // setTarget bumps targetGen and could race with the modeGen we
+        // just claimed. Also bypass echo cancellation: the anchor value is
+        // what we WANT to see, so the echo does match.
+        try {
+            this.client.set("ap.heading_command", d.valueDeg);
+        }
+        catch (e) {
+            // eslint-disable-next-line no-console
+            console.log(`[apProvider.setMode] re-anchor write failed: ${e?.message || e}`);
+        }
     }
     async setTarget(rad) {
         // Rev272 (audit R07): reject at the boundary. Downstream callers
@@ -341,8 +410,15 @@ class AutopilotProvider {
     }
     async adjustTarget(rad) {
         // Rev272 (audit R07): reject non-finite deltas at the boundary.
-        if (!Number.isFinite(rad) || Math.abs(rad) > 10) {
-            throw new Error(`Invalid adjust rad: ${rad}`);
+        // Rev292 (Carlos, navigating - bug C "piloto girando loco"):
+        // tighten the ceiling. `adjustTarget` is called from user nudges
+        // (max nudgeBig = 100°, so ~1.75 rad in extreme configurations)
+        // and never for tacks (those go through this.tack() → setTarget
+        // absolute). A single adjustTarget above 90° is either a bug in
+        // the caller or a corrupt payload — refuse it before it reaches
+        // pypilot, where it becomes an untraceable heading sweep.
+        if (!Number.isFinite(rad) || Math.abs(rad) > Math.PI / 2) {
+            throw new Error(`Invalid adjust rad: ${rad} (max ±π/2 = ±90°)`);
         }
         // Rev272 (audit R06): serialise on the shared chain. base must be
         // read AFTER any pending adjust has committed data.target,

package/dist/config-backup.js

@@ -0,0 +1,133 @@
+"use strict";
+// Config backup + restore helpers.
+//
+// Two independent things travel in one bundle:
+//   1. This plugin's own SK options (host, port, propose*, thresholds).
+//   2. The pypilot core settings that the boat spent effort tuning
+//      (P/I/D/DD/FF per pilot, tack angle/rate/delay/threshold, servo
+//      max_current, wind offset, compass alignment, profile names).
+//
+// Runtime values (headings, currents, temps) are NOT included. The
+// filter distinguishes them by name: any key whose "info.persistent"
+// flag is true in the pypilot catalog, or that matches an explicit
+// whitelist, is treated as a persistent setting.
+//
+// Restore applies the pypilot settings back to the core one at a time
+// via client.set(). The plugin's own props are handed back to the
+// caller so it can savePluginOptions() them.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRuntimeKey = isRuntimeKey;
+exports.captureBundle = captureBundle;
+exports.validateBundle = validateBundle;
+exports.applyBundleToPypilot = applyBundleToPypilot;
+/** Extra pypilot keys we always include even if their catalog entry
+ *  does not flag them as persistent. Empirically these have proved
+ *  worth carrying across a restore. */
+const EXTRA_PERSISTENT_KEYS = [
+    "ap.mode",
+    "profile",
+    "profiles",
+    "servo.max_current",
+    "servo.min_speed",
+    "servo.max_speed",
+];
+/** Runtime keys we NEVER include even if the catalog claims persistent. */
+const RUNTIME_BLOCKLIST_SUFFIXES = [
+    ".command",
+    ".position",
+    ".voltage",
+    ".current",
+    ".temperature",
+    ".rate",
+    ".heading",
+    ".heel",
+    ".pitch",
+    ".roll",
+    ".fault",
+    ".flags",
+];
+/** Returns true if the value of a pypilot key looks like a runtime
+ *  telemetry number (which we should never include in a config backup)
+ *  rather than a persistent setting. */
+function isRuntimeKey(key) {
+    for (const suf of RUNTIME_BLOCKLIST_SUFFIXES) {
+        if (key.endsWith(suf))
+            return true;
+    }
+    return false;
+}
+/** Build a bundle from the current in-memory state. `catalog` comes
+ *  from client.getCatalog(); `values` from client.getValues(); `props`
+ *  from the plugin's own options. */
+function captureBundle(args) {
+    const pypilotSettings = {};
+    for (const [key, entry] of Object.entries(args.catalog)) {
+        const persistent = entry?.info?.persistent === true;
+        const extra = EXTRA_PERSISTENT_KEYS.includes(key);
+        if (!persistent && !extra)
+            continue;
+        if (isRuntimeKey(key))
+            continue;
+        const v = args.values[key];
+        if (v === undefined)
+            continue;
+        // Skip nested objects and arrays — pypilot settings are scalars.
+        if (typeof v === "object" && v !== null)
+            continue;
+        pypilotSettings[key] = v;
+    }
+    return {
+        version: 1,
+        capturedTs: Date.now(),
+        revision: args.revision,
+        note: args.note,
+        pluginOptions: JSON.parse(JSON.stringify(args.props)),
+        pypilotSettings,
+    };
+}
+/** Validate that a bundle looks well-formed. Returns null on success,
+ *  an error message otherwise. Kept liberal — we accept older
+ *  bundles even if some fields are missing, as long as the essentials
+ *  parse. */
+function validateBundle(b) {
+    if (!b || typeof b !== "object")
+        return "not an object";
+    const bb = b;
+    if (bb.version !== 1)
+        return `unsupported version: ${bb.version}`;
+    if (typeof bb.capturedTs !== "number")
+        return "capturedTs missing";
+    if (!bb.pluginOptions || typeof bb.pluginOptions !== "object")
+        return "pluginOptions missing";
+    if (!bb.pypilotSettings || typeof bb.pypilotSettings !== "object")
+        return "pypilotSettings missing";
+    for (const [k, v] of Object.entries(bb.pypilotSettings)) {
+        if (v && typeof v === "object")
+            return `pypilotSettings.${k} is not a scalar`;
+    }
+    return null;
+}
+/** Apply the pypilot settings from a bundle to the running core via
+ *  the given setter. Skips keys that no longer exist in the catalog
+ *  (a firmware downgrade would remove them). Returns an audit list. */
+function applyBundleToPypilot(bundle, catalog, set) {
+    const out = [];
+    for (const [key, value] of Object.entries(bundle.pypilotSettings)) {
+        if (isRuntimeKey(key)) {
+            out.push({ key, status: "skipped-runtime" });
+            continue;
+        }
+        if (!(key in catalog)) {
+            out.push({ key, status: "skipped-unknown" });
+            continue;
+        }
+        try {
+            set(key, value);
+            out.push({ key, status: "applied" });
+        }
+        catch (e) {
+            out.push({ key, status: "error", error: String(e?.message || e) });
+        }
+    }
+    return out;
+}