cleonos/docs/stage12.md

# CLeonOS Stage12

## Stage Goal
- Add user execution manager in CLKS (`userland manager`) for shell launch lifecycle.
- Connect user execution state to scheduler via a dedicated kernel task (`usrd`).
- Extend syscall ABI with user execution telemetry (`ready/requested/tries/ok/fail`).
- Expose userland status as a first-class kernel service (`CLKS_SERVICE_USER`).

## Acceptance Criteria
- Kernel boots and prints `CLEONOS STAGE12 START`.
- Userland logs include:
  - `USERLAND FRAMEWORK ONLINE`
  - `SHELL ELF READY`
  - `SHELL EXEC REQUESTED`
- Scheduler task count increases by one (`usrd` added).
- Service framework includes USER service (service count increases).
- Stage12 syscall probe logs include:
  - `USER SHELL_READY`
  - `USER EXEC_REQUESTED`
  - `USER LAUNCH_TRIES`
  - `USER LAUNCH_OK`
  - `USER LAUNCH_FAIL`
- System remains stable in idle loop with periodic task dispatch logs.

## Build Targets
- `make setup`
- `make userapps`
- `make iso`
- `make run`
- `make debug`

## QEMU Command
- `qemu-system-x86_64 -M q35 -m 1024M -cdrom build/CLeonOS-x86_64.iso -serial stdio`

## Common Bugs and Debugging
- USER syscall counters always 0:
  - Check syscall IDs 16..20 match in kernel and user headers.
- Service count did not increase:
  - Confirm `CLKS_SERVICE_USER` is registered in `clks_service_init()`.
- `SHELL EXEC REQUEST FAILED`:
  - Ensure `/shell/shell.elf` exists in ramdisk and ELF inspect passes.
- `usrd` task missing:
  - Verify `clks_scheduler_add_kernel_task_ex("usrd", ...)` in `kmain`.
- Boot regression after Stage12 merge:
  - Re-check init order: FS -> userland init -> driver/kelf/exec -> scheduler -> service -> interrupts.