ADR 0006: Simplify `periphemu` Bootstrap

Status

Accepted

Date

2026-06-08

Context

startup/servers.lua historically called periphemu.create four times on computer 0: a top modem, two computer peers at ids 1 and 2 (both labelled Trap in saved per-computer config), and a router peer at id 10. In CraftOS-PC GUI mode this opened four windows on every launch (Computer 0, two duplicate Traps, and Router).

That setup predates the current workflow:

The install path is now manifest-driven (install.lua v3.0.0 fetches files listed in manifest.json and writes a marker at /trapos/manifest.json). The legacy apis/, programs/, servers/, install.lua files hand-copied into each per-computer dir are obsolete.
Local verification runs headless through just test against scripts in tests/; the smokes don't need persistent emulated peers.
The duplicate Trap label and persistent stale computer state across versions caused recurring confusion.

The CraftOS-PC data directory (~/Library/Application Support/CraftOS-PC/) had also accumulated years of stale state in computer/, old_computer/, and per-id config/*.json files (labels like test, two Traps, etc.).

Decision

startup/servers.lua attaches only a top modem under periphemu:

if periphemu then
  periphemu.create('top', 'modem');
end

Extra emulated computers are spawned manually from the CraftOS-PC shell when actually needed (e.g. periphemu create 10 computer to bring up a router peer for cross-VM testing). The pattern is documented in docs/periphemu.md.
Wiped the live CraftOS-PC data dir back to a clean slate (one-time, manually). Removed computer/, old_computer/, and all per-id config/*.json. Preserved config/global.json (user-level CraftOS-PC settings). A full pre-wipe backup lives at ~/Backups/craftos-pc-2026-06-08/CraftOS-PC/ outside any repo.

Consequences

craftos (GUI) now opens a single unlabelled Computer 0 window with a top modem attached. No more duplicate Trap windows.
just test is unchanged: the headless smokes set up whatever they need per script.
New contributors and fresh machines get a clean state by default — no inherited per-computer config to chase.
Cross-machine testing now requires an explicit periphemu create call from the shell rather than being implicit on boot. That is a deliberate trade-off: the cost is one extra command when you genuinely need a peer; the benefit is no surprise windows and no persisted ghost VMs.
The if periphemu then guard (called out in CLAUDE.md) is preserved, so in-game behavior is unchanged.

Future Work

If tests/ grows a multi-VM scenario, drive peer creation from the test script itself (each tests/*.lua already owns its setup) rather than re-adding peers to startup/servers.lua.
Consider a small programs/spawn-peer.lua wrapper to make ad-hoc shell incantations friendlier (spawn-peer 10 instead of periphemu create 10 computer). Not done now — premature for current usage.

3.0 KiB Raw Blame History

ADR 0006: Simplify periphemu Bootstrap