A rootless Android app that boots Alpine Linux: run containers (Podman/Docker/LXC) and GUI desktop apps.
chore: post-virtio-console cleanup — dead code, stale docs, leftovers
ExTv4f3f0d01cc1e
diff --git a/CLAUDE.md b/CLAUDE.mdindex 157423b..f954961 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -44,12 +44,17 @@ The app uses debug build for all releases (release signing not configured). Nati```Terminal UI (Compose)↕ TerminalSession (Termux JNI)-libpodroid-bridge.so ←→ serial.sock / ctrl.sock ←→ QEMU ←→ ttyAMA0 (Alpine)+libpodroid-bridge.so ←→ terminal.sock + ctrl.sock ←→ QEMU ←→ hvc0 + hvc1 (Alpine)++PodroidQemu (boot monitor) ←→ serial.sock ←→ QEMU ←→ ttyAMA0 (boot log only)```-- **Terminal I/O:** TerminalSession runs `libpodroid-bridge.so` as a process; the bridge connects `serial.sock` (I/O relay) and `ctrl.sock` (SIGWINCH / resize signaling)-- **Port forwarding:** `QmpClient` sends `netdev_add`/`netdev_remove` commands to `qmp.sock` at runtime-- **Boot monitoring:** `PodroidQemu` reads `serial.sock` until it detects the "Ready!" marker, logging all output to `console.log`+The terminal layer uses three QEMU Unix sockets, each with a single role:++- **`terminal.sock`** ↔ virtio-console `/dev/hvc0` — primary terminal I/O. getty runs on hvc0; `libpodroid-bridge.so` relays it to a Termux PTY.+- **`ctrl.sock`** ↔ virtio-console `/dev/hvc1` — resize signal channel. Bridge debounces SIGWINCH bursts (~25 per keyboard slide) and writes a single `RESIZE rows cols\n`; the resize daemon in `init-podroid` stty's hvc0.+- **`serial.sock`** ↔ PL011 `/dev/ttyAMA0` — boot log sink. `PodroidQemu.monitorBootSerial` connects for the lifetime of the VM, streaming kernel + init output into `console.log` and the boot-stage detector. No bridge handoff.+- **`qmp.sock`** — runtime control for port forwarding (`QmpClient` sends `netdev_add` / `netdev_remove`).### Key Components@@ -57,7 +62,7 @@ libpodroid-bridge.so ←→ serial.sock / ctrl.sock ←→ QEMU ←→ tty**`service/PodroidService.kt`** — foreground service that owns the QEMU process. Holds a `WakeLock`, updates the persistent notification with boot stages, and handles graceful stop when the app is swiped from recents.-**`podroid-bridge.c`** — native C binary (compiled to `libpodroid-bridge.so`) that Termux runs as a subprocess. Bidirectionally relays PTY ↔ `serial.sock`, answers ESC window-size queries locally, and sends `RESIZE rows cols\n` to `ctrl.sock` on SIGWINCH.+**`podroid-bridge.c`** — native C binary (compiled to `libpodroid-bridge.so`) that Termux runs as a subprocess. Bidirectionally relays PTY ↔ `terminal.sock`, and writes `RESIZE rows cols\n` to `ctrl.sock` after a 200 ms-debounced SIGWINCH burst (so a single keyboard-slide animation produces one shell prompt redraw, not 25).**`init-podroid`** — two-phase Alpine init script embedded as an asset. Phase 1 mounts overlayfs over `storage.img`; Phase 2 sets up cgroup v2, SLIRP networking, Podman, and Dropbear SSH, then prints the boot stage markers consumed by `PodroidQemu`.@@ -76,7 +81,7 @@ Single-activity Compose app: `NavGraph.kt` routes `setup → home → terminal /| File | What it is ||---|---|| `libqemu-system-aarch64.so` | QEMU TCG emulator (PIE executable, 16KB aligned) |-| `libpodroid-bridge.so` | PTY ↔ serial relay (PIE executable, 16KB aligned) |+| `libpodroid-bridge.so` | PTY ↔ virtio-console relay (PIE executable, 16KB aligned) || `libtermux.so` | Termux terminal emulator JNI (rebuilt for 16KB pages) || `libslirp.so` | SLIRP user-mode networking (statically linked into QEMU) |@@ -85,8 +90,9 @@ These are executed directly via `ProcessBuilder` / `TerminalSession`, not loaded## QEMU Command Construction`PodroidQemu.buildCommand()` constructs the full QEMU cmdline including:-- `-serial unix:serial.sock` / `-chardev socket,path=ctrl.sock` / `-qmp unix:qmp.sock`-- RAM and CPU count from `SettingsRepository`+- `-serial unix:serial.sock` (boot log) + a virtio-serial-pci bus carrying two virtconsoles: `terminal.sock` (org.podroid.term, hvc0) and `ctrl.sock` (org.podroid.ctrl, hvc1)+- `-qmp unix:qmp.sock` for runtime port-forward changes+- RAM, CPU count, and user-editable extras (`-cpu`, `-accel`, RNG, etc.) from `SettingsRepository`- Virtio block device backed by `storage.img` (resized on first boot to configured size)- SLIRP networking with runtime port forwards via `QmpClient` (`netdev_add`/`netdev_remove` over `qmp.sock`)@@ -106,6 +112,17 @@ All tuning applies under software emulation only — KVM is impossible without r- ZRAM swap at half physical RAM using lz4 — gives 1.5–2× effective memory with near-zero I/O cost; swapon at priority 100 so it's preferred over any file swap**In `Dockerfile` (QEMU build):**-- `-O3 -flto=thin` in `--extra-cflags` / `--extra-ldflags` — LLVM thin LTO optimises across QEMU's translation units including the TCG hot path; deps are built separately without LTO so mixed linking is intentional+- QEMU 11.0.0-rc2 cross-compiled against NDK r27c with three minimum patches:+ `--disable-plugins` (uftrace.c uses `timespec_get`, absent from Bionic),+ empty `contrib/ivshmem-{server,client}/meson.build` (use shm_open we don't ship),+ `-include shm_shim.h` declarations + a `libshm.a` stub implementing+ `shm_open`/`shm_unlink` via `memfd_create` (NDK API-28 stubs lack them).+- Custom Linux 6.6.87 kernel: arm64 defconfig + `podroid_kernel.config` (modules)+ + `forced_builtin.config` (=y for IPV6 / BRIDGE / NF_TABLES / NFT_COMPAT /+ MASQUERADE family / VETH / TUN / OVERLAY_FS / FUSE_FS).+- A build-time loop greps the resolved `.config` and **fails the build** if+ any of those critical options isn't `=y`. This guards against silent+ Kconfig demotions caused by unmet tristate deps (e.g. CONFIG_BRIDGE caps+ out at IPV6's strength).**What won't work without root:** `io_uring` (Android 12+ seccomp block), CPU affinity/taskset, KSM memory dedup, TAP networking, huge pages on the host.diff --git a/app/src/main/java/com/excp/podroid/engine/PodroidQemu.kt b/app/src/main/java/com/excp/podroid/engine/PodroidQemu.ktindex 2affb2d..281367a 100644--- a/app/src/main/java/com/excp/podroid/engine/PodroidQemu.kt+++ b/app/src/main/java/com/excp/podroid/engine/PodroidQemu.kt@@ -2,19 +2,25 @@* Podroid - Rootless Podman for Android* Copyright (C) 2024 Podroid contributors*- * QEMU engine for Podroid. Manages the VM lifecycle and exposes two Unix+ * QEMU engine for Podroid. Manages the VM lifecycle and exposes three Unix* sockets for the terminal layer:*- * serial.sock — QEMU serial chardev (ttyAMA0 in the VM). The podroid-bridge- * binary connects here for bidirectional terminal I/O.+ * serial.sock — QEMU -serial (ttyAMA0 in the VM). Boot-log sink only:+ * PodroidQemu's monitorBootSerial coroutine connects here+ * for the lifetime of the VM, streaming kernel messages+ * and init-podroid boot stages into console.log + the+ * in-memory ring buffer used by detectBootStage().*- * ctrl.sock — QEMU virtio-console chardev (hvc0 in the VM). The bridge- * writes "RESIZE rows cols\n" here on SIGWINCH; the VM daemon- * calls stty on ttyAMA0 which triggers SIGWINCH in the VM.+ * terminal.sock — QEMU virtio-console (/dev/hvc0 in the VM). Primary+ * terminal I/O. getty runs on hvc0; the podroid-bridge+ * binary connects here for bidirectional shell I/O. Fully+ * independent of serial.sock, so no socket hand-off.*- * Boot monitoring: PodroidQemu connects to serial.sock and reads until the VM- * reaches the "Ready" stage (or until releaseSerial() is called). The bridge- * then takes over the connection for interactive terminal use.+ * ctrl.sock — QEMU virtio-console (/dev/hvc1 in the VM). Resize signal+ * channel only. Bridge writes "RESIZE rows cols\n" on+ * SIGWINCH (debounced by RESIZE_DEBOUNCE_MS); the resize+ * daemon in init-podroid stty's hvc0 to deliver SIGWINCH+ * to the foreground TUI inside the VM.*/package com.excp.podroid.engine@@ -108,11 +114,13 @@ class PodroidQemu @Inject constructor(}/**- * Release the boot-monitoring serial connection so podroid-bridge can connect.+ * Close the boot-monitoring serial socket. Called from cleanup() when the+ * VM stops; not used as a hand-off trigger any more (bridge has its own+ * socket).*/fun releaseSerial() {val sock = bootSocket ?: return- Log.d(TAG, "Releasing boot monitor socket")+ Log.d(TAG, "Closing boot monitor socket")bootSocket = nulltry {// Signal EOF to the monitor loop@@ -124,27 +132,6 @@ class PodroidQemu @Inject constructor(}}- /**- * Replay the portion of boot serial output that arrived after "Ready!" into- * a freshly created terminal emulator.- */- private fun replayBootOutput(sess: TerminalSession) {- val console = _consoleText.value- val readyIdx = console.indexOf("Ready!")- if (readyIdx < 0) return- val lineEnd = console.indexOf('\n', readyIdx)- if (lineEnd < 0) return- val postReady = console.substring(lineEnd + 1)- if (postReady.isEmpty()) return- val bytes = postReady.toByteArray(Charsets.UTF_8)- try {- sess.emulator?.append(bytes, bytes.size)- Log.d(TAG, "Replayed ${bytes.size}B of post-Ready output to emulator")- } catch (e: Exception) {- Log.w(TAG, "Could not replay boot output: ${e.message}")- }- }-private fun autoStartBridge() {android.os.Handler(android.os.Looper.getMainLooper()).post {if (_terminalSession != null) return@post@@ -196,7 +183,6 @@ class PodroidQemu @Inject constructor()sess.updateSize(80, 24)- replayBootOutput(sess)_terminalSession = sess_terminalSessionAttached = true@@ -322,9 +308,12 @@ class PodroidQemu @Inject constructor(}/**- * Connects to serial.sock and reads boot output until:- * - The "Ready" stage is detected, or- * - releaseSerial() is called (bootSocket closed externally), or+ * Connects to serial.sock and streams kernel + init-podroid output for the+ * lifetime of the VM. Writes the bytes to console.log and pushes the+ * latest tail into the consoleText flow used by the diagnostic exporter+ * and the boot-stage detector. Stops when:+ * - releaseSerial() is called during cleanup() (VM stopping), or+ * - QEMU itself exits, or* - The coroutine is cancelled.** Writes all output to console.log for the test-deploy.sh validator anddiff --git a/app/src/main/java/com/excp/podroid/ui/screens/terminal/TerminalViewModel.kt b/app/src/main/java/com/excp/podroid/ui/screens/terminal/TerminalViewModel.ktindex 92af110..681210e 100644--- a/app/src/main/java/com/excp/podroid/ui/screens/terminal/TerminalViewModel.kt+++ b/app/src/main/java/com/excp/podroid/ui/screens/terminal/TerminalViewModel.kt@@ -6,15 +6,18 @@** The bridge binary (libpodroid-bridge.so) runs as the TerminalSession* subprocess. Termux allocates a real PTY for it; the bridge relays that- * PTY to QEMU's serial Unix socket. Window resize is handled properly:+ * PTY to QEMU's virtio-console terminal.sock (= /dev/hvc0 in the VM).+ * Window resize is handled out-of-band over a second virtio-console port:** TerminalSession.updateSize(cols, rows)* → ioctl(pty_master, TIOCSWINSZ) [Termux JNI]* → SIGWINCH → bridge process- * → bridge reads new size via TIOCGWINSZ- * → writes "RESIZE rows cols\n" to ctrl.sock- * → VM daemon calls stty on /dev/ttyAMA0- * → Linux kernel sends SIGWINCH to VM foreground process group+ * → bridge debounces (RESIZE_DEBOUNCE_MS, currently 200 ms) so a+ * keyboard-slide animation collapses to one event+ * → reads final size via TIOCGWINSZ+ * → writes "RESIZE rows cols\n" to ctrl.sock (= /dev/hvc1 in the VM)+ * → init-podroid resize daemon calls stty on /dev/hvc0+ * → Linux sends SIGWINCH to the VM's foreground process group* → nvim / htop / btop redraws correctly** No reflection, no emulator injection, no sz stdin injection.diff --git a/init-podroid b/init-podroidindex d934ab8..df5469f 100755--- a/init-podroid+++ b/init-podroid@@ -62,17 +62,15 @@ hostname podroid 2>/dev/nullprintf '127.0.0.1\tlocalhost podroid\n::1\tlocalhost ip6-localhost\n' > /etc/hosts# ── Kernel modules + device nodes ────────────────────────────────────────────+# Bridge / netfilter / overlay / fuse / virtio are =y in our custom kernel+# (see Dockerfile forced_builtin.config), so only the few that legitimately+# remain modular are loaded here. The check on /lib/modules still guards+# against a kernel built without CONFIG_MODULES.boot_stage "Loading kernel modules..."_kver=$(uname -r)if [ -d "/lib/modules/$_kver" ]; thendepmod -a 2>/dev/null- for _mod in \- virtio_net virtio_blk fuse tun veth \- bridge br_netfilter overlay \- xt_addrtype xt_conntrack xt_nat xt_mark xt_comment \- nf_nat nf_conntrack nf_conntrack_netlink nfnetlink \- ip_tables ip6_tables ip6table_nat \- 9p 9pnet 9pnet_virtio; do+ for _mod in 9p 9pnet 9pnet_virtio; domodprobe "$_mod" 2>/dev/nulldonefi@@ -188,7 +186,6 @@ export CONTAINERS_STORAGE_CONF=/etc/containers/storage.confexport CONTAINERS_REGISTRIES_CONF=/etc/containers/registries.confdmesg -n 1 2>/dev/null-stty rows 24 cols 80 -ixon -ixoff -iexten 2>/dev/nulltrap 'podman stop -a -t 5 2>/dev/null; podman network prune -f 2>/dev/null; sync' TERM INT HUP# ── Resize daemon (reads RESIZE msgs from hvc1, applies to hvc0 terminal) ─────diff --git a/podroid-bridge.c b/podroid-bridge.cindex d464482..3914aa2 100644--- a/podroid-bridge.c+++ b/podroid-bridge.c@@ -18,7 +18,9 @@* SIGPIPE — ignored; EPIPE on write = EOF, handled in main loop* SIGINT — graceful shutdown* SIGTERM — graceful shutdown- * SIGWINCH — async flag, processed in select() loop; fires send_resize() immediately+ * SIGWINCH — async flag, debounced in the select() loop. Each signal just+ * refreshes a timestamp; send_resize() fires once after the+ * burst has been quiet for RESIZE_DEBOUNCE_MS.** Args: <terminal.sock> <ctrl.sock>*/diff --git a/skill.md b/skill.mdindex 739d382..0e9376c 100644--- a/skill.md+++ b/skill.md@@ -43,26 +43,25 @@ Android App├── PodroidService (foreground) — hosts QEMU, holds WakeLock, updates notification with boot stages├── PodroidQemu (singleton)│ ├── QEMU process (libqemu-system-aarch64.so — ELF binary renamed .so for APK)-│ ├── serial.sock — boot monitor reads until "Ready!", then bridge connects-│ ├── ctrl.sock — virtio-console for RESIZE signals from bridge-│ └── qmp.sock — QEMU Machine Protocol for runtime control (port forwarding)+│ ├── serial.sock — ttyAMA0 boot-log sink; monitor stays connected for VM lifetime+│ ├── terminal.sock — virtio-console hvc0; primary shell I/O for podroid-bridge+│ ├── ctrl.sock — virtio-console hvc1; debounced RESIZE messages from bridge+│ └── qmp.sock — QEMU Machine Protocol for runtime control (port forwarding)└── Compose UI└── Screens: Setup → Home → Terminal / Settings```-### VM Boot Sequence (critical — read carefully)-1. QEMU starts, creates `serial.sock` (unix socket, server, single-client)-2. **Boot monitor** (`PodroidQemu.monitorBootSerial`) connects first to `serial.sock`, streams output to `console.log` and parses `boot_stage` strings for the Android UI-3. `init-podroid` Phase 1 (running in initramfs): mounts virtio-blk as ext4, creates overlayfs (`lowerdir=/`, `upperdir=/mnt/persist/upper`), `chroot /mnt/overlay /init --main`-4. `init-podroid` Phase 2 (`--main`): kernel modules → networking → containers → SSH → getty on ttyAMA0-5. Phase 2 emits `boot_stage "Ready!"` then **sleeps 2 seconds** (critical — lets boot monitor finish reading "Ready!" before bridge steals the single-client socket)-6. `detectBootStage("Ready!")` fires → `_state = Running` → `autoStartBridge()`-7. **`releaseSerial()`** closes boot monitor socket (`shutdownInput + shutdownOutput + close`)-8. **500ms delay** then `TerminalSession` launched with `libpodroid-bridge.so` as subprocess-9. Bridge binary connects to `serial.sock`, relays PTY ↔ serial bidirectionally+### VM Boot Sequence+1. QEMU starts and binds all four sockets (`server,nowait` so it doesn't block on a connection).+2. **Boot monitor** (`PodroidQemu.monitorBootSerial`) connects to `serial.sock` and streams everything kernel and init-podroid write to ttyAMA0 into `console.log` + the in-memory tail used by `detectBootStage`. Stays connected for the lifetime of the VM (no hand-off).+3. `init-podroid` Phase 1 (initramfs): mounts virtio-blk as ext4, creates overlayfs (`lowerdir=/`, `upperdir=/mnt/persist/upper`), pivots via `/bin/busybox chroot /mnt/overlay /init --main`.+4. `init-podroid` Phase 2 (`--main`): kernel modules (just `9p*` now — bridge / netfilter / overlay / fuse / virtio are all built-in) → networking → containers → SSH → starts getty on `/dev/hvc0`. Resize daemon listens on `/dev/hvc1`.+5. Phase 2 emits `boot_stage "Ready!"` immediately before launching the getty loop — no `sleep 2` is needed any more because the bridge connects to a different socket.+6. `detectBootStage("Ready!")` fires → `_state = Running` → `autoStartBridge()` posts to the main thread.+7. `TerminalSession` launches `libpodroid-bridge.so` with `terminal.sock` + `ctrl.sock` as args. Bridge connects directly; no socket hand-off, no 500 ms guard delay.-### Single-Client Socket Constraint-`serial.sock` is QEMU `server,nowait` — only ONE client at a time. Boot monitor connects first. `releaseSerial()` frees it. Bridge has a 50×200ms retry loop. The `sleep 2` in init-podroid and the 500ms `postDelayed` in `autoStartBridge()` are both critical timing guards.+### No socket hand-off+The old PL011 path used a single-client `serial.sock` shared by the boot monitor and the bridge, which forced a `releaseSerial()` + delay dance. With the virtio-console split that constraint is gone. `releaseSerial()` only runs during `cleanup()` on VM stop now.---@@ -81,7 +80,7 @@ All tuning applies under software emulation only — KVM is impossible without r- ZRAM swap at half physical RAM using lz4 — gives 1.5–2× effective memory with near-zero I/O cost; swapon at priority 100 so it's preferred over any file swap.**In `Dockerfile` (QEMU build):**-- `-O3 -flto=thin` in `--extra-cflags` / `--extra-ldflags` — LLVM thin LTO optimises across QEMU's translation units including the TCG hot path.+- Currently `-fPIC -DANDROID` only (no LTO / -O3) — those previously caused link failures with QEMU 11.0.0-rc2 + NDK r27c. Three minimum patches make the build clean: `--disable-plugins`, empty `contrib/ivshmem-{server,client}/meson.build` stubs, and an `-include shm_shim.h` + `libshm.a` (memfd_create-backed) to satisfy `shm_open`/`shm_unlink`.---@@ -92,7 +91,7 @@ All tuning applies under software emulation only — KVM is impossible without r/├── app/ # Android application module├── init-podroid # VM init script (baked into initrd.img as /init)-├── podroid-bridge.c # Native PTY↔serial relay (compiled to libpodroid-bridge.so)+├── podroid-bridge.c # Native PTY↔virtio-console relay (compiled to libpodroid-bridge.so)├── Dockerfile # Unified multi-stage: downloader → rootfs-builder → packer → qemu-builder → final├── build-all.sh # Unified build+deploy script├── gradle.properties # podroidQemuVersion=11.0.0-rc2@@ -180,7 +179,7 @@ All tuning applies under software emulation only — KVM is impossible without r| File | What it is ||---|---|| `libqemu-system-aarch64.so` | QEMU TCG emulator (PIE executable, 16KB aligned) |-| `libpodroid-bridge.so` | PTY ↔ serial relay (PIE executable, 16KB aligned) |+| `libpodroid-bridge.so` | PTY ↔ virtio-console relay (PIE executable, 16KB aligned) || `libtermux.so` | Termux terminal emulator JNI (rebuilt for 16KB pages) || `libslirp.so` | SLIRP user-mode networking (statically linked into QEMU) |@@ -195,8 +194,9 @@ All tuning applies under software emulation only — KVM is impossible without r| Kernel | `filesDir/vmlinuz-virt` || Initrd | `filesDir/initrd.img` || Storage image | `filesDir/storage.img` (ext4, sparse) |-| serial.sock | `filesDir/serial.sock` — ttyAMA0, single-client, boot monitor then bridge |-| ctrl.sock | `filesDir/ctrl.sock` — hvc0, bridge writes `RESIZE rows cols\n` |+| serial.sock | `filesDir/serial.sock` — ttyAMA0, boot-log only; monitor stays connected for VM lifetime |+| terminal.sock | `filesDir/terminal.sock` — virtio-console hvc0; primary terminal for podroid-bridge |+| ctrl.sock | `filesDir/ctrl.sock` — virtio-console hvc1; bridge writes debounced `RESIZE rows cols\n` || qmp.sock | `filesDir/qmp.sock` || VM IP | 10.0.2.15/24 (SLIRP) || Gateway | 10.0.2.2 |@@ -206,8 +206,8 @@ All tuning applies under software emulation only — KVM is impossible without r| Default CPUs | 1 (range: 1, 2, 4, 6, 8) || Default font size | 20sp || Default storage | 2 GB (range: 2–64 GB) |-| QEMU machine | `-M virt,gic-version=3 -cpu max -accel tcg,thread=multi,tb-size=256` |-| Kernel cmdline | `console=ttyAMA0 loglevel=1 quiet androidip=<ip> [ssh=1]` |+| QEMU machine | `-M virt,gic-version=3 -smp <cpus> -m <ramMb>`; tunable extras (`-cpu`, `-accel`, RNG, etc.) come from the user-editable Settings field |+| Kernel cmdline | `console=ttyAMA0 <user-extras> androidip=<ip> [ssh=1]` (default user-extras: `loglevel=1 quiet mitigations=off elevator=mq-deadline`) |---@@ -228,7 +228,7 @@ These exact strings are emitted by `init-podroid` and matched by `PodroidQemu.deAlso detected: `Mounting storage...`, `Booting kernel...` (emitted by PodroidQemu itself, not init-podroid).-**Critical**: After `boot_stage "Ready!"`, init-podroid does `sleep 2` before starting the getty loop. This is intentional — gives the boot monitor time to read "Ready!" before the single-client serial.sock becomes available to the bridge.+No `sleep 2` after `Ready!` is needed any more — the boot monitor stays on `serial.sock` while the bridge connects to a separate `terminal.sock`, so there's no socket hand-off race to guard.---@@ -238,41 +238,38 @@ Also detected: `Mounting storage...`, `Booting kernel...` (emitted by PodroidQem```bash# Located AFTER the `if [ "$1" = "--main" ]; then ... fi` block (at end of file)mount proc/sys/dev-depmod -a && modprobe virtio_blk # must load virtio_blk to get /dev/vda+# virtio_blk is built-in to the custom kernel (no need to modprobe).find /dev/vda or /dev/vdb → PERSIST_DEVmount -t ext4 PERSIST_DEV /mnt/persist # mkfs.ext4 if neededmkdir -p /mnt/persist/upper /mnt/persist/work /mnt/overlaymount -t overlay overlay -o lowerdir=/,upperdir=...,workdir=... /mnt/overlay-exec chroot /mnt/overlay /init --main+exec /bin/busybox chroot /mnt/overlay /init --main# FALLBACK (if overlay failed): exec /init --main ← runs without persistence```-**Critical bug to avoid**: The fallback at end of Phase 1 must NOT be `exec chroot /mnt/overlay /init --main` — if overlay failed, `/mnt/overlay` may not exist → kernel panic. Must be `exec /init --main`.--**Critical bug to avoid**: vmlinuz-virt and modules in initrd.img MUST come from the SAME rootfs-builder Docker stage. The Dockerfile copies vmlinuz from `rootfs-builder /boot/vmlinuz-virt` (NOT from the netboot downloader stage). Mismatched kernel/modules = `modprobe virtio_blk` silently skipped = no block device = no storage mount = kernel panic.+**Critical bug to avoid**: the chroot must use `/bin/busybox chroot` explicitly. Phase 1 runs before busybox applet symlinks are installed, so a bare `chroot` is not in PATH and the script exits with code 127, which the kernel interprets as init dying → panic on every boot.### Phase 2 (`--main` flag, runs inside chroot overlay)```bashboot_stage "Initializing system..."# mount proc/sys/devtmpfs/devpts/tmpfs/cgroup2boot_stage "Loading kernel modules..."-# depmod + modprobe (virtio_net, virtio_blk, fuse, tun, veth, bridge, overlay, ...)+# Most networking/fs is =y in our custom kernel; only 9p* are still =m.boot_stage "Waiting for network..."-# wait for eth0 with IP (loop), set up resolv.conf (8.8.8.8, 1.1.1.1)-boot_stage "Network found" or boot_stage "Network found" (after timeout)+# wait for eth0 with IP (loop), set up resolv.conf (10.0.2.3, 8.8.8.8, 1.1.1.1)+boot_stage "Network found"boot_stage "Configuring containers..."# sysctl, /etc/subuid, containers.conf, storage.conf, registries.confboot_stage "Starting SSH..." # only if ssh=1 in kernel cmdline# dropbearkey + dropbearboot_stage "Almost ready..."-# MOTD generation with internet check, bash profile + aliases-# resize daemon: background loop reads RESIZE from /dev/hvc0, calls stty on /dev/ttyAMA0+# MOTD generation with async internet check, bash profile + aliases+# resize daemon (background): reads RESIZE from /dev/hvc1, runs stty on /dev/hvc0# write podroid-login wrapper: #!/bin/bash; cat /etc/motd; exec script -q -c 'exec /bin/bash --login' /dev/nullboot_stage "Ready!"rm -f /run/boot_stage-sleep 2 # ← CRITICAL: let boot monitor read "Ready!" before bridge steals socketwhile true; do- /sbin/getty -n -l /usr/local/bin/podroid-login 0 ttyAMA0 xterm-256color+ /sbin/getty -n -l /usr/local/bin/podroid-login 0 hvc0 xterm-256colorsleep 1done```@@ -295,15 +292,15 @@ Keyboard → TerminalView → TerminalSession.write() → PTY master fd↓podroid-bridge stdin (PTY slave)↓- serial.sock → ttyAMA0 in VM-VM output → ttyAMA0 → serial.sock → bridge stdout → PTY slave → TerminalEmulator → TerminalView+ terminal.sock → /dev/hvc0 in VM+VM output → /dev/hvc0 → terminal.sock → bridge stdout → PTY slave → TerminalEmulator → TerminalViewResize → TerminalView.updateSize() → TIOCSWINSZ on PTY → SIGWINCH → bridge- → bridge reads TIOCGWINSZ+ → bridge debounces 200 ms → TIOCGWINSZ→ writes "RESIZE rows cols\n" to ctrl.sock- → VM daemon reads /dev/hvc0- → stty rows N cols M < /dev/ttyAMA0+ → init resize daemon reads /dev/hvc1+ → stty rows N cols M < /dev/hvc0→ Linux SIGWINCH to VM fg process group-Mouse → TerminalView touch handler → PTY → bridge → serial → VM+Mouse → TerminalView touch handler → PTY → bridge → terminal.sock → VM```### PodroidQemu Key Methods@@ -356,15 +353,16 @@ arrow(final): if mod==1 → "\x1b[$final" else → "\x1b[1;$mod$final"## podroid-bridge.c-- **Purpose**: Relay PTY (Termux-allocated) ↔ `serial.sock` (QEMU serial)-- **Arguments**: `bridge_exe serial_sock_path ctrl_sock_path`+- **Purpose**: Relay PTY (Termux-allocated) ↔ `terminal.sock` (QEMU virtio-console / hvc0).+- **Arguments**: `bridge_exe terminal_sock_path ctrl_sock_path`.- **STDERR silenced** immediately via `dup2(/dev/null, STDERR_FILENO)` — bridge runs as TerminalSession subprocess so stderr IS the PTY.- **`cfmakeraw()`** on own stdin (VM's getty handles echo/line editing).-- **serial.sock retry**: 50 attempts × 200ms = 10s max.-- **ctrl.sock retry**: 50 × 100ms = 5s max; lazy reconnect on each SIGWINCH if not yet connected.-- **`filter_queries()`**: Intercepts `ESC[18t` / `ESC[19t` (xterm window size queries from busybox `less`), responds locally with fake size (using `TIOCGWINSZ`), strips bytes — prevents garbage in terminal output.-- **`send_resize()`**: On SIGWINCH, reads new size via `TIOCGWINSZ`, writes `RESIZE rows cols\n` to ctrl.sock.-- **select timeout**: 50ms (allows SIGWINCH handling without blocking).+- **terminal.sock retry**: 50 attempts × 200 ms = 10 s max.+- **ctrl.sock retry**: 50 × 100 ms = 5 s max; lazy reconnect on each SIGWINCH if not yet connected.+- **`send_resize()`**: reads new size via `TIOCGWINSZ`, writes `RESIZE rows cols\n` to ctrl.sock.+- **SIGWINCH debounce**: every signal just refreshes a `clock_gettime(CLOCK_MONOTONIC)` timestamp; the actual `send_resize()` only fires once the burst has been quiet for `RESIZE_DEBOUNCE_MS` (200 ms). Collapses the ~25 per-frame layout changes during an Android keyboard slide into a single shell prompt redraw.+- **select timeout**: 50 ms — wakes the loop frequently enough to fire the debounced resize on schedule.+- The old `filter_queries()` intercept (`ESC[18t`/`ESC[19t` xterm size queries) is gone — virtio-console reports real `TIOCGWINSZ` inside the guest, so apps don't need the workaround.---