@mikrojs/native 0.6.1 → 0.7.0

package/runtime/result/result.ts

@@ -7,20 +7,19 @@ export class PanicError extends Error {
   }
 }
 
-export function defineError<D extends Record<string, (...args: any[]) => Record<string, unknown>>>(
-  _name: string,
-  variants: D,
-): {[K in keyof D & string]: (...args: Parameters<D[K]>) => {name: K} & ReturnType<D[K]>} {
-  const constructors: Record<string, (...args: unknown[]) => Record<string, unknown>> = {}
-  for (const key in variants) {
-    const factory = variants[key]!
-    constructors[key] = (...args: unknown[]) => {
-      const fields = (factory as (...a: unknown[]) => Record<string, unknown>)(...args)
-      fields.name = key
-      return fields
-    }
-  }
-  return constructors as unknown as {
-    [K in keyof D & string]: (...args: Parameters<D[K]>) => {name: K} & ReturnType<D[K]>
+export function matchError<E extends {name: string}, R>(
+  error: E,
+  handlers: {[K in E['name']]: (error: Extract<E, {name: K}>) => R},
+): R {
+  // hasOwn guard: bare `handlers[error.name]` would resolve to Object.prototype
+  // methods (toString, hasOwnProperty, …) for any error.name string that
+  // happens to match a prototype member — silently returning a wrong value
+  // instead of failing loudly. The type system enforces `name` is one of the
+  // union's tags, but interop with native or hand-built error objects can
+  // bypass that.
+  const h = handlers as unknown as Record<string, (e: E) => R>
+  if (!Object.hasOwn(h, error.name)) {
+    throw new TypeError(`matchError: no handler for ${error.name}`)
   }
+  return h[error.name]!(error)
 }

package/runtime/result/types.ts

@@ -37,20 +37,10 @@ export declare function ok<T>(value: T): OkResult<T>
 
 export declare function err<E>(error: E): ErrResult<E>
 
-type VariantDef = Record<string, (...args: any[]) => Record<string, unknown>>
-
-type ErrorConstructors<D extends VariantDef> = {
-  [K in keyof D & string]: (...args: Parameters<D[K]>) => {name: K} & ReturnType<D[K]>
-}
-
-export type ErrorOf<T extends Record<string, (...args: any[]) => any>> = {
-  [K in keyof T & string]: ReturnType<T[K]>
-}[keyof T & string]
-
-export declare function defineError<D extends VariantDef>(
-  name: string,
-  variants: D,
-): ErrorConstructors<D>
+export declare function matchError<E extends {name: string}, R>(
+  error: E,
+  handlers: {[K in E['name']]: (error: Extract<E, {name: K}>) => R},
+): R
 
 /** Raw error shape returned by native mik__result_err(). */
 export interface NativeError {

package/runtime/schema/schema.ts

@@ -1,10 +1,11 @@
-import {defineError, err, ok} from 'mikrojs/result'
+import {err, ok} from 'mikrojs/result'
 
 import type {Result} from '../result/types.js'
 
-export const SchemaError = defineError('SchemaError', {
-  ValidationFailed: (message: string, path: string) => ({message, path}),
-})
+export const SchemaError = {
+  ValidationFailed: (message: string, path: string) =>
+    ({name: 'ValidationFailed', message, path}) as const,
+}
 export type SchemaError = ReturnType<typeof SchemaError.ValidationFailed>
 
 // ── Schema types ────────────────────────────────────────────────────

package/runtime/stream/stream.ts

@@ -1,24 +1,37 @@
 /**
  * Minimal composable stream primitives for mikrojs.
  *
- * Streams are plain `AsyncIterable<T>` — no class hierarchy, no
- * lockable readers, no BYOB, no queueing strategies. Transforms are
- * async generator functions. Composition is function call.
+ * Streams are `AsyncIterable<Result<T, E>>` — Result-yielding rather
+ * than throwing — so error handling composes uniformly with the rest
+ * of the runtime's Result-based APIs. Combinators short-circuit on the
+ * first err item: they yield the err and return.
  *
- * This is deliberately a subset of what Snell's "new-streams" proposal
- * covers, adapted for the realities of QuickJS on a microcontroller:
- * no fast-path promise optimizations, no sendfile-style native
- * shortcuts, tight heap budget.
+ * Combinators that originate their own errors (`withTimeout`,
+ * `collectUntil`) widen the result's error type with a `StreamError`
+ * variant defined in `./types.ts`.
  *
  * V1 scope: enough to rewrite a modem AT channel as a one-file shim.
  * Expand only when a second call site asks for it.
  */
 
+import {err, ok} from 'mikrojs/result'
+
+import type {Result} from '../result/types.js'
+
 /** Decode a stream of UTF-8 byte chunks into a stream of strings. */
-export async function* decodeUtf8(source: AsyncIterable<Uint8Array>): AsyncIterable<string> {
+export async function* decodeUtf8<E>(
+  source: AsyncIterable<Result<Uint8Array, E>>,
+): AsyncIterable<Result<string, E>> {
   const decoder = new TextDecoder()
-  for await (const chunk of source) yield decoder.decode(chunk, {stream: true})
-  yield decoder.decode()
+  for await (const r of source) {
+    if (!r.ok) {
+      yield r
+      return
+    }
+    yield ok(decoder.decode(r.value, {stream: true}))
+  }
+  const final = decoder.decode()
+  if (final.length > 0) yield ok(final)
 }
 
 /**
@@ -36,10 +49,10 @@ export async function* decodeUtf8(source: AsyncIterable<Uint8Array>): AsyncItera
  * for protocols that use a blank line as a separator, e.g. HTTP
  * headers vs. body.
  */
-export async function* splitLines(
-  source: AsyncIterable<string>,
+export async function* splitLines<E>(
+  source: AsyncIterable<Result<string, E>>,
   delimiter: string = '\n',
-): AsyncIterable<string> {
+): AsyncIterable<Result<string, E>> {
   // indexOf('') returns 0 unconditionally, which would make the inner
   // loop spin forever yielding empty strings. Reject at entry instead
   // of hanging the event loop on a user mistake.
@@ -47,16 +60,20 @@ export async function* splitLines(
     throw new RangeError('splitLines: delimiter must be non-empty')
   }
   let buffer = ''
-  for await (const chunk of source) {
-    buffer += chunk
+  for await (const r of source) {
+    if (!r.ok) {
+      yield r
+      return
+    }
+    buffer += r.value
     let idx = buffer.indexOf(delimiter)
     while (idx !== -1) {
-      yield buffer.slice(0, idx)
+      yield ok(buffer.slice(0, idx))
       buffer = buffer.slice(idx + delimiter.length)
       idx = buffer.indexOf(delimiter)
     }
   }
-  if (buffer.length > 0) yield buffer
+  if (buffer.length > 0) yield ok(buffer)
 }
 
 /**
@@ -68,34 +85,30 @@ export async function* splitLines(
  * like modem AT commands where the terminator (`OK`/`ERROR`) is
  * semantically different from the response body lines in between.
  *
- * If the stream closes before any item matches, throws `StreamClosed`
- * (a plain Error with a `.name`). Callers should wrap this in their
- * own Result type if they want structured error handling.
+ * If the stream closes before any item matches, returns
+ * `err({name: 'StreamClosed'})`. Source errors propagate unchanged.
  */
-export async function collectUntil<T>(
-  source: AsyncIterable<T>,
+export async function collectUntil<T, E>(
+  source: AsyncIterable<Result<T, E>>,
   predicate: (item: T) => boolean,
-): Promise<{matched: T; collected: T[]}> {
+): Promise<Result<{matched: T; collected: T[]}, E | {name: 'StreamClosed'}>> {
   const collected: T[] = []
-  for await (const item of source) {
-    if (predicate(item)) {
-      return {matched: item, collected}
-    }
-    collected.push(item)
+  for await (const r of source) {
+    if (!r.ok) return r
+    if (predicate(r.value)) return ok({matched: r.value, collected})
+    collected.push(r.value)
   }
-  const err = new Error('Stream closed before predicate matched')
-  err.name = 'StreamClosed'
-  throw err
+  return err({name: 'StreamClosed' as const})
 }
 
 /**
  * Wrap an async iterable with a total-duration timeout.
  *
  * The deadline starts when this function is called (not per-item).
- * If the next item doesn't arrive before the deadline, the returned
- * iterable throws a `TimeoutError`, and cleans up the upstream source
- * by calling its `return()` method. Callers using `for await` will see
- * the error propagate out of the loop.
+ * If the next item doesn't arrive before the deadline, yields
+ * `err({name: 'Timeout', ms})` and ends, cleaning up the upstream
+ * source by calling its `return()` method. Source errors propagate
+ * unchanged.
  *
  * Implementation notes:
  * - Promise.race with setTimeout would leak orphaned timers on the
@@ -105,29 +118,39 @@ export async function collectUntil<T>(
  * - The upstream iterator is explicitly .return()'d on exit (normal,
  *   timeout, or consumer break) so underlying resources (UART claims,
  *   socket handles, ring buffers) get released.
+ *
+ * Source contract: the source iterator must surface failures via
+ * `yield err(...)` items, not by rejecting `next()`. On a timer win,
+ * the in-flight `next()` promise is discarded; if that promise
+ * rejects, the rejection is unhandled. Every Result-yielding source
+ * in this codebase (`uart.read()`, `fs.readStream`, `Response.body`)
+ * satisfies that contract — only relevant if you compose
+ * `withTimeout` over a hand-rolled iterator.
  */
-export async function* withTimeout<T>(source: AsyncIterable<T>, ms: number): AsyncIterable<T> {
+export async function* withTimeout<T, E>(
+  source: AsyncIterable<Result<T, E>>,
+  ms: number,
+): AsyncIterable<Result<T, E | {name: 'Timeout'; ms: number}>> {
   const deadline = Date.now() + ms
   const iter = source[Symbol.asyncIterator]()
   try {
     while (true) {
       const remaining = deadline - Date.now()
       if (remaining <= 0) {
-        const err = new Error(`Stream did not complete within ${ms}ms`)
-        err.name = 'TimeoutError'
-        throw err
+        yield err({name: 'Timeout' as const, ms})
+        return
       }
 
       let timerId: ReturnType<typeof setTimeout> | undefined
-      let result: IteratorResult<T, unknown>
+      let result: IteratorResult<Result<T, E>, unknown>
+      let timedOut = false
       try {
         result = await Promise.race([
           iter.next(),
-          new Promise<IteratorResult<T, unknown>>((_, reject) => {
+          new Promise<IteratorResult<Result<T, E>, unknown>>((resolve) => {
             timerId = setTimeout(() => {
-              const err = new Error(`Stream did not complete within ${ms}ms`)
-              err.name = 'TimeoutError'
-              reject(err)
+              timedOut = true
+              resolve({done: true, value: undefined})
             }, remaining)
           }),
         ])
@@ -135,8 +158,13 @@ export async function* withTimeout<T>(source: AsyncIterable<T>, ms: number): Asy
         if (timerId !== undefined) clearTimeout(timerId)
       }
 
+      if (timedOut) {
+        yield err({name: 'Timeout' as const, ms})
+        return
+      }
       if (result.done) return
-      yield result.value as T
+      yield result.value
+      if (!result.value.ok) return
     }
   } finally {
     if (typeof iter.return === 'function') {

package/runtime/stream/types.ts

@@ -5,42 +5,62 @@
  * bytecode at firmware build time. This file is the declaration-only
  * surface consumed by the `mikrojs/stream` re-export in
  * `packages/mikrojs` and by user apps via their tsconfig.
+ *
+ * Streaming sources yield `Result<T, E>` rather than throwing — see
+ * the design note in `stream.ts`. Combinators that originate their own
+ * errors widen the error type with a `StreamError` variant.
  */
 
+import type {Result} from 'mikrojs/result'
+
+export type StreamError = {name: 'Timeout'; ms: number} | {name: 'StreamClosed'}
+
 /** Decode a stream of UTF-8 byte chunks into a stream of strings. */
-export declare function decodeUtf8(source: AsyncIterable<Uint8Array>): AsyncIterable<string>
+export declare function decodeUtf8<E>(
+  source: AsyncIterable<Result<Uint8Array, E>>,
+): AsyncIterable<Result<string, E>>
 
 /**
  * Split a stream of text into a stream of lines on the given delimiter
  * (default `\n`). Partial lines spanning chunk boundaries are buffered
  * and reassembled. Empty lines between consecutive delimiters are
- * preserved. Throws `RangeError` if called with an empty delimiter.
+ * preserved. Throws `RangeError` if called with an empty delimiter
+ * (programmer error, not a stream error).
  */
-export declare function splitLines(
-  source: AsyncIterable<string>,
+export declare function splitLines<E>(
+  source: AsyncIterable<Result<string, E>>,
   delimiter?: string,
-): AsyncIterable<string>
+): AsyncIterable<Result<string, E>>
 
 /**
  * Consume a stream until an item matches `predicate`, then stop.
  *
- * Returns `{matched, collected}` where `collected` is every item that
- * came BEFORE the match (not including the matching item). Throws an
- * Error with `name === 'StreamClosed'` if the stream ends before any
- * item matches.
+ * Returns `ok({matched, collected})` where `collected` is every item
+ * that came BEFORE the match (not including the matching item).
+ * Returns `err({name: 'StreamClosed'})` if the stream ends before any
+ * item matches. Propagates the source's error variants unchanged.
  */
-export declare function collectUntil<T>(
-  source: AsyncIterable<T>,
+export declare function collectUntil<T, E>(
+  source: AsyncIterable<Result<T, E>>,
   predicate: (item: T) => boolean,
-): Promise<{matched: T; collected: T[]}>
+): Promise<Result<{matched: T; collected: T[]}, E | Extract<StreamError, {name: 'StreamClosed'}>>>
 
 /**
- * Wrap an async iterable with a total-duration deadline. Throws an
- * Error with `name === 'TimeoutError'` if the next item doesn't
- * arrive in time. Releases the upstream iterator via `return()` on
- * timeout, error, or consumer break.
+ * Wrap an async iterable with a total-duration deadline. Yields
+ * `err({name: 'Timeout', ms})` if the next item doesn't arrive in
+ * time, then ends. Releases the upstream iterator via `return()` on
+ * timeout, source error, or consumer break.
+ *
+ * Source contract: the source must surface failures via `yield err(...)`,
+ * not by rejecting `next()`. On a timer win the in-flight `next()`
+ * promise is discarded — if it later rejects, the rejection is
+ * unhandled. All Result-yielding sources in this runtime
+ * (`uart.read()`, `fs.readStream`, `Response.body`) satisfy that.
  */
-export declare function withTimeout<T>(source: AsyncIterable<T>, ms: number): AsyncIterable<T>
+export declare function withTimeout<T, E>(
+  source: AsyncIterable<Result<T, E>>,
+  ms: number,
+): AsyncIterable<Result<T, E | Extract<StreamError, {name: 'Timeout'}>>>
 
 /* BufferedReader lives in the sibling `mikrojs/reader` module — see
  * `runtime/reader/` — so apps that only need byte-level framing can

package/runtime/uart/types.ts

@@ -53,7 +53,13 @@ export interface UartTx {
  * @public
  */
 export interface UartRx {
-  read(): Result<AsyncIterable<Uint8Array>, UartError>
+  /**
+   * Open a Result-yielding async iterable of received chunks. Mid-stream
+   * failures (driver fault, port closed mid-iteration) arrive as a single
+   * terminal `err(UartError)` item rather than throwing — composes with
+   * stream/* combinators and other Result-based APIs.
+   */
+  read(): Result<AsyncIterable<Result<Uint8Array, UartError>>, UartError>
 }
 
 /**

package/runtime/uart/uart.ts

@@ -36,14 +36,15 @@ export class Uart implements UartBase {
     return this.#native.write(data)
   }
 
-  read(): Result<AsyncIterable<Uint8Array>, UartError> {
+  read(): Result<AsyncIterable<Result<Uint8Array, UartError>>, UartError> {
     const result = this.#native.read()
     if (!result.ok) return result
     const nativeIter = result.value
-    // Wrap the native iterator object (which has next/return) into a proper AsyncIterable
-    const iterable: AsyncIterable<Uint8Array> = {
+    // Wrap the native iterator object (which has next/return) into a proper AsyncIterable.
+    // Native yields Result items directly via mik__result_ok / mik__result_err_tag.
+    const iterable: AsyncIterable<Result<Uint8Array, UartError>> = {
       [Symbol.asyncIterator]() {
-        return nativeIter as AsyncIterator<Uint8Array>
+        return nativeIter as AsyncIterator<Result<Uint8Array, UartError>>
       },
     }
     return ok(iterable)

package/src/mik_app_config.cpp

@@ -12,30 +12,20 @@
 static const char* TAG = "mik_app_config";
 
 void MIK_DefaultConfig(MIKConfig* config) {
-    config->restart_on_uncaught_exception = false;
-    config->restart_delay_ms = 1000;
+    config->panic_restart_delay_ms = 1000;
     config->stack_size = 0;
     config->mem_reserved = 64 * 1024;
     config->fs_read_max = 0; /* 0 = runtime default (65536) */
     config->entry_point[0] = '\0';
     config->wifi_country[0] = '\0';
     config->wifi_hostname[0] = '\0';
+    config->log_dir[0] = '\0';
+    config->log_max_size = 64 * 1024;
+    config->log_flush = MIK_LOG_FLUSH_ERROR;
 }
 
 /* Minimal JSON parser for config file — avoids cJSON dependency.
- * Only handles the flat object with bool/number fields we need. */
-static bool mik__json_get_bool(const char* json, const char* key, bool* out) {
-    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++;
-    if (strncmp(p, "true", 4) == 0) { *out = true; return true; }
-    if (strncmp(p, "false", 5) == 0) { *out = false; return true; }
-    return false;
-}
-
+ * Only handles the flat object with string/number fields we need. */
 static bool mik__json_get_string(const char* json, const char* key, char* out, size_t out_size) {
     char pattern[128];
     snprintf(pattern, sizeof(pattern), "\"%s\"", key);
@@ -326,14 +316,10 @@ int MIK_LoadConfig(const char* base_path, MIKConfig* config) {
         snprintf(path, sizeof(path), "%s/mikro.config.json", app_dir);
         buf = mik__read_json_file(path, &st);
         if (buf) {
-            bool bool_val;
             double num_val;
 
-            if (mik__json_get_bool(buf, "restartOnUncaughtException", &bool_val)) {
-                config->restart_on_uncaught_exception = bool_val;
-            }
-            if (mik__json_get_number(buf, "restartDelay", &num_val)) {
-                config->restart_delay_ms = (int)num_val;
+            if (mik__json_get_number(buf, "panicRestartDelay", &num_val)) {
+                config->panic_restart_delay_ms = (int)num_val;
             }
             if (mik__json_get_number(buf, "stackSize", &num_val)) {
                 config->stack_size = (size_t)num_val;
@@ -349,9 +335,19 @@ int MIK_LoadConfig(const char* base_path, MIKConfig* config) {
             mik__json_get_string(buf, "wifi.hostname", config->wifi_hostname,
                                  sizeof(config->wifi_hostname));
 
+            mik__json_get_string(buf, "logFile.dir", config->log_dir, sizeof(config->log_dir));
+            if (mik__json_get_number(buf, "logFile.maxSize", &num_val)) {
+                config->log_max_size = (uint32_t)num_val;
+            }
+            char flush_str[16];
+            if (mik__json_get_string(buf, "logFile.flush", flush_str, sizeof(flush_str))) {
+                config->log_flush =
+                    strcmp(flush_str, "line") == 0 ? MIK_LOG_FLUSH_LINE : MIK_LOG_FLUSH_ERROR;
+            }
+
             platform->log(MIK_LOG_INFO, TAG,
-                           "Loaded config: restart=%d delay=%dms stack=%u reserved=%lu",
-                           config->restart_on_uncaught_exception, config->restart_delay_ms,
+                           "Loaded config: delay=%dms stack=%u reserved=%lu",
+                           config->panic_restart_delay_ms,
                            (unsigned)config->stack_size, (unsigned long)config->mem_reserved);
             free(buf);
         }

package/src/mik_console.cpp

@@ -420,6 +420,7 @@ void mik__console_init(JSContext* ctx, JSValue global_obj) {
  * bindings they'll never use. The mikrojs/test built-in has a console.log
  * fallback for when these globals aren't present. */
 void MIK_EnableTestHelpers(MIKRuntime* mik_rt) {
+    mik_rt->test_mode = true;
     JSContext* ctx = mik_rt->ctx;
     JSValue global_obj = JS_GetGlobalObject(ctx);
     JS_SetPropertyStr(ctx, global_obj, "__testEmit",

package/src/mik_repl.cpp

@@ -47,6 +47,23 @@ bool mik__repl_is_protocol_mode(void) {
 
 /* ── TLV frame helpers ───────────────────────────────────────────── */
 
+/* Plain bool, not atomic — relies on the assumption that mik__proto_send
+ * is only ever called from the REPL serve task, which is the same task
+ * that drives mik__console_write (since console_write is invoked by the
+ * runtime's stdout/stderr hooks during JS execution, and JS runs on the
+ * serve task). If a future feature introduces another task that calls
+ * mik__console_write directly (e.g. a watchdog or a sensor task that
+ * writes to console), its writes during a proto_send window will be
+ * dropped by the file-log tap. Revisit (task-local storage, or move the
+ * suppression into mik__console_write itself) if that happens. */
+bool mik__proto_send_in_progress = false;
+
+static MIKLogEmitFn s_log_emit_tap = nullptr;
+
+void mik__set_log_emit_tap(MIKLogEmitFn fn) {
+    s_log_emit_tap = fn;
+}
+
 /* Send a TLV-framed message: [ type: uint8 ] [ length: uint32_le ] [ payload ] */
 void mik__proto_send(MIKReplTransport* transport, uint8_t type, const void* data,
                      size_t len) {
@@ -56,10 +73,12 @@ void mik__proto_send(MIKReplTransport* transport, uint8_t type, const void* data
     header[2] = (uint8_t)((len >> 8) & 0xFF);
     header[3] = (uint8_t)((len >> 16) & 0xFF);
     header[4] = (uint8_t)((len >> 24) & 0xFF);
+    mik__proto_send_in_progress = true;
     transport->write(header, MIK_PROTO_HEADER_SIZE, transport->ctx);
     if (len > 0 && data) {
         transport->write(data, len, transport->ctx);
     }
+    mik__proto_send_in_progress = false;
 }
 
 void mik__proto_send_ok(MIKReplTransport* transport) {
@@ -70,9 +89,13 @@ void mik__proto_send_err(MIKReplTransport* transport, const char* msg) {
     mik__proto_send(transport, MIK_MSG_ERR, msg, strlen(msg));
 }
 
-/* Public wrapper used by mik_console.cpp and mik_stdio.cpp */
+/* Public wrapper used by mik_console.cpp and mik_stdio.cpp. Pre-frame
+ * tap fires before the TLV bytes go on the wire, so the file logger
+ * sees clean body text rather than [type][len][body]. */
 void mik__repl_proto_send_output(uint8_t msg_type, const void* data, size_t len) {
     if (repl_transport) {
+        MIKLogEmitFn tap = s_log_emit_tap;
+        if (tap) tap(msg_type, data, len);
         mik__proto_send(repl_transport, msg_type, data, len);
     }
 }
@@ -106,8 +129,11 @@ bool mik__proto_read_exact(MIKReplTransport* transport, void* buf, size_t n) {
             }
             /* Microtasks are deferred user JS: settling them re-enters .then
              * handlers that can write to the transport (console.log → MSG_LOG)
-             * or touch the filesystem mid-deploy. Gate on pause too. */
-            if (repl_ctx && !repl_paused) {
+             * or touch the filesystem mid-deploy. Gate on pause too — and
+             * on a pending panic-restart, since the runtime is on its way
+             * out and no further user JS should fire on it. */
+            if (repl_ctx && !repl_paused &&
+                (!repl_mik_rt || repl_mik_rt->restart_at_us == 0)) {
                 mik__execute_jobs(repl_ctx);
             }
             /* A pumped job (e.g. the test runtime's __testFileDone) may

package/src/mikrojs.cpp

@@ -145,18 +145,18 @@ static void mik__promise_rejection_tracker(JSContext* ctx, JSValue promise, JSVa
              * are genuine unhandled promise rejections. */
             bool in_promise = !mik__repl_is_evaluating();
             mik__report_uncaught(ctx, reason, in_promise);
-            if (!MIK_IsReplActive()) {
-                /* Notify the error handler (e.g. host bridge) directly.
-                 * Don't JS_Throw here — we're inside a QuickJS callback
-                 * during promise resolution; throwing would corrupt engine
-                 * state and cause mik__execute_jobs to dump the error a
-                 * second time. */
-                if (mik_rt->error_handler_fn) {
-                    mik_rt->error_handler_fn(ctx, reason, mik_rt->error_handler_opaque);
-                }
-                mik_rt->stop_requested = true;
-                MIK_Stop(mik_rt);
+            /* Notify the error handler (e.g. host bridge) directly.
+             * Don't JS_Throw here — we're inside a QuickJS callback
+             * during promise resolution; throwing would corrupt engine
+             * state and cause mik__execute_jobs to dump the error a
+             * second time. MIK_Stop itself gates on whether we're inside
+             * an interactive REPL eval so a typo at the prompt doesn't
+             * reboot the device. */
+            if (mik_rt->error_handler_fn) {
+                mik_rt->error_handler_fn(ctx, reason, mik_rt->error_handler_opaque);
             }
+            mik_rt->stop_requested = true;
+            MIK_Stop(mik_rt);
             return;
         }
 
@@ -534,6 +534,18 @@ void mik__execute_jobs(JSContext* ctx) {
 
 /* main loop which calls the user JS callbacks */
 int MIK_Loop(MIKRuntime* 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) {
+            platform->restart();
+        }
+        return 0;
+    }
     if (mik_rt->stop_requested) {
         return 1;
     }
@@ -659,14 +671,31 @@ bool MIK_IsStopRequested(MIKRuntime* mik_rt) {
 
 void MIK_Stop(MIKRuntime* mik_rt) {
     CHECK_NOT_NULL(mik_rt);
-    if (MIK_IsReplActive()) {
+    /* Only firmware (protocol REPL attached) auto-restarts on uncaught
+     * exceptions. Host embedders (Node addon, standalone tests) own their
+     * own process lifecycle and surface errors via the error handler. */
+    if (!MIK_IsReplActive()) {
         return;
     }
-    const MIKPlatform* platform = MIK_GetPlatform();
-    if (mik_rt->config.restart_on_uncaught_exception) {
-        printf("Restarting in %d ms...\n", mik_rt->config.restart_delay_ms);
-        usleep(mik_rt->config.restart_delay_ms * 1000);
-        platform->restart();
+    /* A throw inside an interactive REPL eval is a user typo, not an app
+     * crash — don't reboot the device. */
+    if (mik__repl_is_evaluating()) {
+        return;
+    }
+    /* In test mode, the supervisor wants stop_requested to bubble up so it
+     * can synthesize a failing-test event and move to the next file. Arming
+     * a panic-restart here would reboot the device mid-manifest on the
+     * first async rejection. */
+    if (mik_rt->test_mode) {
+        return;
+    }
+    /* Defer the restart so the host can still issue deploy/clean/--recover
+     * commands during the grace window. The actual platform->restart()
+     * fires from MIK_Loop once the deadline elapses. */
+    if (mik_rt->restart_at_us == 0) {
+        const MIKPlatform* platform = MIK_GetPlatform();
+        mik_rt->restart_at_us =
+            platform->get_boot_us() + (int64_t)mik_rt->config.panic_restart_delay_ms * 1000;
     }
 }