Merge pull request #8 from bitcoin3us/docs/task-supervision-and-boot-ctrlc

Document TaskManager.create_supervised_task() and boot-time Ctrl-C handling

Author: ThomasFarstrike

docs/architecture/boot-sequence.md

@@ -7,6 +7,7 @@ MicroPythonOS consists of several core components that initialize and manage the
 - **internal_filesystem/main.py**: Hands off execution to /lib/mpos/main.py by importing it
 
 - **/lib/mpos/main.py**:
+    - Disables the Ctrl-C interrupt character for the duration of the boot
     - Detects the hardware board
     - Initializes the filesystem driver
     - Mounts the freezefs into /builtin/
@@ -25,3 +26,15 @@ MicroPythonOS consists of several core components that initialize and manage the
 See [Filesystem Layout](filesystem.md) for where apps and data are stored.
 
 See [Service](../frameworks/service.md) for details on writing boot services.
+
+## Connecting over serial during boot
+
+Tools that open the serial port send Ctrl-C to interrupt whatever is running — `mpremote` does this whenever it enters the raw REPL. Arriving mid-boot, that would abort the boot scripts and leave the device at a bare REPL shell with the OS only half-started, which is easily mistaken for a broken build: the prompt looks normal, but apps are missing and files placed in `/lib` appear to have no effect.
+
+To prevent this, `/lib/mpos/main.py` disables the interrupt character (`micropython.kbd_intr(-1)`) as its first action, and the asyncio REPL manages it from then on. It is restored on the paths that fall back to the REPL shell, so a failed boot still gives you an interruptible prompt.
+
+Practical consequences:
+
+- Connecting while the device boots is safe; the command waits for the boot to finish instead of corrupting it.
+- Wait for `Starting asyncio REPL...` on the serial console to know the boot completed.
+- Ctrl-C can no longer break into a boot that hangs — use the board's reset button in that case.

docs/frameworks/task-manager.md

@@ -191,6 +191,35 @@ Create and schedule a background task.
 TaskManager.create_task(self.background_work())
 ```
 
+#### `TaskManager.create_supervised_task(coroutine_factory, restart_delay_ms=200)`
+
+Create a background task that is automatically restarted if it dies unexpectedly. Used by the OS for long-lived services that must never stay down, such as the asyncio REPL console.
+
+**Parameters:**
+
+- `coroutine_factory` - A **callable returning a fresh coroutine** (not a coroutine object), because a new one is needed for every restart
+- `restart_delay_ms` (int) - Delay before each restart, in milliseconds
+
+**Returns:**
+
+- Task object for the supervisor (cancel it to stop supervision)
+
+**Restart behavior:**
+
+- Task raises `Exception` or `KeyboardInterrupt` → logged and restarted after `restart_delay_ms`
+- Task returns normally → supervision ends (a clean exit is treated as intentional)
+- Supervisor task is cancelled → supervision ends, no restart
+
+**Example:**
+```python
+def make_listener():
+    return my_service.listen_forever()
+
+TaskManager.create_supervised_task(make_listener)
+```
+
+Note the factory: passing `create_supervised_task(my_service.listen_forever())` would hand over a single coroutine object that cannot be re-run after it dies.
+
 ### Sleep Operations
 
 #### `TaskManager.sleep(seconds)`
@@ -473,10 +502,15 @@ async def safe_task(self):
 
 **Key features:**
 - `create_task()` - Wraps `asyncio.create_task()`
+- `create_supervised_task()` - Restarts a task that dies from an exception or KeyboardInterrupt
 - `sleep()` / `sleep_ms()` - Wrap `asyncio.sleep()`
 - `wait_for()` - Wraps `asyncio.wait_for()` with timeout handling
 - `notify_event()` - Creates `asyncio.Event()` objects
 
+**KeyboardInterrupt resilience:**
+
+MicroPython's `run_until_complete()` only catches `CancelledError` and `Exception`, so a `KeyboardInterrupt` raised inside any task (for example from a stray Ctrl-C sent by a host connecting over serial) escapes the event loop and would otherwise terminate every running task while the LVGL UI keeps running on its hardware timer. `TaskManager.start()` catches this and re-enters `asyncio.run()`; the task queue survives the unwind, so the remaining tasks resume.
+
 **Thread model:**
 - All async tasks run on main asyncio event loop
 - No separate threads created (unless using `_thread` module separately)