@mikrojs/native 0.19.0 → 0.20.0-next.20260904225731

package/CMakeLists.txt

@@ -61,6 +61,7 @@ set(MIKROJS_CORE_SOURCES
     src/mik_ota_js_hooks.cpp
     src/mik_ota_client.cpp
     src/mik_sys_codec.cpp
+    src/mik_watchdog.cpp
 )
 
 add_library(mikrojs STATIC
@@ -91,7 +92,7 @@ endif()
 include(cmake/mikrojs_bytecode.cmake)
 mikrojs_generate_bytecode(
     RUNTIME_DIR "${CMAKE_CURRENT_SOURCE_DIR}/runtime"
-    MODULES abort cbor env result schema fs i2c 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
+    MODULES abort cbor env result schema fs i2c 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
     MODULE_PREFIX "mikro"
     SYMBOL_PREFIX "mikro"
     TARGET gen_bytecode
@@ -222,6 +223,7 @@ if(BUILD_TESTING)
         test/ota_wire_fixtures_test.cpp
         test/schema_conformance_test.cpp
         test/sys_codec_test.cpp
+        test/watchdog_test.cpp
     )
 
     # ── Check-in wire fixtures ───────────────────────────────────────

package/include/mikrojs/mikrojs.h

@@ -54,8 +54,18 @@ typedef struct MIKConfig {
     char log_dir[64];
     uint32_t log_max_size;
     MIKLogFlush log_flush;
+    /* Watchdog budgets in ms, 0 = disabled. Mirror of the `watchdog` key in
+     * the host-side TS config. blocking: one event-loop turn holding the
+     * loop; feed: gap between watchdog.feed() calls; awake: time since boot. */
+    int blocking_timeout_ms;
+    int feed_timeout_ms;
+    int awake_timeout_ms;
 } MIKConfig;
 
+/* Shipped blocking default. The ESP32 side static_asserts this against the
+ * hardware TWDT timeout so the two cannot drift out of order. */
+#define MIK_WATCHDOG_BLOCKING_DEFAULT_MS 30000
+
 void MIK_DefaultConfig(MIKConfig* config);
 int MIK_LoadConfig(const char* base_path, MIKConfig* config);
 void MIK_SetConfig(MIKRuntime* mik_rt, const MIKConfig* config);

package/include/mikrojs/ota_policy.h

@@ -51,6 +51,18 @@ public:
 
 using MIKOtaDownloadFn = std::function<bool(MIKOtaUpdate& update, MIKOtaError* out_err)>;
 
+/* Why the last offered build was not taken, in wire-string form, held in the
+ * store until a completed check-in delivers it. Persisted rather than held in
+ * memory (unlike the built-in client's copy) because an own-transport decline
+ * happens after that wake's check-in, so it must survive a deep sleep to make
+ * the next report. Field caps match the registry's checkin validation, which
+ * rejects a body whose lastDecline oversteps them. */
+struct MIKOtaDeclineRecord {
+    char checksum[65] = {};
+    char reason[65] = {};
+    char detail[257] = {};
+};
+
 class MIKOtaStore {
 public:
     explicit MIKOtaStore(const MIKOtaEnv* env) : env_(env) {}
@@ -75,6 +87,11 @@ public:
     bool GetInFlight() const;
     void SetInFlight(bool in_flight);
 
+    /* False when no record stands. */
+    bool GetDecline(MIKOtaDeclineRecord* out) const;
+    void SetDecline(const MIKOtaDeclineRecord& record);
+    void ClearDecline();
+
 private:
     const MIKOtaEnv* env_;
 };

package/include/mikrojs/platform.h

@@ -19,6 +19,9 @@ typedef struct MIKPlatform {
      *  deep sleep (hosts), where callers fall back to restart(). */
     void (*deep_sleep_us)(uint64_t us);
     void (*yield)(void);
+    /** Feed the hardware task watchdog for the calling task. NULL where the
+     *  platform has none (hosts) or the watchdog is compiled out. */
+    void (*feed_watchdog)(void);
     size_t (*get_free_system_mem)(void);
     size_t (*get_min_free_system_mem)(void); /* All-time low watermark */
     size_t (*get_total_system_mem)(void);

package/include/mikrojs/private.h

@@ -80,6 +80,21 @@ struct MIKRuntime {
      * the host can still deploy/clean/--recover during the grace window,
      * then platform->restart() fires from MIK_Loop. */
     int64_t restart_at_us;
+    /* Watchdog state (mik_watchdog.cpp). All per-runtime, no atomics needed.
+     * blocking_start_us == 0 means "stamp on the next interrupt poll"; the
+     * handler switches itself off when it fires and back on at mik__blocking_begin. */
+    int64_t blocking_start_us;
+    bool blocking_armed;
+    /* Set when the limit is hit, consumed by the error dump that reports it. */
+    bool blocking_tripped;
+    /* Feed deadline: last feed()/re-stamp; feed_armed clears when it fires. */
+    int64_t feed_last_us;
+    bool feed_armed;
+    /* Awake budget: deploy-pause time credited against get_boot_us(). */
+    int64_t awake_pause_offset_us;
+    bool awake_armed;
+    /* Boot-clock stamp of the current pause; 0 = not paused. */
+    int64_t pause_start_us;
     const char* fs_base_path;
     const char* fs_root;  /* Sandbox root for mikrojs/fs operations (separate from module resolution) */
     size_t fs_limit;      /* Max bytes for fs_root (0 = unlimited) */
@@ -296,6 +311,31 @@ JSModuleDef* mik__udp_init(JSContext* ctx);
 JSModuleDef* mik__observable_init(JSContext* ctx);
 void mik__observable_dispatch_free(struct MIKRuntime* mik_rt);
 
+/* Watchdog (mik_watchdog.cpp). */
+/* Start a fresh blocking budget: top of each MIK_Loop pass, eval entry
+ * points, REPL eval, and on return from a deliberately blocking native
+ * (lightSleep). One store; the interrupt handler stamps on its next poll. */
+void mik__blocking_begin(struct MIKRuntime* mik_rt);
+/* JS_SetInterruptHandler callback; opaque is the MIKRuntime*. */
+int mik__watchdog_interrupt(JSRuntime* rt, void* opaque);
+/* If the blocking deadline was hit, log the watchdog line and clear the
+ * flag. Returns whether it did; callers print the error trace after. */
+bool mik__watchdog_report_blocking(struct MIKRuntime* mik_rt);
+/* Switch feed/awake on from mik_rt->config. Called once the config is set. */
+void mik__watchdog_arm(struct MIKRuntime* mik_rt);
+/* Feed and awake checks. Runs at the top of MIK_Loop after the restart_at_us
+ * branch; a feed miss throws an uncatchable error into mik_rt->ctx, on an
+ * awake overrun calls MIK_Stop directly. */
+void mik__watchdog_check(struct MIKRuntime* mik_rt);
+/* On return from lightSleep: fresh blocking budget and feed window. */
+void mik__watchdog_wake(struct MIKRuntime* mik_rt);
+/* Deploy/REPL pause bookkeeping: re-stamp the feed clock and credit the
+ * paused span to the awake budget. */
+void mik__watchdog_pause_begin(struct MIKRuntime* mik_rt);
+void mik__watchdog_pause_end(struct MIKRuntime* mik_rt);
+/* Registers native:mikro/watchdog (feed) on ctx. */
+void mik__watchdog_init(JSContext* ctx);
+
 bool mik__repl_is_evaluating(void);
 
 /* REPL protocol mode (mik_repl.cpp) — used by mik_console.cpp, mik_stdio.cpp */

package/include/mikrojs/utils.h

@@ -68,6 +68,11 @@ void mik_assert(const struct AssertionInfo info);
     }
 
 void mik_call_handler(JSContext* ctx, JSValue func, int argc, JSValue* argv);
+/* Print one always-visible error line the way console.error does: an error
+ * frame in protocol mode, stderr otherwise. platform->log is filtered per
+ * tag on the device and silent by default, so lines that precede a reboot
+ * (watchdog lines, panic actions) go through here instead. */
+void mik__print_error_line(const char* fmt, ...) __attribute__((format(printf, 1, 2)));
 void mik_dump_error(JSContext* ctx);
 void mik_dump_error1(JSContext* ctx, JSValue exception_val);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikrojs/native",
-  "version": "0.19.0",
+  "version": "0.20.0-next.20260904225731",
   "description": "Mikro.js C++ runtime library and Node.js native addon",
   "keywords": [
     "esp32",
@@ -80,21 +80,22 @@
     "./runtime/test/types": "./runtime/test/types.ts",
     "./runtime/uart/types": "./runtime/uart/types.ts",
     "./runtime/udp/types": "./runtime/udp/types.ts",
+    "./runtime/watchdog/types": "./runtime/watchdog/types.ts",
     "./runtime/wifi/types": "./runtime/wifi/types.ts"
   },
   "dependencies": {
     "cmake-js": "^8.0.0",
     "node-addon-api": "^8.7.0",
     "node-gyp-build": "^4.8.4",
-    "@mikrojs/quickjs": "0.19.0"
+    "@mikrojs/quickjs": "0.20.0-next.20260904225731+071a2a9"
   },
   "devDependencies": {
     "@swc/core": "^1.15.30",
     "@types/node": "^24.12.2",
     "esbuild": "^0.28.0",
     "terser": "^5.46.2",
-    "@mikrojs/registry": "0.19.0",
-    "@mikrojs/schema": "0.19.0"
+    "@mikrojs/registry": "0.20.0-next.20260904225731+071a2a9",
+    "@mikrojs/schema": "0.20.0-next.20260904225731+071a2a9"
   },
   "engines": {
     "node": ">=24.0.0"

package/runtime/internal.d.ts

@@ -170,6 +170,10 @@ declare module 'native:mikro/pin' {
   export function analogReadMillivolts(pin: number, attenuation: number): Result<number, PinError>
 }
 
+declare module 'native:mikro/watchdog' {
+  export function feed(): void
+}
+
 declare module 'native:mikro/sleep' {
   import type {DeepWakeupSources, LightWakeupSources} from '@mikrojs/native/runtime/sleep/types'
 
@@ -580,12 +584,8 @@ declare module 'native:mikro/ota_client' {
 
   // The mikro/ota policy surface.
   export const reconcile: Ota['reconcile']
-  export const running: Ota['running']
-  export const parseOffer: Ota['parseOffer']
   export const applyOffer: Ota['applyOffer']
-  export const parseConfig: Ota['parseConfig']
-  export const applyConfig: Ota['applyConfig']
-  export const configState: Ota['configState']
+  export const decline: Ota['decline']
   export const report: Ota['report']
   export const settle: Ota['settle']
   export const confirm: Ota['confirm']

package/runtime/ota/ota.ts

@@ -8,18 +8,14 @@
 
 import {config} from 'mikro/ota/config'
 import {
-  applyConfig,
   applyOffer,
   bearer,
-  configState,
   confirm,
-  parseConfig,
-  parseOffer,
+  decline,
   reconcile,
   registry,
   report,
   revert,
-  running,
   settle,
 } from 'native:mikro/ota_client'
 
@@ -27,17 +23,13 @@ import type {Ota} from './types.js'
 
 const ota: Ota = {
   reconcile,
-  running,
-  parseOffer,
   applyOffer,
   confirm,
   revert,
   bearer,
   registry,
   config,
-  parseConfig,
-  applyConfig,
-  configState,
+  decline,
   report,
   settle,
 }

package/runtime/ota/types.ts

@@ -6,7 +6,8 @@ import type {Result} from '../result/types.js'
 /** An update offered by a registry: what to fetch and how to verify it, nothing
  *  more. Whether this device should take it is the registry's decision, made
  *  against the firmware and bytecode version the device reports at check-in and
- *  the whole set of builds it holds. Validate untrusted input with `parseOffer`. */
+ *  the whole set of builds it holds. `settle()` validates the untrusted
+ *  response fields into one. */
 export interface Offer {
   /** https URL of the .tgz build */
   url: string
@@ -117,24 +118,6 @@ export type ApplyOutcome =
  *  mismatch code, since it cannot tell a bad hash from bad bytes. */
 export type OtaError = OtaWriteError | OtaBeginError | OtaInstallError | OtaDownloadError
 
-/** One stored config document: the complete effective config computed and
- *  validated by the registry (or by the CLI at cable-seed time), the opaque
- *  token that identifies it, and the release version it was computed for.
- *  The device stores and returns it without understanding it: validation is
- *  the writer's job, and the registry already ships the code. */
-export interface StoredConfig {
-  /** Opaque registry-issued token echoed as `configRev` on check-ins. The
-   *  registry serves its document whenever the echo differs from its own
-   *  current rev, so a document it does not recognize is replaced. */
-  rev?: string
-  /** The release version this document was computed for. A document stamped
-   *  for another version is ignored by `ota.config()`. */
-  version: string
-  /** The served document: the deviation overlay the read resolves over the
-   *  build's manifest defaults. */
-  doc?: unknown
-}
-
 /** The three config slots, mirroring the build's install slots: `current` is
  *  what the running build reads, `next` is staged with an offered build,
  *  `prev` is the rollback baseline while a trial is unresolved. */
@@ -166,28 +149,13 @@ export type ConfigWrite =
    *  included), or it was a clear with nothing to clear. */
   | 'unchanged'
   /** Nothing was written, and the reason is transient: the store could not
-   *  answer, or the running version could not be read. Keep echoing the rev
-   *  from `configState()` so the document is served again, rather than the rev
-   *  of the document that did not land. */
+   *  answer, or the running version could not be read. The next `report()`
+   *  still echoes the held rev, so the document is served again, rather than
+   *  the rev of the document that did not land. */
   | 'failed'
-  /** Not a usable config document. Validate with `parseConfig` first to find
-   *  out before the delivery, and log what the wire actually carried. */
+  /** Not a usable config document; log what the wire actually carried. */
   | 'invalid'
 
-/** What a check-in body owes the registry about config, for a client that
- *  builds its own. */
-export interface ConfigState {
-  /** The rev to send as `configRev`: the registry serves its document whenever
-   *  this differs from its own current rev. Absent when the device holds no
-   *  document. After a rolled-back trial this is the FAILED document's rev,
-   *  which is what stops the registry serving it again. */
-  rev?: string
-  /** A document that failed its trial and was rolled back, reported until it
-   *  is replaced. Send it as `configError`, or an operator has no way to see
-   *  that the document they published took the device down. */
-  error?: ConfigErrorReport
-}
-
 /** A config document rolled back after a failed trial; reported on check-ins
  *  while it stands. `rev` names the failed document, and the client keeps
  *  echoing it as `configRev`, which is what stops the registry re-serving
@@ -197,6 +165,19 @@ export interface ConfigErrorReport {
   message: string
 }
 
+/** Why the last offered build was not taken. Without it a registry that waits
+ *  for `running.checksum` to turn into the offered checksum cannot tell a
+ *  device still working through a download from one that has permanently
+ *  stopped trying. */
+export interface DeclineReport {
+  /** The declined build, 64 lowercase hex characters. */
+  checksum: string
+  /** A module outcome ({@link DeclineReason}) or the app's own word for a
+   *  reason only it can see, at most 64 characters. */
+  reason: DeclineReason | (string & {})
+  detail?: string
+}
+
 /** The check-in body a device owes its registry, as `ota.report()` builds it.
  *  Field shapes match the wire, so a client (or the proxy behind it) can
  *  forward fields verbatim into `POST /api/v1/checkin`. */
@@ -217,10 +198,17 @@ export interface CheckinReport {
   /** Why a previous install failed. Present after a `reconcile()` that found
    *  one, until a `settle()` marks it delivered. */
   lastInstall?: Diagnostic
-  /** The held document's rev to echo; see {@link ConfigState.rev}. */
+  /** The held document's rev to echo: the registry serves its document
+   *  whenever this differs from its own current rev. After a rolled-back
+   *  trial this is the FAILED document's rev, which is what stops the
+   *  registry serving it again. */
   configRev?: string
-  /** A rolled-back document to report; see {@link ConfigState.error}. */
+  /** A rolled-back document to report; see {@link ConfigErrorReport}. */
   configError?: ConfigErrorReport
+  /** Why the last offered build was not taken. Present after `applyOffer`
+   *  declined one or the app recorded its own via `decline()`, until a
+   *  `settle()` marks it delivered. */
+  lastDecline?: DeclineReport
 }
 
 /** What `ota.settle()` took from a completed check-in's response. */
@@ -260,15 +248,14 @@ export type RegisteredConfig = keyof OtaConfig extends never ? unknown : OtaConf
 export interface Ota {
   /** Report what happened to a previous update on this boot, and clear the report. */
   reconcile(): InstallOutcome
-  /** The build currently executing, read from the live app. */
-  running(): RunningBuild
-  /** Validate a registry value into an `Offer`, or `undefined` if unusable.
-   *  `allowInsecure` (dev only) accepts an http build url instead of https. */
-  parseOffer(raw: unknown, opts?: {allowInsecure?: boolean}): Offer | undefined
   /** Run the full update policy: skip checks and the retry limit, download
    *  via the `download` callback, and verification. Compatibility is not
    *  re-checked: the registry selected this build for the reported firmware,
-   *  and a mismatched archive fails its checksum or fails to load. */
+   *  and a mismatched archive fails its checksum or fails to load.
+   *
+   *  An offer it does not stage is recorded for the registry the way
+   *  `decline()` records one, except `'current'` and `'trial-pending'`,
+   *  which are not declines. */
   applyOffer(
     offer: Offer,
     download: DownloadFn,
@@ -318,50 +305,29 @@ export interface Ota {
    */
   config<T = RegisteredConfig>(): T
   /**
-   * Validate a config document a client received over its own transport, or
-   * `undefined` when it cannot be used. What `parseOffer` is to an offer.
-   *
-   * A usable document is an object with a non-empty `version` (the release it
-   * was computed for, which decides where `applyConfig` puts it), an optional
-   * `rev` short enough to echo intact, and a `doc` that is an object or absent.
-   * An absent `doc` is the clear, not a malformed document.
-   *
-   * Whether the document survives CBOR is settled by `applyConfig`, which is
-   * where the stored bytes are made.
-   */
-  parseConfig(raw: unknown): StoredConfig | undefined
-  /**
-   * Store a config document, for a client that received one over its own
-   * transport. The built-in client covers the ordinary case and does not go
-   * through here.
-   *
-   * The `version` stamp decides where it lands: stamped for the running
-   * release it is applied, and the document it replaces is kept as the
-   * rollback baseline; stamped for another it is staged for the build it
-   * names, to apply when that build installs. The return value says which
-   * happened, and says when nothing did.
+   * Record why an offered build was not taken, for the next `report()` to
+   * carry as `lastDecline` and a later `settle()` to mark delivered — the
+   * same lifecycle as `lastInstall`. `applyOffer` records its own outcomes,
+   * so this is for a reason only the app can see: its own download budget
+   * spent, a build its policy refuses. Without a recorded decline the
+   * registry cannot tell a device still working through a download from one
+   * that has stopped, and shows the update pending forever.
    *
-   * A delivery to the running release arms a trial. Each boot whose first
-   * `config()` read serves the document burns one of `trialBoots`, and the
-   * budget spent with no `confirm()` in between restores the previous
-   * document. On a wake-cycle device every wake is a boot, so raise
-   * `trialBoots` above the default when a check-in can plausibly fail a few
-   * cycles in a row.
-   */
-  applyConfig(config: StoredConfig, options?: {trialBoots?: number}): ConfigWrite
-  /**
-   * What the device owes its registry about config: the rev to echo, and a
-   * rolled-back document to report. A client that builds its own check-in body
-   * needs both. Without the echo the registry re-serves the same document on
-   * every check-in; without the report a document that took the device down is
-   * re-served forever and nobody is told.
+   * Persisted on the device, so it survives a deep sleep: on a wake-cycle
+   * device the decline always lands after that wake's check-in, and the next
+   * wake's `report()` is its first chance to travel. Recording again
+   * overwrites; only the last decline stands. Throws a `TypeError` on a
+   * checksum that is not 64 lowercase hex characters or a `reason` past 64
+   * characters, since the registry would reject the whole check-in body;
+   * `detail` is free text and is cut to 256 characters instead.
    */
-  configState(): ConfigState
+  decline(checksum: string, reason: DeclineReason | (string & {}), detail?: string): void
   /**
    * The check-in body the device owes its registry, assembled: identity,
-   * `running()`, the name pair, free storage, the pending `lastInstall`
-   * report, and what `configState()` resolves. One call instead of gathering
-   * the fields by hand, and the same facts the built-in client sends.
+   * the running build, the name pair, free storage, the pending `lastInstall`
+   * report, a recorded `lastDecline`, and the config echo. One
+   * call instead of gathering the fields by hand, and the same facts the
+   * built-in client sends.
    *
    * Call `reconcile()` first, on every boot: it is what surfaces the
    * `lastInstall` report this reads (`settle()` marks it delivered).
@@ -370,9 +336,12 @@ export interface Ota {
   /**
    * Take a COMPLETED check-in's response, whole: confirm the running trial
    * and a read config document's trial (exactly `confirm()`), adopt a
-   * delivered name pair, store a delivered config document (exactly
-   * `applyConfig`, with `trialBoots`), and validate the offer fields (exactly
-   * `parseOffer(raw)`, with `allowInsecure`). An empty or null response is
+   * delivered name pair, store a delivered config document, and validate the
+   * offer fields (`allowInsecure`, dev only, accepts an http build url). A
+   * stored document arms a trial of `trialBoots` boots: each boot whose first
+   * `config()` read serves it burns one, and the budget spent with no
+   * `confirm()` in between restores the previous document, so raise it above
+   * the default on a wake-cycle device. An empty or null response is
    * the registry's quiet round: nothing to deliver, and the confirm still
    * happens, which is the point of calling. A response of any other shape
    * never decoded: a captive portal handed back HTML, or a proxy sent an

package/runtime/watchdog/types.ts

@@ -0,0 +1,9 @@
+export interface Watchdog {
+  /** Report progress to the feed watchdog. Call it where real work completed,
+   *  not from a bare timer. A no-op when `watchdog.feed` is not configured. */
+  feed(): void
+}
+
+/** Progress reporting for the `feed` watchdog. The limits themselves are
+ *  set in `mikro.config.ts` under `watchdog`, not from code. */
+export declare const watchdog: Watchdog

package/runtime/watchdog/watchdog.ts

@@ -0,0 +1,7 @@
+import {feed} from 'native:mikro/watchdog'
+
+import type {Watchdog} from './types.js'
+
+export type {Watchdog} from './types.js'
+
+export const watchdog: Watchdog = {feed}

package/src/eval_bytecode.cpp

@@ -19,6 +19,7 @@ int mik__eval_bytecode(JSContext* ctx, const uint8_t* buf, size_t buf_len, bool
         }
     }
 
+    mik__blocking_begin(MIK_GetRuntime(ctx));
     JSValue val = JS_EvalFunction(ctx, obj);
     if (JS_IsException(val)) {
         mik_dump_error(ctx);

package/src/mik_app_config.cpp

@@ -1,5 +1,6 @@
 #include "mikrojs/mikrojs.h"
 
+#include <climits>
 #include <cstdio>
 #include <cstdlib>
 #include <cstring>
@@ -24,6 +25,9 @@ void MIK_DefaultConfig(MIKConfig* config) {
     config->log_dir[0] = '\0';
     config->log_max_size = 64 * 1024;
     config->log_flush = MIK_LOG_FLUSH_ERROR;
+    config->blocking_timeout_ms = MIK_WATCHDOG_BLOCKING_DEFAULT_MS;
+    config->feed_timeout_ms = 0;
+    config->awake_timeout_ms = 0;
 }
 
 /* Minimal JSON parser for config file — avoids cJSON dependency.
@@ -60,6 +64,34 @@ static bool mik__json_get_number(const char* json, const char* key, double* out)
     return true;
 }
 
+static bool mik__json_is_false(const char* json, const char* key) {
+    char pattern[128];
+    snprintf(pattern, sizeof(pattern), "\"%s\"", key);
+    const char* p = strstr(json, pattern);
+    if (!p) return false;
+    p += strlen(pattern);
+    while (*p == ' ' || *p == '\t' || *p == ':') p++;
+    return strncmp(p, "false", 5) == 0;
+}
+
+/* Watchdog budget in ms. `false` and 0 disable; other values below 1 s
+ * clamp up with a warning, since a smaller budget fires on ordinary work. */
+static int mik__json_get_watchdog_ms(const MIKPlatform* platform, const char* json,
+                                     const char* key, int current) {
+    if (mik__json_is_false(json, key)) return 0;
+    double num_val;
+    if (!mik__json_get_number(json, key, &num_val)) return current;
+    if (num_val == 0) return 0;
+    if (num_val < 1000) {
+        platform->log(MIK_LOG_WARN, TAG, "%s below 1000 ms (%ld); clamping to 1000", key,
+                      (long)num_val);
+        return 1000;
+    }
+    /* Past INT_MAX the cast would wrap negative and silently disable it. */
+    if (num_val > INT_MAX) return INT_MAX;
+    return (int)num_val;
+}
+
 /* Read a JSON file into a malloc'd buffer. Caller must free(). Returns NULL on failure. */
 static char* mik__read_json_file(const char* filepath, struct stat* st) {
     if (stat(filepath, st) != 0) return nullptr;
@@ -333,6 +365,12 @@ int MIK_LoadConfig(const char* base_path, MIKConfig* config) {
             if (mik__json_get_number(buf, "onPanic.duration", &num_val)) {
                 config->panic_sleep_duration_ms = (int)num_val;
             }
+            config->blocking_timeout_ms = mik__json_get_watchdog_ms(
+                platform, buf, "watchdog.blocking", config->blocking_timeout_ms);
+            config->feed_timeout_ms = mik__json_get_watchdog_ms(platform, buf, "watchdog.feed",
+                                                                config->feed_timeout_ms);
+            config->awake_timeout_ms = mik__json_get_watchdog_ms(
+                platform, buf, "watchdog.awake", config->awake_timeout_ms);
             if (mik__json_get_number(buf, "stackSize", &num_val)) {
                 config->stack_size = (size_t)num_val;
             }

package/src/mik_console.cpp

@@ -263,6 +263,11 @@ bool mik__report_uncaught(JSContext* ctx, JSValue exc, bool in_promise) {
         }
     }
 
+    /* A blocking-watchdog timeout reaches here either through mik_dump_error
+     * (which already reported it; this is then a no-op) or as an unhandled
+     * rejection when the interrupted turn was a module evaluation. */
+    mik__watchdog_report_blocking(MIK_GetRuntime(ctx));
+
     /* Fixed-size stack buffer so this function never allocates from the
      * C++ heap. Previously we used std::string + mik_inspect here; both
      * can throw std::bad_alloc under memory pressure, and with

package/src/mik_ota_policy.cpp

@@ -116,6 +116,40 @@ void MIKOtaStore::SetInFlight(bool in_flight) {
     env_->kv_set_i32(env_->opaque, "ota.inflight", in_flight ? 1 : 0);
 }
 
+bool MIKOtaStore::GetDecline(MIKOtaDeclineRecord* out) const {
+    if (!env_ || !env_->kv_get_str) return false;
+    if (!env_->kv_get_str(env_->opaque, "ota.declined", out->checksum, sizeof(out->checksum)) ||
+        out->checksum[0] == '\0') {
+        return false;
+    }
+    if (!env_->kv_get_str(env_->opaque, "ota.declReason", out->reason, sizeof(out->reason)) ||
+        out->reason[0] == '\0') {
+        return false;
+    }
+    if (!env_->kv_get_str(env_->opaque, "ota.declDetail", out->detail, sizeof(out->detail))) {
+        out->detail[0] = '\0';
+    }
+    return true;
+}
+
+void MIKOtaStore::SetDecline(const MIKOtaDeclineRecord& record) {
+    if (!env_ || !env_->kv_set_str) return;
+    env_->kv_set_str(env_->opaque, "ota.declined", record.checksum);
+    env_->kv_set_str(env_->opaque, "ota.declReason", record.reason);
+    if (record.detail[0]) {
+        env_->kv_set_str(env_->opaque, "ota.declDetail", record.detail);
+    } else if (env_->kv_remove) {
+        env_->kv_remove(env_->opaque, "ota.declDetail");
+    }
+}
+
+void MIKOtaStore::ClearDecline() {
+    if (!env_ || !env_->kv_remove) return;
+    env_->kv_remove(env_->opaque, "ota.declined");
+    env_->kv_remove(env_->opaque, "ota.declReason");
+    env_->kv_remove(env_->opaque, "ota.declDetail");
+}
+
 // ── Offer parsing ────────────────────────────────────────────────────────────
 
 bool mik__ota_parse_offer(const char* url, const char* checksum, int64_t size, bool allow_insecure,

package/src/mik_repl.cpp

@@ -119,8 +119,8 @@ void mik__repl_proto_send_output(uint8_t msg_type, const void* data, size_t len)
  * Returns false on transport EOF/error, when MIK_ProtocolExit() is
  * signalled from inside the pump (the supervisor's mechanism for ending
  * a test-file's serve loop after __testFileDone fires), or when MIK_Loop
- * reports the attached runtime has halted (e.g. an unhandled rejection
- * set stop_requested — a test that crashed mid-execution). */
+ * reports the attached runtime has halted without a panic grace window
+ * (e.g. an unhandled rejection in a test that crashed mid-execution). */
 bool mik__proto_read_exact(MIKReplTransport* transport, void* buf, size_t n) {
     const MIKPlatform* platform = MIK_GetPlatform();
     uint8_t* p = static_cast<uint8_t*>(buf);
@@ -133,11 +133,10 @@ bool mik__proto_read_exact(MIKReplTransport* transport, void* buf, size_t n) {
             return false;
         } else {
             if (repl_mik_rt && !repl_paused) {
-                if (MIK_Loop(repl_mik_rt) != 0) {
-                    /* Runtime halted (typically unhandled rejection sets
-                     * stop_requested). Further pumping is a no-op, so
-                     * exit the serve loop and let the caller swap in the
-                     * next runtime — or restart, in non-supervisor mode. */
+                /* A panic arms restart_at_us and MIK_Loop takes the action
+                 * itself at the deadline, so keep serving (--recover). Only
+                 * a plain stop (test supervisor) ends the serve loop. */
+                if (MIK_Loop(repl_mik_rt) != 0 && repl_mik_rt->restart_at_us == 0) {
                     s_exit_serve_loop = true;
                     return false;
                 }
@@ -611,6 +610,7 @@ static bool handle_directive_impl(JSContext* ctx, const char* line, std::string&
             out.append("App is already paused\n");
         } else {
             repl_paused = true;
+            mik__watchdog_pause_begin(repl_mik_rt);
             out.append("App paused (timers, callbacks suspended). Use /resume to continue.\n");
         }
         return true;
@@ -621,6 +621,7 @@ static bool handle_directive_impl(JSContext* ctx, const char* line, std::string&
             out.append("App is not paused\n");
         } else {
             repl_paused = false;
+            mik__watchdog_pause_end(repl_mik_rt);
             out.append("App resumed\n");
         }
         return true;
@@ -852,6 +853,13 @@ bool mik__repl_is_paused(void) {
 }
 
 void mik__repl_set_paused(bool paused) {
+    if (paused != repl_paused) {
+        if (paused) {
+            mik__watchdog_pause_begin(repl_mik_rt);
+        } else {
+            mik__watchdog_pause_end(repl_mik_rt);
+        }
+    }
     repl_paused = paused;
 }
 
@@ -1035,6 +1043,9 @@ void MIK_ProtocolClose(void) {
     }
     repl_active = false;
     repl_protocol_mode = false;
+    if (repl_paused) {
+        mik__watchdog_pause_end(repl_mik_rt);
+    }
     repl_paused = false;
     repl_transport = nullptr;
     repl_ctx = nullptr;
@@ -1082,6 +1093,7 @@ void MIK_ProtocolServeLoop(void) {
 
                 repl_evaluating = true;
                 repl_async_skipped = false;
+                mik__blocking_begin(repl_mik_rt);
                 JSValue result = repl_eval_and_pump(ctx, code.c_str(), code.size());
                 repl_evaluating = false;
 
@@ -1094,6 +1106,10 @@ void MIK_ProtocolServeLoop(void) {
                 if (JS_IsException(result)) {
                     JSValue exc = JS_GetException(ctx);
 
+                    /* A synchronous throw never reaches mik_dump_error, so
+                     * consume the blocking-timeout flag here. */
+                    mik__watchdog_report_blocking(repl_mik_rt);
+
                     /* Format the error */
                     std::string msg = "Uncaught ";
                     if (JS_IsObject(exc)) {

package/src/mik_watchdog.cpp

@@ -0,0 +1,170 @@
+#include <quickjs.h>
+
+#include "mikrojs/mikrojs.h"
+#include "mikrojs/platform.h"
+#include "mikrojs/private.h"
+#include "mikrojs/utils.h"
+
+/* ── Watchdog: blocking deadline, feed deadline, awake budget ─────────
+ *
+ * All three measure wall time via get_boot_us(). The blocking deadline is
+ * polled from the QuickJS interrupt handler (every 10k branches/calls);
+ * feed and awake are checked once per MIK_Loop pass. State is per-runtime,
+ * so the Node addon's parallel runtimes need no atomics. */
+
+
+void mik__blocking_begin(MIKRuntime* mik_rt) {
+    if (!mik_rt) return;
+    mik_rt->blocking_start_us = 0;
+    mik_rt->blocking_armed = true;
+}
+
+int mik__watchdog_interrupt(JSRuntime* rt, void* opaque) {
+    (void)rt;
+    MIKRuntime* mik_rt = static_cast<MIKRuntime*>(opaque);
+    int budget_ms = mik_rt->config.blocking_timeout_ms;
+    if (budget_ms <= 0 || !mik_rt->blocking_armed) {
+        return 0;
+    }
+    int64_t now = MIK_GetPlatform()->get_boot_us();
+    int64_t start = mik_rt->blocking_start_us;
+    /* now < start: the boot clock reset (deep sleep, test platform swap). */
+    if (start == 0 || now < start) {
+        mik_rt->blocking_start_us = now;
+        return 0;
+    }
+    if (now - start >= (int64_t)budget_ms * 1000) {
+        /* One-shot: stay off while the error unwinds so finally blocks
+         * and error-handler property reads are not interrupted too. */
+        mik_rt->blocking_armed = false;
+        mik_rt->blocking_tripped = true;
+        /* The app could not feed while it was blocked; give it a fresh
+         * window so a surviving session (REPL eval) is not hit twice. */
+        mik_rt->feed_last_us = now;
+        return 1;
+    }
+    return 0;
+}
+
+bool mik__watchdog_report_blocking(MIKRuntime* mik_rt) {
+    if (!mik_rt || !mik_rt->blocking_tripped) {
+        return false;
+    }
+    mik_rt->blocking_tripped = false;
+    mik__print_error_line("[watchdog] WATCHDOG TRIGGERED: event loop blocking time exceeded "
+                          "configured limit of %d ms",
+                          mik_rt->config.blocking_timeout_ms);
+    return true;
+}
+
+void mik__watchdog_arm(MIKRuntime* mik_rt) {
+    const MIKPlatform* platform = MIK_GetPlatform();
+    const MIKConfig* cfg = &mik_rt->config;
+    mik__blocking_begin(mik_rt);
+    mik_rt->feed_armed = cfg->feed_timeout_ms > 0;
+    mik_rt->feed_last_us = platform->get_boot_us();
+    mik_rt->awake_armed = cfg->awake_timeout_ms > 0;
+    mik_rt->awake_pause_offset_us = 0;
+    mik_rt->pause_start_us = 0;
+    if (mik_rt->awake_armed && cfg->panic_mode != MIK_PANIC_DEEP_SLEEP) {
+        /* Always visible: platform->log is silent on device by default. */
+        mik__print_error_line("[watchdog] awake limit of %d ms without onPanic.mode 'deepSleep': "
+                              "the device restarts every %d ms",
+                              cfg->awake_timeout_ms, cfg->awake_timeout_ms);
+    }
+}
+
+void mik__watchdog_check(MIKRuntime* mik_rt) {
+    if (mik_rt->stop_requested || (!mik_rt->feed_armed && !mik_rt->awake_armed)) {
+        return;
+    }
+    /* A pending exception (a blocking timeout, or any uncaught throw from the
+     * entry) is about to be reported and stop the runtime. Firing feed or
+     * awake on top of it would replace that exception and lose its trace. */
+    if (JS_HasException(mik_rt->ctx)) {
+        return;
+    }
+    const MIKPlatform* platform = MIK_GetPlatform();
+    int64_t now = platform->get_boot_us();
+
+    if (mik_rt->awake_armed) {
+        int64_t elapsed_us = now - mik_rt->awake_pause_offset_us;
+        if (elapsed_us >= (int64_t)mik_rt->config.awake_timeout_ms * 1000) {
+            mik_rt->awake_armed = false;
+            mik__print_error_line("[watchdog] WATCHDOG TRIGGERED: awake time exceeded configured "
+                                  "limit of %d ms",
+                                  mik_rt->config.awake_timeout_ms);
+            /* No JS error: nothing to point a trace at, and this must not
+             * reach the OTA trial error handler (a slow link is not a bug). */
+            MIK_Stop(mik_rt);
+            return;
+        }
+    }
+
+    if (mik_rt->feed_armed) {
+        if (now < mik_rt->feed_last_us) {
+            mik_rt->feed_last_us = now;
+        } else if (now - mik_rt->feed_last_us >= (int64_t)mik_rt->config.feed_timeout_ms * 1000) {
+            mik_rt->feed_armed = false;
+            mik__print_error_line("[watchdog] WATCHDOG TRIGGERED: time since last feed() exceeded "
+                                  "configured limit of %d ms",
+                                  mik_rt->config.feed_timeout_ms);
+            /* No JS frame is active here, so uncatchable marking is moot: the
+             * JS_HasException branch in MIK_Loop routes this before any user
+             * code runs. */
+            JS_ThrowInternalError(mik_rt->ctx,
+                                  "watchdog: time since last feed() exceeded configured limit "
+                                  "of %d ms",
+                                  mik_rt->config.feed_timeout_ms);
+        }
+    }
+}
+
+void mik__watchdog_wake(MIKRuntime* mik_rt) {
+    if (!mik_rt) return;
+    mik__blocking_begin(mik_rt);
+    /* The app could not feed while asleep; it gets a fresh window, as after
+     * a pause. The awake clock keeps counting: light sleep is still uptime. */
+    mik_rt->feed_last_us = MIK_GetPlatform()->get_boot_us();
+}
+
+void mik__watchdog_pause_begin(MIKRuntime* mik_rt) {
+    if (!mik_rt || mik_rt->pause_start_us != 0) return;
+    mik_rt->pause_start_us = MIK_GetPlatform()->get_boot_us();
+}
+
+void mik__watchdog_pause_end(MIKRuntime* mik_rt) {
+    if (!mik_rt || mik_rt->pause_start_us == 0) return;
+    int64_t now = MIK_GetPlatform()->get_boot_us();
+    if (now > mik_rt->pause_start_us) {
+        mik_rt->awake_pause_offset_us += now - mik_rt->pause_start_us;
+    }
+    mik_rt->pause_start_us = 0;
+    /* The app could not feed while suspended; it gets a fresh budget. */
+    mik_rt->feed_last_us = now;
+}
+
+/* ── native:mikro/watchdog ──────────────────────────────────────────── */
+
+static JSValue mik__watchdog_feed(JSContext* ctx, JSValueConst this_val, int argc,
+                                  JSValueConst* argv) {
+    (void)this_val;
+    (void)argc;
+    (void)argv;
+    MIKRuntime* mik_rt = MIK_GetRuntime(ctx);
+    if (mik_rt && mik_rt->feed_armed) {
+        mik_rt->feed_last_us = MIK_GetPlatform()->get_boot_us();
+    }
+    return JS_UNDEFINED;
+}
+
+static int mik__watchdog_module_init(JSContext* ctx, JSModuleDef* m) {
+    JS_SetModuleExport(ctx, m, "feed", JS_NewCFunction(ctx, mik__watchdog_feed, "feed", 0));
+    return 0;
+}
+
+void mik__watchdog_init(JSContext* ctx) {
+    JSModuleDef* m = JS_NewCModule(ctx, "native:mikro/watchdog", mik__watchdog_module_init);
+    if (!m) return;
+    JS_AddModuleExport(ctx, m, "feed");
+}

package/src/mikrojs.cpp

@@ -262,6 +262,9 @@ MIKRuntime* MIK_NewRuntimeInternal(MIKRunOptions* options) {
 
     memcpy(&mik_rt->options, options, sizeof(*options));
     MIK_DefaultConfig(&mik_rt->config);
+    /* Runtimes that never see MIK_SetConfig (host tests, the Node addon)
+     * still get the default blocking budget. */
+    mik__watchdog_arm(mik_rt);
 
     /* Switch the QuickJS heap to PSRAM before constructing the runtime,
      * so JS_NewRuntime2 and every subsequent QuickJS allocation lands
@@ -346,6 +349,9 @@ MIKRuntime* MIK_NewRuntimeInternal(MIKRunOptions* options) {
     /* unhandled promise rejection tracker */
     JS_SetHostPromiseRejectionTracker(rt, mik__promise_rejection_tracker, NULL);
 
+    /* Blocking watchdog: polled every 10k branches/calls. */
+    JS_SetInterruptHandler(rt, mik__watchdog_interrupt, mik_rt);
+
     /* Register internal C modules */
     JSModuleDef* sys_mod = JS_NewCModule(ctx, "native:mikro/sys", mik__sys_module_init);
     CHECK_NOT_NULL(sys_mod);
@@ -360,6 +366,7 @@ MIKRuntime* MIK_NewRuntimeInternal(MIKRunOptions* options) {
     mik__result_init(ctx);
     mik__cbor_init(ctx);
     mik__udp_init(ctx);
+    mik__watchdog_init(ctx);
     mik__observable_init(ctx);
 
     /* Native mikrojs modules (replace bytecode builtins). The http client
@@ -666,13 +673,21 @@ void mik__execute_jobs(JSContext* ctx) {
 
 /* main loop which calls the user JS callbacks */
 int MIK_Loop(MIKRuntime* mik_rt) {
+    const MIKPlatform* platform = MIK_GetPlatform();
+    /* Feed the hardware watchdog before the grace-window return below, so
+     * a long onPanic.delay never counts against it. */
+    if (platform->feed_watchdog) {
+        platform->feed_watchdog();
+    }
+    /* One blocking budget per pass, not per job: a fresh budget per job
+     * would let `while (true) await 0` spin forever unnoticed. */
+    mik__blocking_begin(mik_rt);
     /* Deferred restart (see MIK_Stop): once the grace window elapses, reboot
      * the device. While we're still in the window, return 0 without pumping
      * timers/consumers so the protocol serve loop keeps reading host
      * commands without firing any more user JS on the dead runtime. The
      * serve loop also skips its microtask drain on this condition. */
     if (mik_rt->restart_at_us > 0) {
-        const MIKPlatform* platform = MIK_GetPlatform();
         if (platform->get_boot_us() >= mik_rt->restart_at_us) {
             /* The grace window has elapsed; take the configured panic action.
              * In deep-sleep mode the timer wake reboots the chip, so the wake
@@ -680,12 +695,18 @@ int MIK_Loop(MIKRuntime* mik_rt) {
              * design (the CPU is suspended). If the platform has no deep-sleep
              * hook (hosts), fall through to a plain restart. */
             if (mik_rt->config.panic_mode == MIK_PANIC_DEEP_SLEEP && platform->deep_sleep_us) {
+                mik__print_error_line("[panic] deep-sleeping for %d ms",
+                                      mik_rt->config.panic_sleep_duration_ms);
                 platform->deep_sleep_us((uint64_t)mik_rt->config.panic_sleep_duration_ms * 1000);
             }
+            mik__print_error_line("[panic] restarting");
             platform->restart();
         }
         return 0;
     }
+    /* Feed/awake deadlines: a feed miss lands in the exception branch below,
+     * an awake overrun in the stop_requested one. */
+    mik__watchdog_check(mik_rt);
     if (mik_rt->stop_requested) {
         return 1;
     }
@@ -730,6 +751,7 @@ void MIK_SetConfig(MIKRuntime* mik_rt, const MIKConfig* config) {
     if (config->fs_read_max > 0) {
         mik_rt->fs_read_max = config->fs_read_max;
     }
+    mik__watchdog_arm(mik_rt);
 }
 
 /* Record a profile entry for the entry module loaded via MIK_EvalModule.
@@ -850,6 +872,15 @@ void MIK_Stop(MIKRuntime* mik_rt) {
         const MIKPlatform* platform = MIK_GetPlatform();
         mik_rt->restart_at_us =
             platform->get_boot_us() + (int64_t)mik_rt->config.panic_restart_delay_ms * 1000;
+        /* Say what comes next: with deep sleep the device goes silent. */
+        if (mik_rt->config.panic_mode == MIK_PANIC_DEEP_SLEEP && platform->deep_sleep_us) {
+            mik__print_error_line("[panic] deep-sleeping for %d ms in %d ms",
+                                  mik_rt->config.panic_sleep_duration_ms,
+                                  mik_rt->config.panic_restart_delay_ms);
+        } else {
+            mik__print_error_line("[panic] restarting in %d ms",
+                                  mik_rt->config.panic_restart_delay_ms);
+        }
     }
 }
 
@@ -974,6 +1005,7 @@ JSValue MIK_EvalModuleContent(JSContext* ctx, const char* filename, const char*
     const char* eval_src = pp_source ? pp_source : content;
     size_t eval_len = pp_source ? pp_len : len;
 
+    mik__blocking_begin(mik_rt);
     /* Compile then run to be able to set import.meta */
     JSValue ret =
         JS_Eval(ctx, eval_src, eval_len, filename, JS_EVAL_TYPE_MODULE | JS_EVAL_FLAG_COMPILE_ONLY);
@@ -987,6 +1019,7 @@ JSValue MIK_EvalModuleContent(JSContext* ctx, const char* filename, const char*
 }
 
 JSValue MIK_EvalScriptContent(JSContext* ctx, const char* content, size_t len) {
+    mik__blocking_begin(MIK_GetRuntime(ctx));
     return JS_Eval(ctx, content, len, "<eval>", JS_EVAL_TYPE_GLOBAL);
 }
 
@@ -1009,6 +1042,7 @@ JSValue MIK_EvalScript(JSContext* ctx, const char* filename) {
     /* Add null termination, required by JS_Eval. */
     dbuf_putc(&dbuf, '\0');
 
+    mik__blocking_begin(MIK_GetRuntime(ctx));
     ret = JS_Eval(ctx, (char*)dbuf.buf, dbuf_size - 1, filename, JS_EVAL_TYPE_GLOBAL);
 
     dbuf_free(&dbuf);
@@ -1054,6 +1088,7 @@ JSValue MIK_EvalModule(JSContext* ctx, const char* filename, bool is_main) {
     dbuf_size = dbuf.size;
 
     MIKRuntime* mik_rt = MIK_GetRuntime(ctx);
+    mik__blocking_begin(mik_rt);
     bool profile = mik_rt != nullptr && mik_rt->profile_enabled;
     int64_t malloc_before = 0;
     size_t entries_before = 0;

package/src/utils.cpp

@@ -7,6 +7,7 @@
 #include <string.h>
 
 #include "mikrojs/mikrojs.h"
+#include "mikrojs/platform.h"
 #include "mikrojs/private.h"
 
 JSValue mik_new_error(JSContext* ctx, int err) {
@@ -38,7 +39,27 @@ static void mik_dump_obj(JSContext* ctx, FILE* f, JSValue val) {
     }
 }
 
+void mik__print_error_line(const char* fmt, ...) {
+    char buf[256];
+    va_list args;
+    va_start(args, fmt);
+    int n = vsnprintf(buf, sizeof(buf) - 2, fmt, args);
+    va_end(args);
+    if (n < 0) return;
+    size_t len = (size_t)n;
+    /* vsnprintf wrote at most sizeof(buf) - 3 chars plus a NUL. */
+    if (len > sizeof(buf) - 3) len = sizeof(buf) - 3;
+    if (mik__repl_is_protocol_mode()) {
+        mik__repl_proto_send_output(MIK_MSG_ERROR, buf, len);
+        return;
+    }
+    buf[len++] = '\r';
+    buf[len++] = '\n';
+    MIK_GetPlatform()->stderr_write(buf, len);
+}
+
 void mik_dump_error(JSContext* ctx) {
+    mik__watchdog_report_blocking(MIK_GetRuntime(ctx));
     JSValue exception_val = JS_GetException(ctx);
     mik_dump_error1(ctx, exception_val);
     JS_FreeValue(ctx, exception_val);