SchOS/docs/architecture/init.md

schinit — PID 1 as a role

Shaped after launchd rather than sysvinit, and it breaks one Unix rule on purpose.

---

The rule that was changed

Unix's rule is PID 1 is special and must never die. Every init since 1975 has honoured it by being careful.

SchOS's rule instead: PID 1 is a role. The kernel guarantees the role is filled. The role's state lives outside whichever process currently holds it.

"Must never die" is not a mechanism — it is a hope, and the thing it hopes about is the one program on the machine with no supervisor. What replaced it is four pieces: a split by role, state in /proc, a heartbeat, and a kernel that re-execs PID 1 in place instead of panicking.

The arrangement it is not

The obvious design — init 1 starts init 2; if init 1 dies, init 2 revives it — was tried on paper and rejected. The failures are worth keeping, because they are the traps any redundant-supervisor scheme falls into:

• It defends against an attack that already fails. Userspace cannot kill PID 1 here: init_ignores() drops SIGKILL to initproc.
• Init 2 is the same binary. If init 1 died of its own bug, init 2 reaches the same line and dies the same way — faster, having just watched the input that caused it.
• The chain has no bound. Init 2 makes init 3 by symmetry. With a cap, the cap is the real design and the chain is decoration.
• Two supervisors is split brain. Both hold the job table, both see a pid exit, both restart it. Now the console shell exists twice, both reading /dev/console. That is worse than no redundancy: it corrupts the state it was added to protect.
• It only detects death. The common way an init breaks is hanging, and wait() never returns for a process that is merely stuck. The scheme is armed against the rare failure and blind to the likely one.

---

The split

schinit (PID 1)	Reaps children, holds the job table in memory, supervises exactly one child. No manifest parsing, no filesystem walking after boot, no allocation. About 520 lines. Its entire job is to be too boring to fail.
schinitd (PID 2)	Manifests, respawn policy, backoff, socket sections, and the eventual schinitctl. This is where the bugs will be, and it is restartable.

The detail that makes this work, and that two copies of one program cannot have:

Jobs are forked by PID 1, not by schinitd. schinitd decides and asks; PID 1 acts. Every job on the machine is a child of PID 1 at all times, so schinitd crashing orphans nothing, reparents nothing and restarts nothing. It comes back, reads the state, and finds the world exactly as it left it.

So there are still two processes with one watching the other — but their roles are different, which is what stops the second being a second copy of the first one's bug.

The protocol

include/schinit.h. Every message is exactly one struct, and PID 1 reads sizeof(struct) or nothing: no length prefix to get wrong, no partial-message state machine, and no allocation in the process that must not fail. The socket is a socketpair inherited as fd 3.

To PID 1		To the supervisor
HELLO	version handshake	WELCOME	PID 1's version, echoed
SPAWN	start this job	SPAWNED	the pid, or negative
PONG	answer to a ping	EXITED	a child was reaped
		PING	answer within the deadline

---

State outside the process

/proc/schinit is the serialised job table: a generation, the supervisor's pid, then one line per running job — cookie, pid, start tick, label.

It is written by PID 1, because PID 1 is the process that cannot lose it, and written whenever the table changes rather than generated on read — a procfs generator runs in the kernel, and the kernel has no business walking this program's memory.

procfs rather than a file on disk for four reasons: it survives a read-only root, it survives a full disk, it costs no I/O, and it is already the pattern this kernel uses for exactly this kind of question.

A resurrected supervisor reads it back and adopts what is already running instead of starting it again. The side benefit is that the job table is no longer invisible: cat /proc/schinit is the observation.

---

The heartbeat

PID 1 pings the supervisor every 2 seconds and expects an answer within 10. This is the failure the sibling-init scheme cannot see: a supervisor that is stuck rather than dead never causes a wait() to return.

Silence from schinitd means PID 1 replaces it — without waiting for the corpse, because kill() on a wedged process never completes and PID 1 waiting for it would be the hang it was trying to detect.

Silence from PID 1 is what the kernel change exists for.

---

proc_reincarnate()

exit() on initproc used to panic("init exiting"). Now the kernel tears down the address space, keeps the struct proc, keeps pid 1, and re-execs /bin/schinit in place with a generation counter passed in.

No init 2, no init 3, and no reparenting problem — because pid 1 never stops being pid 1. Every orphan the kernel already reparented to initproc is still correctly parented, initproc is still the pointer it always was, the children survive, and the state is in /proc/schinit.

Three details in that path are not obvious and each was a bug first:

• exec() returns 0 on success. It does not fail to return, so the code after it is the success path, not an error path to panic in.
• killed has to be cleared first, or the new image exits before its first instruction — five generations in microseconds.
• exec preserves descriptors, so the new PID 1 inherits the old supervisor's socket and never sees the hangup that tells it the supervisor is gone. It has to be closed deliberately.

The escalation ladder

Generation	What happens
1	Normal boot.
2–3	Re-exec in place. Log it, keep the jobs, carry on.
4	Re-exec, but ignore /etc/schinit entirely and start only a console shell. A manifest that kills init must not kill it forever.
5	Stop. panic().

The last row is the honest one. A machine that cannot hold PID 1 up five times is not a machine that should keep trying, and PSOGM renders a stop code, a call chain and a QR code of the whole report — a far better end than a silent loop.

Both paths are tested by doing them, not by reasoning

Two sysrq keys exist for this:

sysrq i	Kills PID 1. Signals cannot — init_ignores() drops them — so this sets killed directly, which is the kernel deciding rather than userspace asking.
sysrq w	Wedges schinitd on purpose, so the heartbeat timeout is exercised. There is no way back from it; reboot afterwards.

init: pid 1 exited with status 9 -- reincarnating, generation 2
schinit: reclaimed 2 running job(s) from /proc/schinit
schinit: SchOS process 1, generation 2 (reincarnated)
schinitd: adopting os.schos.console-shell
schinitd: adopting os.schos.tty2-shell

The shell being typed into keeps its pid across the death and rebirth of PID 1.

---

Why launchd

Demand launching. The supervisor holds the listening socket or watches the path, and starts a job when something actually arrives.

That inverts the dependency graph. A job stops needing to declare what must be running before it, because the thing it depends on answers on first use — and runlevels stop being a concept at all.

SchOS has the two pieces that make it possible: AF_UNIX sockets and a real /proc. Socket sections are parsed and remembered but not yet held, so this is still the reason for the shape rather than a feature of it.

Constraints on the programs themselves

Both link against lib/, which is raw syscall stubs. There is no libc here — no malloc, no printf, no strlen. Everything is static storage and hand-rolled, which is also why the limits are constants rather than growable:

MAXJOBS	32
MAXARGS	16
manifest size	4 KB, read into one static buffer

Bootstrap

Before any job runs, PID 1 creates the device nodes and mounts that a job needs in order to have somewhere to send its output. This cannot itself be expressed as a job without a bootstrapping problem, which is why it is a function and not a manifest.

Console first, as fd 0/1/2, so every message after it has somewhere to go. Then the /dev nodes — minor numbers under major 1 follow Linux's mem-major layout where it costs nothing (null=2, zero=5, full=7, random=8, urandom=9) — then /dev/input/event0 and event1, the raw disks, and /proc.

Two details that look like carelessness and are not:

The nodes are created unconditionally, including for absent hardware. Opening /dev/hdb with no drive present fails with ENXIO, which is a better answer than a missing path. It matters more than it looks: with no node, echo x > /dev/hdb silently creates an ordinary file of that name and appears to succeed.

The mknod'd /proc files still happen and are then covered by the mount. A failure to mount degrades to the old behaviour rather than losing /proc entirely.

Job manifests

Held by schinitd, not by PID 1. Every *.job file in /etc/schinit is loaded at boot, found with getdents64 rather than a hardcoded list — so dropping a file in the directory is all it takes to add a job.

Sectioned key = value, # starts a comment, keys are case-insensitive (a manifest may say KeepAlive, keepalive or KEEPALIVE; keys are for humans and this is not a language).

Key
Label	A reverse-DNS name, as launchd uses. Identity, not a path.
Program	The binary to execute
Args	argv, space separated. argv[0] is conventionally the basename, so Args = sh for /bin/sh
RunAtLoad	Start it when schinit loads
KeepAlive	Restart it when it exits — unless it exits SCHINIT_EXIT_NORESTART, below
Disabled	Load it but do not start it
ThrottleInterval	Seconds between respawns (default 1)
ControllingTerminal	Claim the console
StandardIn / StandardOut / StandardError	Paths to open as fd 0, 1, 2
[Socket <name>] → Path	Parsed, recorded, not yet honoured

Unknown keys and unknown sections are ignored rather than fatal. A manifest written for a newer schinit must not stop this one booting the machine.

Starting a job

Each job gets its own session (setsid), so it cannot reach back and signal the rest of the system through a shared controlling terminal.

That is exactly what makes ControllingTerminal necessary, and the interaction is the least obvious thing in the program:

A fresh session has no controlling terminal, and a terminal only delivers input to the foreground process group it is tracking. Without ControllingTerminal = yes, the shell comes up, echoes every keystroke through the line discipline, and executes none of them — which looks like a hung shell and is really a terminal that is not listening to it.

It is off by default. A daemon has no business seizing a terminal, and launchd's model is that the terminal is something a job asks for.

exec.c enables the Linux ABI automatically for musl binaries, so a job must not call enable_linux_abi() itself — it would renumber the syscalls the child still has to make.

Supervision

PID 1 loops on wait() and reports every reaped pid to the supervisor.

It reaps whatever exited, including processes reparented here when their own parent died. Those are not jobs, and that is the whole handling they need.

A KeepAlive job is restarted by the supervisor asking PID 1 to spawn it again, subject to ThrottleInterval — a job that exits immediately and forever would otherwise spin the machine. launchd defaults to 10 seconds; 1 is enough here, where the common case is a shell someone just exited on purpose and expects back.

One exit status the supervisor reads

Throttling stops a restart loop from costing CPU. It does not stop it being a loop, and a job that can never succeed on this machine will print its reason every ThrottleInterval for the rest of the uptime — measured at fifteen spawns in forty-five seconds for vgpud on a machine with no virtio-gpu.

So a KeepAlive job that exits SCHINIT_EXIT_NORESTART (78, sysexits.h's EX_CONFIG) is not restarted, and the supervisor says which job stopped and why:

vgpud: no virtio-gpu on this machine
schinitd: os.schos.vgpud has nothing to do on this machine; not restarting

The distinction it draws is the right one: the status is wait(2)-encoded, so a job that was killed or faulted has a signal in the low bits, never matches, and comes back exactly as KeepAlive promises. Only a job that exited deliberately, saying this machine is not one it can run on, is believed.

This is not a new manifest key and there is no policy knob. The wait status has always travelled from PID 1 to the supervisor inside struct schinit_reply; note_exit() simply stopped discarding it.

The fallback

With no manifests found, the supervisor says so and starts /bin/sh on the console anyway.

An unbootable-looking machine because a manifest was missing would be a poor trade for purity.

---

What it does not do

• Socket activation is not implemented. The manifest key is parsed and the path remembered; nothing holds the socket, so demand launching — the entire reason for copying launchd — does not happen yet.
• No schinitctl. Jobs cannot be started, stopped or reloaded at runtime. They can now be inspected, through /proc/schinit, which is half of it.
• No dependency ordering of any kind, deliberately — demand launching is meant to make it unnecessary, and until that exists there is nothing in its place either.
• No log capture. StandardOut is a path, so a job's output goes wherever the manifest says and nothing aggregates it.
• /proc/schinit records running jobs, not the whole table. A job that is loaded and stopped is not in it, so a resurrected supervisor learns what is alive and re-reads the manifests for everything else.
• A new compatibility surface exists between PID 1 and PID 2 that did not before, and the tree's own ../plan/schapi.md §3 spends a section warning about exactly those. SCHINIT_PROTO is versioned in the handshake, which is the least that can be done about it.
• 32 jobs, 16 arguments, 4 KB manifests, all compile-time.