The active interface is the Ring 3 serial shell. Normal builds keep development
syscall/keystroke tracing out of the interactive session. Startup and failure
messages remain available; validation-boot retains the detailed proof trace.
Start with make run. This serial-only QEMU session does not capture the mouse.
To quit the emulator, press Control+A, release both keys, then press x. These
are host emulator controls, not a guest shutdown command.
This stops QEMU immediately. It does not wait for guest services, drain the
device cache or prove that recent file writes survived. The shell has no guest
exit, shutdown or reboot command yet; do not treat closing the VM window,
Control+A then x, QMP quit or a test harness's terminate() as such a
command. After an unexpected host stop, use the documented storage inspection/
recovery path before assuming the latest mutation was durable. The explicit
QMP guest-shutdown event required by the malformed-kernel-ELF test proves only
that loader rejection asked the guest to stop; it is not a normal shell session
shutdown or a filesystem durability proof.
The input line is capped at 80 printable ASCII bytes. Left/Right, Home/End, Backspace and Delete edit around a cursor; Up/Down traverse eight remembered commands and restore the unfinished line when returning to the newest slot. Tab extends a unique or shared prefix of built-in command names; it does not complete paths. Escape alone cancels the current line after a short prefix timeout; Control+C also cancels when the host terminal forwards that byte. Unknown escape sequences are dropped, and an incomplete sequence cannot submit the line. The shell enables bracketed paste and converts pasted newlines/tabs to spaces; a paste over 512 bytes cancels and discards the rest through its end marker. A host terminal that ignores bracketed-paste negotiation sends raw newlines as Enter, so paste one line at a time in that environment.
The serial renderer uses ANSI cursor movement for edits and background-output
redraw. A basic log viewer may show those control bytes literally even though
the actual terminal presents one editable line. Control+A is reserved by QEMU's
default serial multiplexer; use the Home key for shell navigation in make run.
Type one command and press Enter. Commands use plain arguments, not shell quoting,
pipelines or redirection. The current namespace is rooted at / with no cd.
| Command | Behavior |
|---|---|
help |
Bounded usage lines for every available command |
clear |
Clear the serial screen and move the cursor home |
uname |
Version, architecture and experimental ABI |
echo TEXT |
Print text |
net |
Report whether network configuration is available; no new ping |
mem |
Read allocator counters and consistency from /MEMORY.STATUS |
ls [PATH] |
List / or the specified directory |
cat PATH |
Read a file |
stat PATH |
File information |
touch PATH |
Create a missing file |
write PATH TEXT |
Replace file contents |
append PATH TEXT |
Append exact text, without an automatic separator |
mkdir PATH |
Create a directory |
rm PATH |
Remove a file or empty directory |
run init |
Start the built-in example process |
run init hold |
Keep the example running for lifecycle testing |
ps |
Show jobs owned by this shell |
kill JOB |
Stop the named shell job |
wait JOB |
Reap a finished job; report if it is still running |
Writable files belong below /USER/. The current file budget is 512 bytes and
the pathname budget is 64 bytes. Paths are case-insensitive and accept ASCII
letters, digits, ., _ and - within components. Dot-navigation components,
duplicate separators, trailing separators and spaces in names are rejected.
/MEMORY.STATUS is reserved and read-only. Job numbers come from run/ps, not
the task ID or runtime PID.
The current encoding profile is printable ASCII for command input, file
names and display data. Filename comparison folds ASCII letter case under the
canonical path policy; no Unicode normalization or locale-specific comparison
is offered. When cat reads file bytes, LF separates displayed lines; every
other control byte, DEL and byte above 0x7e displays as ?. Console syscalls
apply the same substitution before data reaches presentation, and the serial
output sink applies it again. Only explicit presentation operations (clear,
input redraw and paste-mode negotiation) emit terminal control sequences.
Displayed file/process data therefore cannot clear
the screen, reposition the cursor or manufacture input through an escape byte.
An asynchronous output line temporarily clears the visible prompt and redraws
the shell-owned pending input afterward. The pending command is never executed
because output arrived. Encoding, editing and completion are intentionally
bounded; quoting, filename completion and full terminal-emulator compatibility
are separate work.
help
mem
write /USER/TEST.TXT hello
cat /USER/TEST.TXT
run init hold
mem
ps
kill 1
wait 1
mem
clear
echo terminal ready
Use the actual printed job number if it is not 1. Memory usage should rise while
the example is live and return after teardown. mem counts managed physical
frames, including page tables; it is not total hardware memory or a per-process
memory profiler. See the memory contract.
This remains an experimental console OS, not a complete everyday shell. General program launch, working-directory navigation, quoting, pipelines, redirection, interactive job control, broader terminal escape compatibility and a supported shutdown interface remain future work. The graphical UI remains deferred behind foundation correctness. Familiar command names describe their documented operations; they do not imply Linux/POSIX compatibility.
Normal acceptance uses these same visible echoes and outputs to check help, network configuration, read-only memory diagnostics, canonical paths, process cleanup, persistent file I/O and clear/redraw behavior. It rejects development trace leakage and missing or out-of-order responses. The separate validation suite continues to prove the lower-level mechanisms with detailed serial evidence.