Module supcmd 

The supervisor’s command channel wire format.

ONE definition. This lived in three services at once (supervisor, control, shell) - three copies of a protocol, which is the second-truth problem this project rejects everywhere else (26.4, Commandment III). A drifted copy would not fail loudly; it would send a byte the supervisor reads as a different opcode.

The supervisor’s endpoint receives two kinds of message, told apart by the first byte:

  death notice   "pong" 0 how...               <- kernel-generated; a name, [a-z0-9-], then how it
                                                  ended (`death`, CLAUDE.md 6.2 amendment 2026-10-11)
  command        0x01 op <core u32 LE> name    <- 0x01 cannot begin a name
                                   name may be followed by NUL-separated PEER names

Choosing an impossible first byte means a death notice needs nothing to set it apart: it still begins with the name, as it always has (what follows the NUL is death’s, added 2026-10-11), so the two are unambiguous without the kernel learning anything about commands.

Constants

DEATH

How did this service last end? Read only: [MARKER, DEATH, name...], answered with [OK, since u32 LE, deaths u32 LE, secs u32 LE, how, kind, addr u64 LE, by_len, by...] - since: when this supervisor began its record; deaths: the notices it has read for this name since then (0 = none, and the rest is zero); then the newest one: its uptime second, how it ended (death::KILLED, death::FAULT), the fault kind and address, and the name of the task that called kill. The kernel says how, in the death notice; the supervisor only keeps the newest per name. ask.

DEVICES

Which devices does the supervisor drive? Read only: [MARKER, DEVICES], answered with [OK, count, entries...] - per entry b'H', the spawn row’s device word (u32 LE, hwclass), the service’s name (length byte, bytes); or b'U', a USB device it starts a driver for (vid u16 LE, pid u16 LE, attached 0/1, the reporting host’s name, the driver’s name, each a length byte and bytes). The hardware utility’s DRIVER column (docs/hardware-design.md).

EVENTS

What has happened to the devices this supervisor drives since it started. Read only: [MARKER, EVENTS], answered with [OK, since u32 LE, recorded u32 LE, count, entries...] - since: when this supervisor began its record (after its boot spawns), in seconds of uptime; recorded: every event noted, so recorded - count were overwritten; per entry the uptime second (u32 LE), an EV_* code, the USB vid and pid (u16 LE each, 0 for a driver event), and the driver’s name (length byte, bytes). hardware events.

EV_ATTACHED

A USB device was reported attached and its driver started.

EV_DETACHED

A USB device was reported gone and its driver stopped.

EV_RESTARTED

A device’s driver died and was restarted.

EV_RESTART_FAILED

A device’s driver died and its restart failed.

EV_START_FAILED

A USB device was reported attached and its driver could not be started.

EV_SWEPT

A device’s driver was found dead by the sweep - its death notice never arrived - and restarted.

FAILED

HANDOVER

Replace a running installed package with another version WITHOUT STOPPING IT: [MARKER, HANDOVER, "publisher/name version"]. The supervisor checks the new version, starts it beside the running one, and tells the running one to hand over (gs::handover). Where either version cannot - it is not running, or a contract does not declare handover - it stops the old and starts the new, as INSTALL after UNINSTALL would. Answered [OK, how], how b'H' handed over live or b'R' restarted, or [FAILED, reason...].

INSTALL

Start an installed package: [MARKER, INSTALL, "publisher/name version"]. The supervisor checks the fetched copy from the disk, grants the send peers its grant file names and its contract requests, and starts it under the task name publisher/name (services/supervisor/src/installed.rs). Answered [OK], or [FAILED, reason...] - the reason is a sentence.

INSTALLED

Which packages has this supervisor started from the disk? Read only: [MARKER, INSTALLED], answered with [OK, count, (len, name, running 0/1)*]. godspeed list installed.

MANAGED

Which services does this supervisor keep running right now? Read only: [MARKER, MANAGED], answered with [OK, count, (len, name)*] - the MANAGED services this build carries and wants now (a USB device’s driver only while its device is attached). The question ask’s health answer turns on: a service on this list that is not running is down when it should be up.

MARKER

First byte of a command. Not a legal first byte of a service name.

MAX

Longest command payload: opcode + core + a name and its peers, each at most NAME_MAX bytes.

OK

Reply status, one byte, so a caller can log the truth rather than assume success.

RESTART

Kill if alive, then spawn.

SPAWN

Spawn a service that is not running.

UNINSTALL

Stop an installed package and forget it: [MARKER, UNINSTALL, "publisher/name"]. [OK], or [UNKNOWN] when it was not installed.

UNKNOWN

WHY

Why is this driver’s device handled as it is? Read only: [MARKER, WHY, name...], answered with [OK, text...] - the reason the supervisor keeps beside the spawn rows - or [UNKNOWN] for a service with none recorded. hardware why (docs/hardware-design.md 11).

Functions

encode

Build MARKER op <core> name[\0peer]* into buf, returning its length.