@mikrojs/firmware 0.19.0 → 0.20.0-next.20260904225731

package/components/mikrojs/CMakeLists.txt

@@ -75,6 +75,7 @@ idf_component_register(
     "${MIK_SRC_DIR}/mik_sys_codec.cpp"
     "${MIK_SRC_DIR}/mik_result.cpp"
     "${MIK_SRC_DIR}/mik_udp.cpp"
+    "${MIK_SRC_DIR}/mik_watchdog.cpp"
     "${MIK_SRC_DIR}/mik_observable.cpp"
     "${MIK_SRC_DIR}/mikrojs.cpp"
     # nanocbor CBOR codec
@@ -196,7 +197,7 @@ include("${MIK_BYTECODE_CMAKE}")
 # Force linker to include self-registering native modules
 set(_MIK_MODULES cbor pin i2c i2s spi http http_server wifi rtc nvs_kv sntp sleep neopixel pwm uart ota)
 list(APPEND _MIK_MODULES ota_client)
-set(_MIK_BYTECODE_MODULES abort cbor env result schema fs http/server i2c i2s kv/nvs kv/rtc kv/shared module neopixel observable observable/lazy observable/operators ota ota/client ota/config pin pwm reader sleep spi sntp stdio stream sys test uart udp)
+set(_MIK_BYTECODE_MODULES abort cbor env result schema fs http/server i2c i2s kv/nvs kv/rtc kv/shared module neopixel observable observable/lazy observable/operators ota ota/client ota/config pin pwm reader sleep spi sntp stdio stream sys test uart udp watchdog)
 if(CONFIG_BT_ENABLED)
     list(APPEND _MIK_MODULES ble)
     list(APPEND _MIK_BYTECODE_MODULES ble)

package/components/mikrojs/mik_deploy.cpp

@@ -162,6 +162,13 @@ static bool manifest_matches(const ChecksumsManifest& m, const char* name, uint1
 
 /* ── Filesystem helpers ──────────────────────────────────────────── */
 
+/* Deploy handlers run on the main task without returning to MIK_Loop, so
+ * loops that touch flash per iteration feed the task watchdog themselves. */
+static void feed_watchdog(void) {
+    const MIKPlatform* platform = MIK_GetPlatform();
+    if (platform->feed_watchdog) platform->feed_watchdog();
+}
+
 static void mkdirs(const char* path) {
     char tmp[512];
     snprintf(tmp, sizeof(tmp), "%s", path);
@@ -182,6 +189,7 @@ static void rmdir_recursive(const char* path) {
     struct dirent* entry;
     while ((entry = readdir(dir)) != NULL) {
         if (strcmp(entry->d_name, ".") == 0 || strcmp(entry->d_name, "..") == 0) continue;
+        feed_watchdog();
 
         char full[512];
         snprintf(full, sizeof(full), "%s/%s", path, entry->d_name);
@@ -221,6 +229,7 @@ static bool copy_file(const char* src, const char* dst) {
     bool ok = true;
     int saved_errno = 0;
     while ((n = fread(buf, 1, sizeof(buf), in)) > 0) {
+        feed_watchdog();
         if (fwrite(buf, 1, n, out) != n) {
             saved_errno = errno;
             ok = false;
@@ -490,6 +499,7 @@ bool mik__handle_deploy_command(MIKReplTransport* transport, uint8_t cmd_type,
             while (remaining > 0) {
                 uint32_t chunk = remaining > sizeof(buf) ? sizeof(buf) : remaining;
                 if (!mik__proto_read_exact(transport, buf, chunk)) return false;
+                feed_watchdog();
                 if (fwrite(buf, 1, chunk, s_put_file) != chunk) {
                     /* Write failure: keep the protocol in sync by draining
                      * the rest of this chunk's bytes, then abort the PUT. */

package/components/mikrojs/mik_main.cpp

@@ -13,6 +13,9 @@
 #include "esp_littlefs.h"
 #include "esp_log.h"
 #include "esp_system.h"
+#if CONFIG_ESP_TASK_WDT_EN
+#include "esp_task_wdt.h"
+#endif
 #include "freertos/FreeRTOS.h"
 #include "freertos/task.h"
 #include "mikrojs.h"
@@ -22,6 +25,20 @@
 
 static const char* TAG = "mikrojs";
 
+#if CONFIG_ESP_TASK_WDT_INIT
+/* Ordering invariant: the JS blocking watchdog interrupts (with a stack trace)
+ * before the hardware TWDT resets the chip. The margin covers unwinding and
+ * printing the trace. onPanic.delay is not part of the sum: MIK_Loop feeds
+ * the TWDT through the grace window. CONFIG_ESP_TASK_WDT_TIMEOUT_S only
+ * exists under CONFIG_ESP_TASK_WDT_INIT. */
+#define MIK_TWDT_MARGIN_S 5
+static_assert(MIK_WATCHDOG_BLOCKING_DEFAULT_MS / 1000 + MIK_TWDT_MARGIN_S <
+                  CONFIG_ESP_TASK_WDT_TIMEOUT_S,
+              "watchdog.blocking default (30 s) must fire before the task watchdog: set "
+              "CONFIG_ESP_TASK_WDT_TIMEOUT_S=60 in sdkconfig, or delete sdkconfig and re-run "
+              "`idf.py set-target` so sdkconfig.defaults applies");
+#endif
+
 /* Error handler armed during a normal boot: when the app hits a fatal JS error
  * (uncaught exception or unhandled rejection) while running an OTA trial build,
  * flag the trial so the next reconcile reverts it. A JS error reboots as a clean
@@ -188,6 +205,9 @@ static bool platform_command_handler(MIKReplTransport* transport, uint8_t cmd_ty
     /* Restart: drain payload (should be 0), then restart */
     if (cmd_type == MIK_CMD_RESTART) {
         mik__proto_drain(transport, payload_len);
+        /* Say why: a silent reset is indistinguishable from a crash. */
+        printf("[mikrojs] restart requested by host\n");
+        fflush(stdout);
         esp_restart();
         return true; /* unreachable */
     }
@@ -261,7 +281,15 @@ static esp_err_t mount_littlefs(const char* base_path, const char* partition_lab
     conf.partition_label = partition_label;
     conf.format_if_mount_failed = true;
 
+#if CONFIG_ESP_TASK_WDT_EN
+    /* A first-boot format runs for seconds inside this one call, where no
+     * feed can reach; unsubscribe the main task for its duration. */
+    esp_task_wdt_delete(NULL);
+#endif
     esp_err_t ret = esp_vfs_littlefs_register(&conf);
+#if CONFIG_ESP_TASK_WDT_EN
+    esp_task_wdt_add(NULL);
+#endif
     if (ret != ESP_OK) {
         ESP_LOGE(TAG, "Failed to mount LittleFS partition '%s' at '%s': %s", partition_label,
                  base_path, esp_err_to_name(ret));
@@ -328,6 +356,17 @@ void MIK_Main(void) {
         printf("\n*** SAFE MODE: autorun skipped, dropping to REPL ***\n\n");
     }
 
+#if CONFIG_ESP_TASK_WDT_EN
+    /* Watch the main task: a hang in native code below JS now resets the
+     * chip instead of sitting forever. Fed from MIK_Loop and platform->yield. */
+    {
+        esp_err_t err = esp_task_wdt_add(NULL);
+        if (err != ESP_OK) {
+            ESP_LOGW(TAG, "Could not add the main task to the task watchdog: %s", esp_err_to_name(err));
+        }
+    }
+#endif
+
     /* Initialize NVS (needed for env vars, secrets, and WiFi) */
     {
         esp_err_t err = nvs_flash_init();
@@ -371,6 +410,22 @@ void MIK_Main(void) {
     MIKConfig app_config;
     MIK_LoadConfig("/appfs", &app_config);
 
+#if CONFIG_ESP_TASK_WDT_INIT
+    /* Same ordering invariant as the static_assert above, for a configured
+     * value. Clamp and warn rather than fail, as the memReserved clamp does. */
+    {
+        constexpr int kMaxBlockingMs = (CONFIG_ESP_TASK_WDT_TIMEOUT_S - MIK_TWDT_MARGIN_S) * 1000;
+        if (app_config.blocking_timeout_ms > kMaxBlockingMs) {
+            ESP_LOGW(TAG,
+                     "watchdog.blocking %d ms must stay %d s under the %d s task watchdog; "
+                     "clamping to %d ms",
+                     app_config.blocking_timeout_ms, MIK_TWDT_MARGIN_S,
+                     CONFIG_ESP_TASK_WDT_TIMEOUT_S, kMaxBlockingMs);
+            app_config.blocking_timeout_ms = kMaxBlockingMs;
+        }
+    }
+#endif
+
     /* Start file logging if configured (no-op when log_file is empty). */
     mik_logfile_init(&app_config);
 
@@ -710,6 +765,9 @@ void MIK_Main(void) {
     MIK_ProtocolClose();
     MIK_FreeTests(test_paths, test_count);
 
-    /* If we get here, the transport died. Restart. */
+    /* If we get here, the transport died. Restart, and say so: this reset
+     * reads as "software" on the next boot, same as a host restart. */
+    printf("[mikrojs] console transport closed, restarting\n");
+    fflush(stdout);
     esp_restart();
 }

package/components/mikrojs/mik_ota.cpp

@@ -57,6 +57,18 @@ constexpr size_t kTarBlock = 512;
 constexpr size_t kTarName = 100;  // ustar name field width
 constexpr int kMaxNameDepth = 8;  // path components a member may create
 
+// The boot install and the deploy-time verify run on the main task with no
+// MIK_Loop pass in between, so flash-bound loops feed the task watchdog here.
+// The host test has no platform and nothing to feed.
+#ifdef MIK_OTA_HOST_TEST
+void feed_watchdog(void) {}
+#else
+void feed_watchdog(void) {
+    const MIKPlatform* platform = MIK_GetPlatform();
+    if (platform->feed_watchdog) platform->feed_watchdog();
+}
+#endif
+
 // Classified failure cause carried back to JS. `corrupt` means the bytes are
 // deterministically bad (gzip/tar/SHA) so retrying identical bytes can't help;
 // `transient` is fs/mount/io; `oom` is an allocation failure.
@@ -201,7 +213,10 @@ bool sha256_file(const char* path, char out[65]) {
     Sha256 c;
     sha256_init(&c);
     size_t n;
-    while ((n = fread(buf, 1, kChunk, f)) > 0) sha256_update(&c, buf, n);
+    while ((n = fread(buf, 1, kChunk, f)) > 0) {
+        feed_watchdog();
+        sha256_update(&c, buf, n);
+    }
     bool read_err = ferror(f) != 0;
     free(buf);
     fclose(f);
@@ -564,6 +579,7 @@ bool unpack_tgz(const char* in_path, const char* dest_dir, const char** err, Ota
     unsigned char tail[8];   // rolling last-8-bytes of the file == the gzip trailer
     size_t tail_len = 0;
     for (;;) {
+        feed_watchdog();
         if (avail_in == 0 && !eof) {
             size_t in_n = fread(inbuf, 1, kChunk, in);
             // A read error also returns 0. Distinguish it from real EOF: treating
@@ -834,6 +850,7 @@ void rmtree_at(char* path, size_t cap, int depth) {
     dirent* ent;
     while ((ent = readdir(d)) != nullptr) {
         if (!strcmp(ent->d_name, ".") || !strcmp(ent->d_name, "..")) continue;
+        feed_watchdog();
         const int n = snprintf(path + base, cap - base, "/%s", ent->d_name);
         if (n < 0 || (size_t)n >= cap - base) {
             path[base] = 0;  // would truncate to a different path; skip it

package/components/mikrojs/mik_ota_client_module.cpp

@@ -32,6 +32,7 @@ using mikrojs::MIKOtaConfigWrite;
 using mikrojs::MIKOtaJsHooks;
 using mikrojs::MIKOtaApplyOutcome;
 using mikrojs::MIKOtaApplySession;
+using mikrojs::MIKOtaDeclineRecord;
 using mikrojs::MIKOtaError;
 using mikrojs::MIKOtaInstallOptions;
 using mikrojs::MIKOtaOffer;
@@ -381,7 +382,7 @@ JSValue ota_reconcile(JSContext* ctx, JSValue, int, JSValue*) {
     return obj;
 }
 
-/* running() -> { checksum?, version?, trial } */
+/* The running-build object, { checksum?, version?, trial }, for report(). */
 JSValue ota_running(JSContext* ctx, JSValue, int, JSValue*) {
     MIKOtaClientState* state = state_of(ctx);
     CHECK_NOT_NULL(state);
@@ -431,20 +432,6 @@ JSValue offer_to_js(JSContext* ctx, const MIKOtaOffer& offer) {
     return obj;
 }
 
-/* parseOffer(raw, {allowInsecure}) -> Offer | undefined */
-JSValue ota_parse_offer(JSContext* ctx, JSValue, int argc, JSValue* argv) {
-    bool allow_insecure = false;
-    if (argc > 1 && JS_IsObject(argv[1])) {
-        allow_insecure = opt_bool(ctx, argv[1], "allowInsecure", false);
-    }
-    MIKOtaOffer offer;
-    if (!mikrojs::mik__ota_parse_offer_js(ctx, argc > 0 ? argv[0] : JS_UNDEFINED, allow_insecure,
-                                          &offer)) {
-        return JS_UNDEFINED;
-    }
-    return offer_to_js(ctx, offer);
-}
-
 // ── applyOffer ──────────────────────────────────────────────────────────────
 
 /* The staging session, as the download callback sees it. Recovered from the
@@ -504,15 +491,47 @@ JSValue make_update_object(JSContext* ctx, size_t resume_offset) {
     return update;
 }
 
+/* True for the checksum shape the registry's checkin validation accepts. A
+ * lastDecline with any other checksum would 400 every future check-in — and
+ * permanently, since a failed round never settles and so never clears it. */
+bool is_wire_checksum(const char* s) {
+    for (int i = 0; i < 64; i++) {
+        char c = s[i];
+        if (!((c >= '0' && c <= '9') || (c >= 'a' && c <= 'f'))) return false;
+    }
+    return s[64] == '\0';
+}
+
+/* Record why an offered build was not taken, for the next report() to carry as
+ * lastDecline and a later settle() to mark delivered — the own-transport twin
+ * of the built-in client's NoteDecline, persisted because here the decline
+ * lands after the wake's check-in and must survive a deep sleep to make the
+ * next one. */
+void note_decline(const MIKOtaEnv* env, const std::string& checksum, const char* reason,
+                  const std::string& detail) {
+    if (!is_wire_checksum(checksum.c_str())) return;
+    MIKOtaDeclineRecord record;
+    snprintf(record.checksum, sizeof(record.checksum), "%s", checksum.c_str());
+    snprintf(record.reason, sizeof(record.reason), "%s", reason);
+    snprintf(record.detail, sizeof(record.detail), "%s", detail.c_str());
+    mikrojs::MIKOtaStore(env).SetDecline(record);
+}
+
 /* Close the attempt and settle applyOffer's promise. */
 void settle_apply(JSContext* ctx, bool downloaded, const std::string& message) {
     MIKOtaClientState* state = state_of(ctx);
     if (!state || !state->apply.active) return;
 
+    std::string checksum = state->apply.session.checksum;
     MIKOtaApplyOutcome outcome = MIKOtaApplyOutcome::kStaged;
     MIKOtaError error;
     bool ok = mikrojs::mik__ota_policy_apply_end(&state->apply.session, downloaded, message,
                                                  state->apply.options, &outcome, &error);
+    if (!ok) {
+        note_decline(state->env, checksum,
+                     error.name == "DownloadFailed" ? "download-failed" : "install-failed",
+                     error.message);
+    }
     JSValue result = ok ? mik__result_ok(ctx, JS_NewString(ctx, mikrojs::mik__ota_outcome_to_str(
                                                                     outcome)))
                         : mik__result_err_obj(ctx, error_to_js(ctx, error));
@@ -592,11 +611,18 @@ JSValue ota_apply_offer(JSContext* ctx, JSValue, int argc, JSValue* argv) {
     MIKOtaError error;
     if (!mikrojs::mik__ota_policy_apply_begin(state->env, offer, &state->apply.session, &outcome,
                                               &error)) {
+        note_decline(state->env, offer.checksum, "install-failed", error.message);
         JSValue failed = mik__result_err_obj(ctx, error_to_js(ctx, error));
         return MIK_NewResolvedPromise(ctx, 1, &failed);
     }
     if (!state->apply.session.update) {
-        /* Declined before staging: trial pending, current, abandoned, exhausted. */
+        /* Declined before staging: trial pending, current, abandoned, exhausted.
+         * Only the last two are recorded for the registry — the first two are
+         * the policy working as intended, mirroring the built-in's NoteDecline. */
+        if (outcome == MIKOtaApplyOutcome::kAbandoned ||
+            outcome == MIKOtaApplyOutcome::kExhausted) {
+            note_decline(state->env, offer.checksum, mikrojs::mik__ota_outcome_to_str(outcome), "");
+        }
         JSValue declined =
             mik__result_ok(ctx, JS_NewString(ctx, mikrojs::mik__ota_outcome_to_str(outcome)));
         return MIK_NewResolvedPromise(ctx, 1, &declined);
@@ -742,25 +768,7 @@ bool encode_config_doc(JSContext* ctx, JSValue doc, std::vector<uint8_t>* out) {
     return ok;
 }
 
-/* parseConfig(raw) -> StoredConfig | undefined */
-JSValue ota_parse_config(JSContext* ctx, JSValue, int argc, JSValue* argv) {
-    MIKOtaStoredConfig cfg = {};
-    JSValue doc = JS_UNDEFINED;
-    if (argc < 1 || !config_from_js(ctx, argv[0], &cfg, &doc)) {
-        JS_FreeValue(ctx, doc);
-        return JS_UNDEFINED;
-    }
-    JSValue obj = JS_NewObject(ctx);
-    if (cfg.rev[0]) JS_SetPropertyStr(ctx, obj, "rev", JS_NewString(ctx, cfg.rev));
-    JS_SetPropertyStr(ctx, obj, "version", JS_NewString(ctx, cfg.version));
-    if (JS_IsUndefined(doc)) return obj;
-    /* The document travels on as it arrived: whether it survives CBOR is
-     * settled by applyConfig, which is where the bytes are actually made. */
-    JS_SetPropertyStr(ctx, obj, "doc", doc);
-    return obj;
-}
-
-/* applyConfig(cfg, {trialBoots}) -> ConfigWrite */
+/* The config delivery, cfg + {trialBoots} -> ConfigWrite string, for settle(). */
 JSValue ota_apply_config(JSContext* ctx, JSValue, int argc, JSValue* argv) {
     MIKOtaClientState* state = state_of(ctx);
     CHECK_NOT_NULL(state);
@@ -809,22 +817,6 @@ bool set_config_echo(JSContext* ctx, JSValue obj, const char* rev_key, const MIK
     return has_error;
 }
 
-/* configState() -> {rev?, error?} */
-JSValue ota_config_state(JSContext* ctx, JSValue, int, JSValue*) {
-    MIKOtaClientState* state = state_of(ctx);
-    CHECK_NOT_NULL(state);
-
-    JSValue obj = JS_NewObject(ctx);
-    MIKOtaConfigErrorReport report = {};
-    if (set_config_echo(ctx, obj, "rev", state->env, &report)) {
-        JSValue error = JS_NewObject(ctx);
-        JS_SetPropertyStr(ctx, error, "rev", JS_NewString(ctx, report.rev));
-        JS_SetPropertyStr(ctx, error, "message", JS_NewString(ctx, report.message));
-        JS_SetPropertyStr(ctx, obj, "error", error);
-    }
-    return obj;
-}
-
 // ── the check-in exchange, for a client with its own transport ──────────────
 //
 // report() and settle() are the two halves the built-in client runs around its
@@ -833,6 +825,45 @@ JSValue ota_config_state(JSContext* ctx, JSValue, int, JSValue*) {
 // touches is an existing policy call, so a client that goes through here and
 // the built-in cannot disagree about what a round sends or settles.
 
+/* decline(checksum, reason, detail?) — record why the last offered build was
+ * not taken, for the next report() to carry as lastDecline. The apply paths
+ * record their own outcomes; this is for a reason only the app can see, such
+ * as a download budget it keeps across wakes. The caps are the registry's: an
+ * oversized reason would have the whole check-in rejected, so it throws here,
+ * while detail is free text and is cut to fit instead. */
+JSValue ota_decline(JSContext* ctx, JSValue, int argc, JSValue* argv) {
+    MIKOtaClientState* state = state_of(ctx);
+    CHECK_NOT_NULL(state);
+
+    const char* checksum =
+        argc > 0 && JS_IsString(argv[0]) ? JS_ToCString(ctx, argv[0]) : nullptr;
+    if (!checksum || !is_wire_checksum(checksum)) {
+        if (checksum) JS_FreeCString(ctx, checksum);
+        return JS_ThrowTypeError(ctx, "decline(): checksum must be 64 lowercase hex characters");
+    }
+    const char* reason = argc > 1 && JS_IsString(argv[1]) ? JS_ToCString(ctx, argv[1]) : nullptr;
+    if (!reason || reason[0] == '\0' || strlen(reason) > 64) {
+        JS_FreeCString(ctx, checksum);
+        if (reason) JS_FreeCString(ctx, reason);
+        return JS_ThrowTypeError(ctx, "decline(): reason must be 1 to 64 characters");
+    }
+    const char* detail = nullptr;
+    if (argc > 2 && !JS_IsUndefined(argv[2])) {
+        detail = JS_IsString(argv[2]) ? JS_ToCString(ctx, argv[2]) : nullptr;
+        if (!detail) {
+            JS_FreeCString(ctx, checksum);
+            JS_FreeCString(ctx, reason);
+            return JS_ThrowTypeError(ctx, "decline(): detail must be a string");
+        }
+    }
+
+    note_decline(state->env, checksum, reason, detail ? detail : "");
+    JS_FreeCString(ctx, checksum);
+    JS_FreeCString(ctx, reason);
+    if (detail) JS_FreeCString(ctx, detail);
+    return JS_UNDEFINED;
+}
+
 /* report() -> the check-in body the device owes its registry, wire field
  * shapes throughout so a proxy can forward fields verbatim. */
 JSValue ota_report(JSContext* ctx, JSValue, int, JSValue*) {
@@ -876,6 +907,20 @@ JSValue ota_report(JSContext* ctx, JSValue, int, JSValue*) {
         JS_SetPropertyStr(ctx, obj, "lastInstall", diag);
     }
 
+    /* Why the last offered build was not taken, recorded by applyOffer or
+     * decline(). Without it a registry cannot tell a device still working
+     * through a download from one that has stopped. */
+    MIKOtaDeclineRecord declined;
+    if (mikrojs::MIKOtaStore(env).GetDecline(&declined)) {
+        JSValue last = JS_NewObject(ctx);
+        JS_SetPropertyStr(ctx, last, "checksum", JS_NewString(ctx, declined.checksum));
+        JS_SetPropertyStr(ctx, last, "reason", JS_NewString(ctx, declined.reason));
+        if (declined.detail[0]) {
+            JS_SetPropertyStr(ctx, last, "detail", JS_NewString(ctx, declined.detail));
+        }
+        JS_SetPropertyStr(ctx, obj, "lastDecline", last);
+    }
+
     /* configRev / configError, through the same resolution as configState(). */
     MIKOtaConfigErrorReport report = {};
     if (set_config_echo(ctx, obj, "configRev", env, &report)) {
@@ -915,8 +960,10 @@ JSValue ota_settle(JSContext* ctx, JSValue, int argc, JSValue* argv) {
     /* Confirm before the deliveries, as the built-in does: it must settle the
      * document held BEFORE this round, never the one about to be armed. */
     mikrojs::mik__ota_policy_confirm(state->env);
-    /* The round completed, so the cached install report was delivered. */
+    /* The round completed, so the cached install report and the stored decline
+     * record were delivered. */
     state->has_last_install = false;
+    mikrojs::MIKOtaStore(state->env).ClearDecline();
 
     bool renamed = false;
     if (usable) {
@@ -957,7 +1004,7 @@ JSValue ota_settle(JSContext* ctx, JSValue, int argc, JSValue* argv) {
         JS_FreeValue(ctx, cfg_raw);
 
         /* The offer fields are top-level in the response, so the whole body
-         * goes to the parser, exactly as ota.parseOffer(body) would. */
+         * goes to the offer parser. */
         bool allow_insecure = false;
         if (argc > 1 && JS_IsObject(argv[1])) {
             allow_insecure = opt_bool(ctx, argv[1], "allowInsecure", false);
@@ -976,21 +1023,13 @@ int mik__ota_client_module_init(JSContext* ctx, JSModuleDef* m) {
     JS_SetModuleExport(ctx, m, "watch", JS_NewCFunction(ctx, mik__ota_client_watch, "watch", 1));
     JS_SetModuleExport(ctx, m, "config", JS_NewCFunction(ctx, mik__ota_client_config, "config", 0));
     JS_SetModuleExport(ctx, m, "reconcile", JS_NewCFunction(ctx, ota_reconcile, "reconcile", 0));
-    JS_SetModuleExport(ctx, m, "running", JS_NewCFunction(ctx, ota_running, "running", 0));
     JS_SetModuleExport(ctx, m, "confirm", JS_NewCFunction(ctx, ota_confirm, "confirm", 0));
     JS_SetModuleExport(ctx, m, "revert", JS_NewCFunction(ctx, ota_revert, "revert", 0));
     JS_SetModuleExport(ctx, m, "bearer", JS_NewCFunction(ctx, ota_bearer, "bearer", 0));
     JS_SetModuleExport(ctx, m, "registry", JS_NewCFunction(ctx, ota_registry, "registry", 0));
-    JS_SetModuleExport(ctx, m, "parseOffer",
-                       JS_NewCFunction(ctx, ota_parse_offer, "parseOffer", 2));
     JS_SetModuleExport(ctx, m, "applyOffer",
                        JS_NewCFunction(ctx, ota_apply_offer, "applyOffer", 3));
-    JS_SetModuleExport(ctx, m, "parseConfig",
-                       JS_NewCFunction(ctx, ota_parse_config, "parseConfig", 1));
-    JS_SetModuleExport(ctx, m, "applyConfig",
-                       JS_NewCFunction(ctx, ota_apply_config, "applyConfig", 2));
-    JS_SetModuleExport(ctx, m, "configState",
-                       JS_NewCFunction(ctx, ota_config_state, "configState", 0));
+    JS_SetModuleExport(ctx, m, "decline", JS_NewCFunction(ctx, ota_decline, "decline", 3));
     JS_SetModuleExport(ctx, m, "report", JS_NewCFunction(ctx, ota_report, "report", 0));
     JS_SetModuleExport(ctx, m, "settle", JS_NewCFunction(ctx, ota_settle, "settle", 2));
     return 0;
@@ -1033,16 +1072,12 @@ JSModuleDef* mik__ota_client_init(JSContext* ctx) {
     JS_AddModuleExport(ctx, m, "watch");
     JS_AddModuleExport(ctx, m, "config");
     JS_AddModuleExport(ctx, m, "reconcile");
-    JS_AddModuleExport(ctx, m, "running");
     JS_AddModuleExport(ctx, m, "confirm");
     JS_AddModuleExport(ctx, m, "revert");
     JS_AddModuleExport(ctx, m, "bearer");
     JS_AddModuleExport(ctx, m, "registry");
-    JS_AddModuleExport(ctx, m, "parseOffer");
     JS_AddModuleExport(ctx, m, "applyOffer");
-    JS_AddModuleExport(ctx, m, "parseConfig");
-    JS_AddModuleExport(ctx, m, "applyConfig");
-    JS_AddModuleExport(ctx, m, "configState");
+    JS_AddModuleExport(ctx, m, "decline");
     JS_AddModuleExport(ctx, m, "report");
     JS_AddModuleExport(ctx, m, "settle");
     return m;

package/components/mikrojs/mik_sleep.cpp

@@ -3,6 +3,7 @@
 #include "esp_sleep.h"
 #include "soc/soc_caps.h"
 
+#include "mikrojs/platform.h"
 #include "mikrojs/private.h"
 #include "mikrojs/utils.h"
 #include "mikrojs_esp32.h"
@@ -274,6 +275,12 @@ static JSValue mik__sleep_light(JSContext* ctx, JSValue this_val, int argc, JSVa
     esp_err_t err = esp_light_sleep_start();
     mik__serial_io_attach_usb();
 
+    /* esp_timer keeps counting through light sleep, so without this the
+     * sleep would count against the blocking and feed limits and the TWDT. */
+    const MIKPlatform* platform = MIK_GetPlatform();
+    if (platform->feed_watchdog) platform->feed_watchdog();
+    mik__watchdog_wake(MIK_GetRuntime(ctx));
+
     if (err != ESP_OK)
         return JS_ThrowInternalError(ctx, "light sleep failed: %s", esp_err_to_name(err));
 

package/components/mikrojs/platform_esp32.cpp

@@ -14,6 +14,9 @@
 #include <freertos/FreeRTOS.h>
 #include <freertos/task.h>
 #include <soc/soc_caps.h>
+#if CONFIG_ESP_TASK_WDT_EN
+#include <esp_task_wdt.h>
+#endif
 
 #include <stdarg.h>
 #include <stdio.h>
@@ -53,7 +56,20 @@ static void esp32_deep_sleep_us(uint64_t us) {
     /* Never reached */
 }
 
+/* task_wdt.c is only compiled under CONFIG_ESP_TASK_WDT_EN (the header has no
+ * guard), so every TWDT call is wrapped; the test firmware turns it off. */
+#if CONFIG_ESP_TASK_WDT_EN
+static void esp32_feed_watchdog(void) {
+    esp_task_wdt_reset();
+}
+#endif
+
 static void esp32_yield(void) {
+    /* Every cooperative yield feeds the TWDT: between jobs, in the serve
+     * loop's wait, and while the app is paused. */
+#if CONFIG_ESP_TASK_WDT_EN
+    esp_task_wdt_reset();
+#endif
     vTaskDelay(1);
 }
 
@@ -321,6 +337,11 @@ static const MIKPlatform esp32_platform = {
     .restart = esp32_restart,
     .deep_sleep_us = esp32_deep_sleep_us,
     .yield = esp32_yield,
+#if CONFIG_ESP_TASK_WDT_EN
+    .feed_watchdog = esp32_feed_watchdog,
+#else
+    .feed_watchdog = nullptr,
+#endif
     .get_free_system_mem = esp32_get_free_system_mem,
     .get_min_free_system_mem = esp32_get_min_free_system_mem,
     .get_total_system_mem = esp32_get_total_system_mem,

package/components/mikrojs/test/CMakeLists.txt

@@ -24,6 +24,7 @@ set(_MIK_TEST_SRCS
     timers_js_test.cpp
     timers_test.cpp
     udp_test.cpp
+    watchdog_test.cpp
     wifi_test.cpp
 )
 if(CONFIG_BT_ENABLED)

package/components/mikrojs/test/watchdog_test.cpp

@@ -0,0 +1,280 @@
+#include <cerrno>
+#include <cstring>
+#include <string>
+#include <vector>
+
+#include "esp_timer.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "mikrojs.h"
+#include "mikrojs/platform.h"
+#include "private.h"
+#include "quickjs.h"
+#include "soc/soc_caps.h"
+#include "unity.h"
+
+/* The portable layers (blocking, feed, awake) are covered on the host. These
+ * check what only exists on silicon: the platform hook, lightSleep's budget
+ * re-stamp with esp_timer really counting through the sleep, the REPL
+ * surviving a timeout, and the limits MIK_SetConfig switches on.
+ * The test firmware builds with CONFIG_ESP_TASK_WDT_EN=n, so nothing here
+ * can reset the chip. */
+
+static MIKRuntime* rt;
+static JSContext* ctx;
+
+static void setup(int blocking_ms, int feed_ms, int awake_ms) {
+    rt = MIK_NewRuntime();
+    ctx = MIK_GetJSContext(rt);
+    MIKConfig cfg;
+    MIK_DefaultConfig(&cfg);
+    cfg.blocking_timeout_ms = blocking_ms;
+    cfg.feed_timeout_ms = feed_ms;
+    cfg.awake_timeout_ms = awake_ms;
+    MIK_SetConfig(rt, &cfg);
+}
+
+static void teardown() { MIK_FreeRuntime(rt); }
+
+static JSValue eval_script(const char* code) {
+    return JS_Eval(ctx, code, strlen(code), "test.js", JS_EVAL_TYPE_GLOBAL);
+}
+
+static JSValue eval_module(const char* code) {
+    JSValue ret = MIK_EvalModuleContent(ctx, "mikro/test", code, strlen(code));
+    if (!JS_IsException(ret)) {
+        JS_FreeValue(ctx, ret);
+        mik__execute_jobs(ctx);
+    }
+    return ret;
+}
+
+static bool global_bool(const char* name) {
+    JSValue global = JS_GetGlobalObject(ctx);
+    JSValue v = JS_GetPropertyStr(ctx, global, name);
+    bool b = JS_ToBool(ctx, v) == 1;
+    JS_FreeValue(ctx, v);
+    JS_FreeValue(ctx, global);
+    return b;
+}
+
+/* Pump MIK_Loop until it reports a stop or `ms` elapse. True when stopped. */
+static bool pump_until_stop(int ms) {
+    int64_t deadline = esp_timer_get_time() + (int64_t)ms * 1000;
+    while (esp_timer_get_time() < deadline) {
+        if (MIK_Loop(rt) != 0) return true;
+        vTaskDelay(pdMS_TO_TICKS(10));
+    }
+    return false;
+}
+
+/* ── Platform hook ───────────────────────────────────────────────── */
+
+TEST_CASE("feed_watchdog follows CONFIG_ESP_TASK_WDT_EN", "[watchdog]") {
+    const MIKPlatform* platform = MIK_GetPlatform();
+#if CONFIG_ESP_TASK_WDT_EN
+    TEST_ASSERT_NOT_NULL(platform->feed_watchdog);
+    platform->feed_watchdog(); /* unsubscribed task: must be harmless */
+#else
+    TEST_ASSERT_NULL(platform->feed_watchdog);
+#endif
+}
+
+/* ── Blocking deadline ───────────────────────────────────────────── */
+
+TEST_CASE("blocking watchdog interrupts a runaway loop", "[watchdog]") {
+    setup(1000, 0, 0);
+    int64_t t0 = esp_timer_get_time();
+    JSValue ret = eval_script("while (true) {}");
+    int64_t elapsed_ms = (esp_timer_get_time() - t0) / 1000;
+    TEST_ASSERT_TRUE_MESSAGE(JS_IsException(ret), "runaway loop should be interrupted");
+    JSValue exc = JS_GetException(ctx);
+    TEST_ASSERT_TRUE_MESSAGE(JS_IsUncatchableError(exc), "the interrupt must be uncatchable");
+    JS_FreeValue(ctx, exc);
+    TEST_ASSERT_TRUE_MESSAGE(elapsed_ms >= 900 && elapsed_ms < 5000,
+                             "should fire near the 1 s budget");
+    teardown();
+}
+
+TEST_CASE("blocking watchdog error cannot be caught", "[watchdog]") {
+    setup(1000, 0, 0);
+    JSValue ret = eval_script(R"(
+        globalThis.__caught = false;
+        try { while (true) {} } catch (e) { globalThis.__caught = true; }
+    )");
+    TEST_ASSERT_TRUE_MESSAGE(JS_IsException(ret), "runaway loop should be interrupted");
+    JSValue exc = JS_GetException(ctx);
+    JS_FreeValue(ctx, exc);
+    TEST_ASSERT_FALSE_MESSAGE(global_bool("__caught"), "try/catch must not swallow the interrupt");
+    teardown();
+}
+
+TEST_CASE("blocking watchdog leaves a loop under budget alone", "[watchdog]") {
+    setup(2000, 0, 0);
+    JSValue ret = eval_script(R"(
+        const end = Date.now() + 500;
+        while (Date.now() < end) {}
+        globalThis.__done = true;
+    )");
+    TEST_ASSERT_FALSE_MESSAGE(JS_IsException(ret), "loop under budget must not be interrupted");
+    JS_FreeValue(ctx, ret);
+    TEST_ASSERT_TRUE(global_bool("__done"));
+    teardown();
+}
+
+/* Light sleep disconnects the UART console on targets without USB
+   Serial/JTAG, which stalls the test monitor. Same skip as sleep_test.cpp. */
+TEST_CASE("lightSleep past the blocking budget does not fire", "[watchdog]") {
+#if !SOC_USB_SERIAL_JTAG_SUPPORTED
+    TEST_IGNORE_MESSAGE("light sleep disconnects UART console, skipped on non-USB targets");
+#endif
+    setup(1000, 0, 0);
+    JSValue ret = eval_module(R"(
+        import { lightSleep } from "native:mikro/sleep";
+        const spin = (ms) => { const end = Date.now() + ms; while (Date.now() < end) {} };
+        spin(300); /* lands a budget stamp well before the sleep */
+        try {
+            lightSleep({timer: 1500000});
+        } catch (e) {
+            globalThis.__skipped = true; /* board cannot light-sleep; not a watchdog failure */
+        }
+        spin(300); /* over budget only if the sleep was counted */
+        globalThis.__done = true;
+    )");
+    TEST_ASSERT_FALSE_MESSAGE(JS_IsException(ret), "Module eval should not throw");
+    if (global_bool("__skipped")) {
+        teardown();
+        TEST_IGNORE_MESSAGE("lightSleep unavailable on this board");
+    }
+    TEST_ASSERT_TRUE_MESSAGE(global_bool("__done"),
+                             "lightSleep must not count against the blocking budget");
+    teardown();
+}
+
+/* ── Feed deadline ───────────────────────────────────────────────── */
+
+TEST_CASE("feed deadline stops a runtime that never feeds", "[watchdog]") {
+    setup(0, 1000, 0);
+    TEST_ASSERT_TRUE_MESSAGE(pump_until_stop(5000),
+                             "loop should stop once the feed deadline passes");
+    TEST_ASSERT_TRUE(MIK_IsStopRequested(rt));
+    teardown();
+}
+
+TEST_CASE("watchdog.feed() keeps the feed deadline from firing", "[watchdog]") {
+    setup(0, 1000, 0);
+    JSValue ret = eval_module(R"(
+        import { watchdog } from "mikro/watchdog";
+        setInterval(() => watchdog.feed(), 100);
+    )");
+    TEST_ASSERT_FALSE_MESSAGE(JS_IsException(ret), "Module eval should not throw");
+    TEST_ASSERT_FALSE_MESSAGE(pump_until_stop(2500), "a fed runtime must not stop");
+    teardown();
+}
+
+TEST_CASE("watchdog.feed() without a feed budget is a no-op", "[watchdog]") {
+    setup(0, 0, 0);
+    JSValue ret = eval_module(R"(
+        import { watchdog } from "mikro/watchdog";
+        watchdog.feed();
+        globalThis.__ok = true;
+    )");
+    TEST_ASSERT_FALSE_MESSAGE(JS_IsException(ret), "Module eval should not throw");
+    TEST_ASSERT_TRUE(global_bool("__ok"));
+    teardown();
+}
+
+/* ── Awake budget ────────────────────────────────────────────────── */
+
+static int s_error_calls;
+static void count_errors(JSContext*, JSValue, void*) { s_error_calls++; }
+
+TEST_CASE("awake budget stops the runtime without a JS error", "[watchdog]") {
+    /* The budget counts from boot, so on a device that has been running the
+     * suite it is already spent when the runtime starts counting. */
+    setup(0, 0, 1000);
+    s_error_calls = 0;
+    MIK_SetErrorHandler(rt, count_errors, nullptr);
+    TEST_ASSERT_TRUE_MESSAGE(pump_until_stop(3000), "loop should stop once the budget elapses");
+    TEST_ASSERT_TRUE(MIK_IsStopRequested(rt));
+    TEST_ASSERT_EQUAL_MESSAGE(0, s_error_calls,
+                              "awake must not reach the error handler (OTA trial rollback)");
+    teardown();
+}
+
+/* ── REPL survives a timeout ────────────────────────────────────────── */
+
+struct MockTransport {
+    std::vector<uint8_t> input;
+    size_t pos = 0;
+    std::vector<uint8_t> output;
+};
+
+static int mock_read(uint8_t* buf, size_t size, void* opaque) {
+    auto* m = static_cast<MockTransport*>(opaque);
+    if (m->pos >= m->input.size()) {
+        errno = 0; /* not EAGAIN: true EOF */
+        return -1;
+    }
+    size_t n = m->input.size() - m->pos;
+    if (n > size) n = size;
+    memcpy(buf, m->input.data() + m->pos, n);
+    m->pos += n;
+    return (int)n;
+}
+
+static void mock_write(const void* buf, size_t len, void* opaque) {
+    auto* m = static_cast<MockTransport*>(opaque);
+    auto* bytes = static_cast<const uint8_t*>(buf);
+    m->output.insert(m->output.end(), bytes, bytes + len);
+}
+
+static void append_frame(std::vector<uint8_t>& buf, uint8_t type, const char* payload) {
+    uint32_t len = payload ? (uint32_t)strlen(payload) : 0;
+    buf.push_back(type);
+    for (int i = 0; i < 4; i++) buf.push_back((uint8_t)(len >> (8 * i)));
+    if (len > 0) buf.insert(buf.end(), payload, payload + len);
+}
+
+/* Payload of the first frame of `type`, or empty when none was sent. */
+static std::string find_payload(const std::vector<uint8_t>& data, uint8_t type) {
+    size_t pos = 0;
+    while (pos + MIK_PROTO_HEADER_SIZE <= data.size()) {
+        uint32_t len = (uint32_t)data[pos + 1] | ((uint32_t)data[pos + 2] << 8) |
+                       ((uint32_t)data[pos + 3] << 16) | ((uint32_t)data[pos + 4] << 24);
+        if (pos + MIK_PROTO_HEADER_SIZE + len > data.size()) break;
+        if (data[pos] == type) {
+            return std::string((const char*)data.data() + pos + MIK_PROTO_HEADER_SIZE, len);
+        }
+        pos += MIK_PROTO_HEADER_SIZE + len;
+    }
+    return "";
+}
+
+TEST_CASE("REPL eval of a runaway loop reports an error and the session survives",
+          "[watchdog]") {
+    setup(1000, 0, 0);
+    MockTransport mock;
+    append_frame(mock.input, MIK_CMD_EVAL, "while (true) {}");
+    append_frame(mock.input, MIK_CMD_EVAL, "1 + 2");
+    append_frame(mock.input, MIK_CMD_EXIT, nullptr);
+
+    MIKReplTransport transport = {};
+    transport.read = mock_read;
+    transport.write = mock_write;
+    transport.ctx = &mock;
+    MIK_ProtocolOpen(&transport);
+    MIK_ProtocolAttach(rt);
+    MIK_ProtocolServeLoop();
+    MIK_ProtocolDetach();
+    MIK_ProtocolClose();
+
+    std::string err = find_payload(mock.output, MIK_MSG_EVAL_ERROR);
+    TEST_ASSERT_TRUE_MESSAGE(err.find("InternalError") != std::string::npos,
+                             "runaway eval should report the interrupt as an eval error");
+    std::string result = find_payload(mock.output, MIK_MSG_RESULT);
+    TEST_ASSERT_EQUAL_STRING_MESSAGE("3", result.c_str(),
+                                     "the next eval should still answer");
+    TEST_ASSERT_FALSE_MESSAGE(MIK_IsStopRequested(rt), "a REPL timeout must not stop the runtime");
+    teardown();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikrojs/firmware",
-  "version": "0.19.0",
+  "version": "0.20.0-next.20260904225731",
   "description": "Mikro.js ESP32 firmware: ESP-IDF component, build tools, and project template",
   "keywords": [
     "esp-idf",
@@ -47,8 +47,8 @@
   },
   "dependencies": {
     "esbuild": "^0.28.0",
-    "@mikrojs/quickjs": "0.19.0",
-    "@mikrojs/native": "0.19.0"
+    "@mikrojs/native": "0.20.0-next.20260904225731+071a2a9",
+    "@mikrojs/quickjs": "0.20.0-next.20260904225731+071a2a9"
   },
   "engines": {
     "node": ">=24.0.0"

package/sdkconfig.defaults

@@ -68,6 +68,16 @@ CONFIG_ESP_EVENT_POST_FROM_IRAM_ISR=n
 # Without this, the 128-byte RX FIFO overflows during deploy.
 CONFIG_UART_ISR_IN_IRAM=y
 
+# --- Task watchdog ---
+# The main task (which runs the JS runtime) subscribes in MIK_Main and is fed
+# from MIK_Loop and platform->yield. PANIC makes a timeout reset the chip
+# instead of only logging; it also applies to the idle-task checks, so any
+# task that starves idle for the timeout reboots the device. The JS blocking
+# watchdog (30 s default) must fire first; mik_main.cpp asserts the order.
+# 60 is the Kconfig ceiling.
+CONFIG_ESP_TASK_WDT_PANIC=y
+CONFIG_ESP_TASK_WDT_TIMEOUT_S=60
+
 # --- LittleFS ---
 # Track modification time so fs.stat() / fs.readDir() surface mtime
 # (exposed as ms-since-epoch on the StatResult object).