@mikrojs/native 0.6.0 → 0.8.0-pr-85.g6768f8c

package/include/mikrojs/mikrojs.h

@@ -23,15 +23,25 @@ typedef struct MIKRunOptions {
     bool use_psram_heap;
 } MIKRunOptions;
 
+/* File-log flush policies. Mirror of `LogFlush` in the host-side TS type. */
+typedef enum MIKLogFlush {
+    MIK_LOG_FLUSH_ERROR = 0, /* default: buffer, flush on warn/error or buffer full */
+    MIK_LOG_FLUSH_LINE = 1,
+} MIKLogFlush;
+
 typedef struct MIKConfig {
-    bool restart_on_uncaught_exception;
-    int restart_delay_ms;
+    int panic_restart_delay_ms;
     size_t stack_size;
     uint32_t mem_reserved;
     uint32_t fs_read_max; /* 0 = keep runtime default (65536) */
     char entry_point[128];
     char wifi_country[3];   /* Two-letter country code + NUL, e.g. "NO" */
     char wifi_hostname[64]; /* DHCP hostname; empty = use mikrojs-<device-id> default */
+    /* File-log config. log_dir empty disables file logging; otherwise the
+     * file lives at "<log_dir>/log.txt" (rotated as ".../log.txt.1"). */
+    char log_dir[64];
+    uint32_t log_max_size;
+    MIKLogFlush log_flush;
 } MIKConfig;
 
 void MIK_DefaultConfig(MIKConfig* config);
@@ -306,6 +316,20 @@ void mik__proto_send(MIKReplTransport* transport, uint8_t type, const void* data
 void mik__proto_send_ok(MIKReplTransport* transport);
 void mik__proto_send_err(MIKReplTransport* transport, const char* msg);
 
+/* Tap called by mik__repl_proto_send_output with the raw body bytes (no
+ * TLV framing) before they're sent on the wire. Single slot — owned by
+ * the file logger on the device side. msg_type is the MIK_MSG_* value so
+ * the tap can pick the appropriate log level. */
+typedef void (*MIKLogEmitFn)(uint8_t msg_type, const void* data, size_t len);
+void mik__set_log_emit_tap(MIKLogEmitFn fn);
+
+/* True while mik__proto_send is writing TLV bytes to the transport.
+ * Platform-side transports (mik__console_write on the ESP32) check this
+ * to skip any installed wire-byte taps that would otherwise capture the
+ * framing in addition to the body. Single-task code path, so plain bool
+ * is sufficient — there's no other writer of this flag. */
+extern bool mik__proto_send_in_progress;
+
 /* ── Session primitives ─────────────────────────────────────────────
  * A protocol session is scoped to a transport (one client connection).
  * Runtimes are attached/detached within the session; a supervisor can

package/include/mikrojs/private.h

@@ -56,6 +56,18 @@ struct MIKRuntime {
     bool is_worker;
     bool freeing;
     bool stop_requested;  /* Set by promise rejection tracker to stop the loop */
+    /* Set by MIK_EnableTestHelpers — the test supervisor wants stop_requested
+     * to bubble up cleanly so it can synthesize a failing-test event and move
+     * to the next file. Without this flag, MIK_Stop would arm a panic-restart
+     * deadline and reboot the whole device mid-manifest on the first async
+     * rejection. */
+    bool test_mode;
+    /* Deferred restart deadline (boot_us, 0 = no pending restart). Set by
+     * MIK_Stop when an uncaught exception happens with a protocol REPL
+     * attached: the serve loop keeps reading commands until the deadline so
+     * the host can still deploy/clean/--recover during the grace window,
+     * then platform->restart() fires from MIK_Loop. */
+    int64_t restart_at_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) */
@@ -259,6 +271,9 @@ void mik__repl_set_paused(bool paused);
 #define MIK_MSG_ERR 0x81
 #define MIK_MSG_CHECKSUM_RESULT 0x82
 #define MIK_MSG_CONFIG_ENTRIES 0x83
+/* Chunk of file bytes streamed in response to MIK_CMD_FS_GET.
+ * Multiple frames precede a final MSG_OK signaling end-of-file. */
+#define MIK_MSG_FS_CHUNK 0x84
 
 /* CLI → Device command types */
 #define MIK_CMD_EVAL 0x10
@@ -284,6 +299,10 @@ void mik__repl_set_paused(bool paused);
 #define MIK_CMD_RESTART 0x28
 #define MIK_CMD_RUNTIME_PAUSE 0x29
 #define MIK_CMD_RUNTIME_RESUME 0x2A
+/* Pull a file off the device. Payload: u16le path_len | path.
+ * Device replies with zero-or-more MIK_MSG_FS_CHUNK frames followed by
+ * MIK_MSG_OK on EOF, or MIK_MSG_ERR if the path can't be opened. */
+#define MIK_CMD_FS_GET 0x2B
 
 #define MIK_CMD_CONFIG_LIST 0x40
 #define MIK_CMD_CONFIG_SET 0x41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikrojs/native",
-  "version": "0.6.0",
+  "version": "0.8.0-pr-85.g6768f8c",
   "description": "Mikro.js C++ runtime library and Node.js native addon",
   "keywords": [
     "esp32",
@@ -78,7 +78,7 @@
     "cmake-js": "^8.0.0",
     "node-addon-api": "^8.7.0",
     "node-gyp-build": "^4.8.4",
-    "@mikrojs/quickjs": "0.6.0"
+    "@mikrojs/quickjs": "0.8.0-pr-85.g6768f8c"
   },
   "devDependencies": {
     "@swc/core": "^1.15.30",

package/runtime/fs/fs.ts

@@ -1,4 +1,4 @@
-import {ok} from 'mikrojs/result'
+import {err, ok} from 'mikrojs/result'
 import * as native from 'native:fs'
 
 import type {Result} from '../result/types.js'
@@ -61,28 +61,26 @@ export const exists = native.exists
 export function readStream(
   path: string,
   options?: ReadStreamOptions,
-): Result<AsyncIterable<Uint8Array>, FSError> {
+): Result<AsyncIterable<Result<Uint8Array, FSError>>, FSError> {
   const openResult = native.open(path)
   if (!openResult.ok) return openResult
   const fh = openResult.value
   const chunkSize = options?.chunkSize ?? 512
 
-  async function* iterate(): AsyncIterable<Uint8Array> {
+  async function* iterate(): AsyncIterable<Result<Uint8Array, FSError>> {
     try {
       while (true) {
         const r = fh.read(chunkSize)
         if (!r.ok) {
           // Handle-level errors (BadFileDescriptor, Unknown) don't carry a
-          // path from the native side. All other variants include `path`
-          // when emitted by path-level ops — but fh.read doesn't have the
-          // path, so we decorate here to preserve the original readStream
-          // context.
+          // path from the native side. Path-aware variants are decorated
+          // here so consumers see the original readStream context.
           const e = r.error
-          if (e.name === 'BadFileDescriptor' || e.name === 'Unknown') throw e
-          throw {...e, path}
+          yield e.name === 'BadFileDescriptor' || e.name === 'Unknown' ? err(e) : err({...e, path})
+          return
         }
         if (r.value === undefined) break
-        yield r.value
+        yield ok(r.value)
       }
     } finally {
       fh.close()

package/runtime/fs/types.ts

@@ -79,8 +79,8 @@ export interface ReadStreamOptions {
 
 /**
  * Open a file as a stream of byte chunks. Returns a Result because the
- * initial open can fail; once iterating, mid-stream read errors propagate
- * via rejected promises from `next()`.
+ * initial open can fail; once iterating, mid-stream read errors arrive
+ * as a final `err(...)` item and end the stream.
  *
  * Compose with `mikrojs/stream` helpers (`decodeUtf8`, `splitLines`) for
  * text/line streams. Closes the underlying handle on EOF, mid-stream
@@ -89,4 +89,4 @@ export interface ReadStreamOptions {
 export declare function readStream(
   path: string,
   options?: ReadStreamOptions,
-): Result<AsyncIterable<Uint8Array>, FSError>
+): Result<AsyncIterable<Result<Uint8Array, FSError>>, FSError>

package/runtime/http/helpers.ts

@@ -3,7 +3,9 @@
 // LTE modem over UART) implement the `Request` type directly and reuse
 // `prepareBody` + `makeResponse` for the boring parts.
 
-import type {Result} from 'mikrojs/result'
+import {err, ok} from 'mikrojs/result'
+
+import type {Result} from '../result/types.js'
 
 export interface RequestOptions {
   method?: string
@@ -25,21 +27,24 @@ export interface Response {
   headers: [string, string][]
   ok: boolean
   /**
-   * Response body as an async iterable of chunks. Single-shot: after any of
-   * `body`, `text()`, `bytes()`, or `json()` has started draining, calling
-   * another consumer throws `BodyConsumedError`.
+   * Response body as an async iterable of byte chunks. Iteration yields
+   * `Result<Uint8Array, RequestError>` so mid-stream failures (network
+   * drop, abort, timeout) compose with the rest of the Result-based API.
+   * Single-shot: after any of `body`, `text()`, `bytes()`, or `json()`
+   * has started draining, the next consumer call throws
+   * `BodyConsumedError`.
    */
-  body: AsyncIterable<Uint8Array>
+  body: AsyncIterable<Result<Uint8Array, RequestError>>
   /** First matching header value, case-insensitive, or undefined if absent. */
   get(name: string): string | undefined
   /** All matching header values in order, case-insensitive. Empty array if absent. */
   getAll(name: string): string[]
   /** Drain body as a UTF-8 string. Throws `BodyConsumedError` on second consumer call. */
-  text(): Promise<string>
+  text(): Promise<Result<string, RequestError>>
   /** Drain body and parse as JSON. Throws `BodyConsumedError` on second consumer call. */
-  json(): Promise<unknown>
+  json(): Promise<Result<unknown, RequestError>>
   /** Drain body to a single `Uint8Array`. Throws `BodyConsumedError` on second consumer call. */
-  bytes(): Promise<Uint8Array>
+  bytes(): Promise<Result<Uint8Array, RequestError>>
   /**
    * Cancel the request and release any native resources. Safe to call after
    * the body has been consumed (no-op). Safe to call multiple times.
@@ -63,16 +68,11 @@ export const RequestError = {
   Aborted: (message: string) => ({name: 'Aborted', message}) as const,
   /** Transport is at its concurrent-request cap. Retry after in-flight requests settle. */
   TooManyPending: () => ({name: 'TooManyPending'}) as const,
+  /** Body drained but JSON.parse rejected the payload. */
+  InvalidJson: (message: string) => ({name: 'InvalidJson', message}) as const,
 }
 
-export type RequestError =
-  | ReturnType<typeof RequestError.Hardware>
-  | ReturnType<typeof RequestError.Network>
-  | ReturnType<typeof RequestError.Timeout>
-  | ReturnType<typeof RequestError.BodyTooLarge>
-  | ReturnType<typeof RequestError.InvalidResponse>
-  | ReturnType<typeof RequestError.Aborted>
-  | ReturnType<typeof RequestError.TooManyPending>
+export type RequestError = ReturnType<(typeof RequestError)[keyof typeof RequestError]>
 
 export class BodyConsumedError extends Error {
   readonly name = 'BodyConsumed'
@@ -99,9 +99,9 @@ export function prepareBody(opts: RequestOptions): {
 }
 
 /**
- * Wrap a transport's raw response (async-iterable body) into the public
- * `Response` shape with `text()`/`json()`/`bytes()`/`get()`/`getAll()`/`close()`
- * and a single-shot body claim.
+ * Wrap a transport's raw response (Result-yielding async-iterable body) into
+ * the public `Response` shape with `text()`/`json()`/`bytes()`/`get()`/
+ * `getAll()`/`close()` and a single-shot body claim.
  */
 export function makeResponse(raw: {
   status: number
@@ -109,7 +109,7 @@ export function makeResponse(raw: {
   url: string
   redirected: boolean
   headers: [string, string][]
-  body: AsyncIterable<Uint8Array>
+  body: AsyncIterable<Result<Uint8Array, RequestError>>
 }): Response {
   let consumed = false
   const claim = () => {
@@ -117,7 +117,7 @@ export function makeResponse(raw: {
     consumed = true
   }
 
-  const body: AsyncIterable<Uint8Array> = {
+  const body: AsyncIterable<Result<Uint8Array, RequestError>> = {
     [Symbol.asyncIterator]() {
       claim()
       return raw.body[Symbol.asyncIterator]()
@@ -153,7 +153,13 @@ export function makeResponse(raw: {
     },
     json: async () => {
       claim()
-      return JSON.parse(await drainAsText(raw.body))
+      const text = await drainAsText(raw.body)
+      if (!text.ok) return text
+      try {
+        return ok(JSON.parse(text.value))
+      } catch (e) {
+        return err(RequestError.InvalidJson(e instanceof Error ? e.message : String(e)))
+      }
     },
     bytes: async () => {
       claim()
@@ -177,29 +183,35 @@ function normalizeHeaders(
   return out
 }
 
-async function drain(source: AsyncIterable<Uint8Array>): Promise<Uint8Array> {
+async function drain(
+  source: AsyncIterable<Result<Uint8Array, RequestError>>,
+): Promise<Result<Uint8Array, RequestError>> {
   const parts: Uint8Array[] = []
   let total = 0
-  for await (const chunk of source) {
-    parts.push(chunk)
-    total += chunk.length
+  for await (const r of source) {
+    if (!r.ok) return r
+    parts.push(r.value)
+    total += r.value.length
   }
-  if (parts.length === 1) return parts[0]!
+  if (parts.length === 1) return ok(parts[0]!)
   const out = new Uint8Array(total)
   let offset = 0
   for (const p of parts) {
     out.set(p, offset)
     offset += p.length
   }
-  return out
+  return ok(out)
 }
 
-async function drainAsText(source: AsyncIterable<Uint8Array>): Promise<string> {
+async function drainAsText(
+  source: AsyncIterable<Result<Uint8Array, RequestError>>,
+): Promise<Result<string, RequestError>> {
   const decoder = new TextDecoder()
   let out = ''
-  for await (const chunk of source) {
-    out += decoder.decode(chunk, {stream: true})
+  for await (const r of source) {
+    if (!r.ok) return r
+    out += decoder.decode(r.value, {stream: true})
   }
   out += decoder.decode()
-  return out
+  return ok(out)
 }

package/runtime/http/native.ts

@@ -92,10 +92,10 @@ export function createRequestFromNative(native: NativeHttpModule): Request {
     const {status, headers: responseHeaders} = headersResult.value
 
     let done = false
-    const rawBody: AsyncIterable<Uint8Array> = {
+    const rawBody: AsyncIterable<Result<Uint8Array, RequestError>> = {
       [Symbol.asyncIterator]() {
         return {
-          async next() {
+          async next(): Promise<IteratorResult<Result<Uint8Array, RequestError>>> {
             if (done) return {done: true, value: undefined}
             let msg
             try {
@@ -103,19 +103,28 @@ export function createRequestFromNative(native: NativeHttpModule): Request {
             } catch (e) {
               done = true
               cleanup()
-              throw e
+              const message = e instanceof Error ? e.message : String(e)
+              return {done: false, value: err(RequestError.Network(message))}
             }
             if (msg.kind === 'chunk') {
-              return {done: false, value: msg.data}
+              return {done: false, value: ok(msg.data)}
             }
             done = true
             cleanup()
             if (msg.kind === 'end') return {done: true, value: undefined}
             /* error */
             if (msg.cancelled) {
-              throw RequestError.Aborted(msg.message || String(options.signal?.reason ?? 'aborted'))
+              return {
+                done: false,
+                value: err(
+                  RequestError.Aborted(msg.message || String(options.signal?.reason ?? 'aborted')),
+                ),
+              }
+            }
+            return {
+              done: false,
+              value: err(RequestError.Network(msg.message || 'HTTP request failed')),
             }
-            throw RequestError.Network(msg.message || 'HTTP request failed')
           },
           async return() {
             if (!done) {

package/runtime/internal.d.ts

@@ -318,8 +318,8 @@ declare module 'native:uart' {
 
     read(): Result<
       {
-        next(): Promise<IteratorResult<Uint8Array>>
-        return(): Promise<IteratorResult<Uint8Array>>
+        next(): Promise<IteratorResult<Result<Uint8Array, UartError>>>
+        return(): Promise<IteratorResult<Result<Uint8Array, UartError>>>
       },
       UartError
     >

package/runtime/kv/shared.ts

@@ -1,4 +1,4 @@
-import {defineError, err, ok} from 'mikrojs/result'
+import {err, ok} from 'mikrojs/result'
 // Typed loosely to avoid deep type instantiation from Infer<S> in parse's generics.
 // Type safety is provided by the storage interface overloads in types.ts.
 import {parse as _parse} from 'mikrojs/schema'
@@ -8,12 +8,14 @@ import type {NativeError} from '../result/types.js'
 type ParseResult = {ok: true; value: unknown} | {ok: false; error: {message: string; path: string}}
 const parse = _parse as unknown as (schema: unknown, value: unknown) => ParseResult
 
-export const KVError = defineError('KVError', {
-  StorageFull: (message: string) => ({message}),
-  EncodeFailed: (message: string) => ({message}),
-  WriteFailed: (message: string) => ({message}),
-  ValidationFailed: (message: string, path: string) => ({message, path}),
-})
+export const KVError = {
+  StorageFull: (message: string) => ({name: 'StorageFull', message}) as const,
+  EncodeFailed: (message: string) => ({name: 'EncodeFailed', message}) as const,
+  WriteFailed: (message: string) => ({name: 'WriteFailed', message}) as const,
+  ValidationFailed: (message: string, path: string) =>
+    ({name: 'ValidationFailed', message, path}) as const,
+  Unknown: (code: number, message: string) => ({name: 'Unknown', code, message}) as const,
+}
 
 /* Error codes from errors.h (MIK_ERR_BASE + 0xD0..0xD4) */
 const KV_INVALID_KEY = 0x80d0
@@ -43,7 +45,7 @@ function mapKvError(e: NativeError) {
     case KV_WRITE:
       return KVError.WriteFailed(e.message)
     default:
-      throw new Error(`unexpected native kv error: code=0x${e.code.toString(16)}`)
+      return KVError.Unknown(e.code, e.message)
   }
 }
 

package/runtime/kv/types.ts

@@ -55,6 +55,7 @@ export type KVError =
   | {name: 'EncodeFailed'; message: string}
   | {name: 'WriteFailed'; message: string}
   | {name: 'ValidationFailed'; message: string; path: string}
+  | {name: 'Unknown'; code: number; message: string}
 
 export type KVOptions<S> =
   | {

package/runtime/reader/reader.ts

@@ -9,12 +9,19 @@
  * lazy-load efficiency.
  */
 
+import {err, ok} from 'mikrojs/result'
+
+import type {Result} from '../result/types.js'
+
+export type ReaderError = {name: 'Timeout'; ms: number} | {name: 'StreamClosed'}
+
 /**
- * A buffered byte reader over an async iterator of byte chunks.
+ * A buffered byte reader over a Result-yielding async iterator of
+ * byte chunks.
  *
- * Wraps any `AsyncIterable<Uint8Array>` (typically `uart.read()`,
- * eventually also TCP sockets) and exposes three primitives that
- * share the same underlying byte buffer:
+ * Wraps any `AsyncIterable<Result<Uint8Array, E>>` (typically
+ * `uart.read()`, `fs.readStream`, an HTTP body) and exposes three
+ * primitives that share the same underlying byte buffer:
  *
  *   - `readUntil(delimiter, {timeoutMs})` — pull chunks until the
  *     buffer contains `delimiter`, return everything before it and
@@ -30,12 +37,12 @@
  *     underlying iterator. Useful before sending a new command when
  *     stale bytes from a previous response might be left over.
  *
- * Both `readUntil` and `readBytes` throw `TimeoutError` (an Error
- * with `name === 'TimeoutError'`) if the deadline expires before
- * the request is satisfied, and `StreamClosed` (an Error with
- * `name === 'StreamClosed'`) if the underlying iterator finishes
- * before the request is satisfied. Callers may wrap those in their
- * own Result type if they prefer structured error handling.
+ * Both `readUntil` and `readBytes` return `Result<Uint8Array, E |
+ * ReaderError>`: `err({name: 'Timeout', ms})` if the deadline expires
+ * before the request is satisfied, `err({name: 'StreamClosed'})` if
+ * the underlying iterator finishes early, or whatever error variant
+ * the source yields. `RangeError` is still thrown for invalid
+ * arguments (programmer mistakes, not stream errors).
  *
  * Timeout semantics: when a pull races against a `setTimeout` and
  * the timer wins, the pending `iter.next()` promise is kept so the
@@ -48,18 +55,21 @@
  * not protected against — the caller is responsible for
  * sequential ordering.
  */
-export class BufferedReader {
-  readonly #source: AsyncIterator<Uint8Array>
+export class BufferedReader<E = never> {
+  readonly #source: AsyncIterator<Result<Uint8Array, E>>
   #buffer: Uint8Array
-  #pending: Promise<IteratorResult<Uint8Array>> | null
+  #pending: Promise<IteratorResult<Result<Uint8Array, E>>> | null
 
-  constructor(source: AsyncIterable<Uint8Array>) {
-    this.#source = source[Symbol.asyncIterator]() as AsyncIterator<Uint8Array>
+  constructor(source: AsyncIterable<Result<Uint8Array, E>>) {
+    this.#source = source[Symbol.asyncIterator]() as AsyncIterator<Result<Uint8Array, E>>
     this.#buffer = new Uint8Array(0)
     this.#pending = null
   }
 
-  async readUntil(delimiter: Uint8Array, options: {timeoutMs: number}): Promise<Uint8Array> {
+  async readUntil(
+    delimiter: Uint8Array,
+    options: {timeoutMs: number},
+  ): Promise<Result<Uint8Array, E | ReaderError>> {
     if (delimiter.length === 0) {
       throw new RangeError('BufferedReader.readUntil: delimiter must be non-empty')
     }
@@ -69,24 +79,29 @@ export class BufferedReader {
       if (idx !== -1) {
         const out = this.#buffer.slice(0, idx)
         this.#buffer = this.#buffer.slice(idx + delimiter.length)
-        return out
+        return ok(out)
       }
-      await this.#pull(deadline)
+      const pull = await this.#pull(deadline, options.timeoutMs)
+      if (!pull.ok) return pull
     }
   }
 
-  async readBytes(count: number, options: {timeoutMs: number}): Promise<Uint8Array> {
+  async readBytes(
+    count: number,
+    options: {timeoutMs: number},
+  ): Promise<Result<Uint8Array, E | ReaderError>> {
     if (count < 0) {
       throw new RangeError('BufferedReader.readBytes: count must be non-negative')
     }
-    if (count === 0) return new Uint8Array(0)
+    if (count === 0) return ok(new Uint8Array(0))
     const deadline = Date.now() + options.timeoutMs
     while (this.#buffer.length < count) {
-      await this.#pull(deadline)
+      const pull = await this.#pull(deadline, options.timeoutMs)
+      if (!pull.ok) return pull
     }
     const out = this.#buffer.slice(0, count)
     this.#buffer = this.#buffer.slice(count)
-    return out
+    return ok(out)
   }
 
   /**
@@ -100,13 +115,9 @@ export class BufferedReader {
     this.#buffer = new Uint8Array(0)
   }
 
-  async #pull(deadline: number): Promise<void> {
+  async #pull(deadline: number, timeoutMs: number): Promise<Result<void, E | ReaderError>> {
     const remaining = deadline - Date.now()
-    if (remaining <= 0) {
-      const err = new Error(`BufferedReader: timeout waiting for bytes`)
-      err.name = 'TimeoutError'
-      throw err
-    }
+    if (remaining <= 0) return err({name: 'Timeout' as const, ms: timeoutMs})
 
     if (this.#pending === null) {
       this.#pending = this.#source.next()
@@ -116,24 +127,24 @@ export class BufferedReader {
     let timerId: ReturnType<typeof setTimeout> | undefined
     try {
       const result = await Promise.race([
-        pending.then((v): {kind: 'value'; v: IteratorResult<Uint8Array>} => ({kind: 'value', v})),
+        pending.then((v): {kind: 'value'; v: IteratorResult<Result<Uint8Array, E>>} => ({
+          kind: 'value',
+          v,
+        })),
         new Promise<{kind: 'timeout'}>((resolve) => {
           timerId = setTimeout(() => resolve({kind: 'timeout'}), remaining)
         }),
       ])
       if (result.kind === 'timeout') {
         // Leave #pending intact so the next pull resumes on this chunk.
-        const err = new Error(`BufferedReader: timeout after ${remaining}ms waiting for bytes`)
-        err.name = 'TimeoutError'
-        throw err
+        return err({name: 'Timeout' as const, ms: timeoutMs})
       }
       this.#pending = null
-      if (result.v.done) {
-        const err = new Error('BufferedReader: stream closed before read satisfied')
-        err.name = 'StreamClosed'
-        throw err
-      }
-      this.#buffer = concatBytes(this.#buffer, result.v.value)
+      if (result.v.done) return err({name: 'StreamClosed' as const})
+      const item = result.v.value
+      if (!item.ok) return item
+      this.#buffer = concatBytes(this.#buffer, item.value)
+      return ok()
     } finally {
       if (timerId !== undefined) clearTimeout(timerId)
     }

package/runtime/reader/types.ts

@@ -7,10 +7,14 @@
  * `packages/mikrojs` and by user apps via their tsconfig.
  */
 
+import type {Result} from 'mikrojs/result'
+
+export type ReaderError = {name: 'Timeout'; ms: number} | {name: 'StreamClosed'}
+
 /**
- * A buffered byte reader over an async iterator of `Uint8Array`
- * chunks. Offers three operations that share the same underlying
- * buffer:
+ * A buffered byte reader over a Result-yielding async iterator of
+ * `Uint8Array` chunks. Offers three operations that share the same
+ * underlying buffer:
  *
  *   - `readUntil(delimiter, {timeoutMs})` — return everything before
  *     the first occurrence of `delimiter`, consume the delimiter.
@@ -19,16 +23,23 @@
  *   - `drain()` — discard buffered bytes without affecting the
  *     underlying iterator.
  *
- * Throws an Error with `name === 'TimeoutError'` if the deadline
- * expires before the request is satisfied, or `name === 'StreamClosed'`
- * if the underlying iterator finishes before the request is satisfied.
+ * Returns `err({name: 'Timeout', ms})` if the deadline expires,
+ * `err({name: 'StreamClosed'})` if the underlying iterator finishes
+ * early, or the source's own error variant when it yields one.
+ * `RangeError` is still thrown for invalid arguments.
  *
  * Single-consumer only: concurrent `readUntil` / `readBytes` calls on
  * the same instance are unsupported.
  */
-export declare class BufferedReader {
-  constructor(source: AsyncIterable<Uint8Array>)
-  readUntil(delimiter: Uint8Array, options: {timeoutMs: number}): Promise<Uint8Array>
-  readBytes(count: number, options: {timeoutMs: number}): Promise<Uint8Array>
+export declare class BufferedReader<E = never> {
+  constructor(source: AsyncIterable<Result<Uint8Array, E>>)
+  readUntil(
+    delimiter: Uint8Array,
+    options: {timeoutMs: number},
+  ): Promise<Result<Uint8Array, E | ReaderError>>
+  readBytes(
+    count: number,
+    options: {timeoutMs: number},
+  ): Promise<Result<Uint8Array, E | ReaderError>>
   drain(): void
 }

package/runtime/result/result.ts

@@ -7,20 +7,9 @@ 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 {
+  return (handlers as unknown as Record<string, (e: E) => R>)[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
@@ -106,28 +119,30 @@ export async function collectUntil<T>(
  *   timeout, or consumer break) so underlying resources (UART claims,
  *   socket handles, ring buffers) get released.
  */
-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 +150,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,56 @@
  * 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.
  */
-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);
     }
 }
@@ -104,7 +127,13 @@ bool mik__proto_read_exact(MIKReplTransport* transport, void* buf, size_t n) {
                     return false;
                 }
             }
-            if (repl_ctx) {
+            /* 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 — 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
@@ -1109,12 +1138,14 @@ void MIK_ProtocolServeLoop(void) {
             }
         }
 
-        /* Pump event loop between commands (skip timers/callbacks when paused,
-         * but always run microtasks so promises can settle) */
+        /* Pump event loop between commands. Skip both timers/callbacks AND
+         * microtasks when paused — draining microtasks runs user .then
+         * handlers, which can interleave MSG_LOG output with deploy traffic
+         * or race the staged-file swap. */
         if (repl_mik_rt && !repl_paused) {
             MIK_Loop(repl_mik_rt);
         }
-        if (ctx) {
+        if (ctx && !repl_paused) {
             mik__execute_jobs(ctx);
         }
     }

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;
     }
 }