CHANGELOG.md

# TOS Changelog

All notable changes to TOS are recorded here. Versions follow a loose
SemVer: MAJOR.MINOR.PATCH. Codenames are tracked in `Codenames.txt`.

---

**Contents:** [Unreleased](#unreleased) · [v1.5.0 "Aletheia"](#v150-aletheia--the-os-that-fits-in-the-machine-you-have) · [v1.4.0 and earlier](#v140-and-earlier)

## Unreleased

Everything since v1.5.0, in 26 rounds of work:

- [A second optimization pass, past the render path](#a-second-optimization-pass-past-the-render-path)
- [The release build renames its own local variables now](#the-release-build-renames-its-own-local-variables-now)
- [The render path re-required its own helpers every frame](#the-render-path-re-required-its-own-helpers-every-frame)
- [A broken source file stripped exactly as cleanly as a good one](#a-broken-source-file-stripped-exactly-as-cleanly-as-a-good-one)
- [The open queue, worked through](#the-open-queue-worked-through)
- [Package identity, and dependencies across sources](#package-identity-and-dependencies-across-sources)
- [A kernel-side network wait could only time out on real hardware](#a-kernel-side-network-wait-could-only-time-out-on-real-hardware)
- [Component methods are callable tables, not functions](#component-methods-are-callable-tables-not-functions)
- [Eleven fixes from a second cloud session](#eleven-fixes-from-a-second-cloud-session)
- [Fifteen fixes from a cloud session, re-verified before landing](#fifteen-fixes-from-a-cloud-session-re-verified-before-landing)
- [Every component call checked against the mod's own source](#every-component-call-checked-against-the-mods-own-source)
- [Three shims, and the kernel hook a sandbox could forge](#three-shims-and-the-kernel-hook-a-sandbox-could-forge)
- [A loot disk offers to install itself](#a-loot-disk-offers-to-install-itself)
- [The ADMIN/ROOT split made real](#the-adminroot-split-made-real)
- [A mesh message is delivered, or still held](#a-mesh-message-is-delivered-or-still-held)
- [A mount lands where TOS says, not where the disk says](#a-mount-lands-where-tos-says-not-where-the-disk-says)
- [A redirect that failed said it had written](#a-redirect-that-failed-said-it-had-written)
- [A trusted neighbour cannot fill a relay](#a-trusted-neighbour-cannot-fill-a-relay)
- [/var/pkg belongs to the package manager](#varpkg-belongs-to-the-package-manager)
- [One 8 KB packet, 240 KB of heap](#one-8-kb-packet-240-kb-of-heap)
- [The disk folds what the ACL compares](#the-disk-folds-what-the-acl-compares)
- [The RAM pass: measured, then fixed](#the-ram-pass-measured-then-fixed)
- [A pentest, and the sandbox's side doors](#a-pentest-and-the-sandboxs-side-doors)
- [A crash you can read from across the room](#a-crash-you-can-read-from-across-the-room)
- [A failed write changes nothing](#a-failed-write-changes-nothing)
- [Findable](#findable)

### A second optimization pass, past the render path

The first optimization pass covered the render loop and the command executor. This one went further: a sweep of every kernel/net file and shell UI input handler not yet reviewed, looking for the same two things OpenComputers' per-tick budget punishes — an uncached `require()` repeated on a path that fires often, and a string built one character at a time.

- **Two network challenge/response functions re-required `kernel.crypto` on every call**, in `kernel/net/init.lua`'s inbound-`CHALLENGE` handler and `verifyPeer` — shadowing a module-level `crypto` already cached once in `net.init` and used everywhere else in the same file. Both now use that existing reference directly.
- **Every mouse click and scroll re-required three modules.** `shell/panels/mouse.lua`'s `M.handle` is the entry point for every raw touch/drag/drop/scroll signal, and on a box without the mouse driver installed — the common case, since it's an Optional Utilities add-on, not base image — that is *every* mouse event on the machine. `shell.panels.home` and `shell.panels.apps` were each re-required at two call sites (click and scroll); the module's own `uptime()` helper re-required `computer` on every call for the same reason, used by the probe this entry point runs first. All four, plus `uptime`, now use the same lazy-cache idiom the file already uses for `shell.panels.textcol` two lines above the first of them — which is what made the other four read as an oversight rather than a different choice.
- **A security-gate check re-required the command registry on every dispatch.** `shell/panels/helpers.lua`'s `M.tierRefusal` — the #SEC fix from a prior pentest round that makes `watch` and the tape toolbox enforce the same tier check the executor does for an ordinary command — re-required `shell.panels.commands` every time `watch` or the tape toolbox ran a named sub-action. Cached the same way, kept lazy (not top-level: `commands.lua` and friends require `helpers.lua` back, so a top-level require here would be the circular load this was always avoiding).
- **A dialog's non-coroutine fallback re-required `computer` every polling iteration.** Low real-world impact (the good path, inside a coroutine, never reaches this branch at all), but free to fix the same way — cached without `pcall`, deliberately: the original let a missing module raise here, and a cache must not quietly turn that into a silent infinite wait instead.

Also measured, and deliberately left alone: a diagnostic-only string-concatenation loop in `screendump` (admin-invoked, bounded to a screen's row count — tens, not thousands — so the real cost is negligible, and touching it risks the one thing that command cannot afford, a subtly wrong byte in its own precision output).

Every fix re-ran its module's existing off-box tests clean, including the two most security-sensitive: the net challenge/response change against the full `test_net_*` suite, and the tier-gate change against `test_watch_tier.lua` and `test_dispatch_tier.lua`.

### The release build renames its own local variables now

The release has been comment-stripped and whitespace-minified for a while, but every local variable and function parameter still shipped under its full dev-source name — `recommendedMaxLength`, `trustedPublisherLabel`, that kind of thing — and this project's names run long, on purpose, because clarity was never rationed in TOS-Dev. That cost real bytes a machine reading the shipped code never benefits from, and the margin had gotten thin: 1907.2 KB used of the 1920 KB budget a 2 MB drive leaves after First Boot Setup, 12.8 KB of slack.

`build/strip.lua` gained `--minify-vars`, now the release default: every local and parameter is renamed to the shortest name that is still unambiguous in its scope, via a vendored, patched copy of [stravant/LuaMinify](https://github.com/stravant/LuaMinify) (MIT; `build/vendor/luaminify/`). Globals and table fields are never touched — only `local`s and parameters, the same way the existing comment-strip marker convention (`--!` keeps, `--` strips) never touches code either.

Patched, not used as-is, because upstream's parser predates Lua 5.3 and has no support for its bitwise/shift operators (`& | ~ << >>`) or floor division (`//`) — it hard-errors on all five, and `kernel/sha256.lua` alone uses every one of them in its core compression function. TOS requires Lua 5.3+ (5.2 is rejected at boot), so this is load-bearing cryptography, not an edge case. Also found and fixed a real upstream bug along the way: its minifying formatter called an undefined function on every `goto` or `::label::`, which `tos/kernel/init.lua`, `tos/shell/syntax.lua` and `tos/shell/panels/commands/admin.lua` all use — so upstream, unpatched, could not have minified this codebase at all, goto or no goto. And replaced its variable-renaming scheme entirely: upstream generates *random* 1-8 character names (built for obfuscation, where resisting pattern-matching is the point), which could make a 1-character original name *longer*. Renaming now picks the shortest not-yet-used name, deterministically, handed out by descending reference count so the busiest variable in a scope gets the shortest name available.

A second addition, `DedupStrings.lua` (not upstream — a TOS-only pass run between parsing and formatting), hoists a string literal repeated three or more times in one file into a single shared local: a string and a local holding that string are interchangeable in every expression position, so this can never change behaviour, independent of where in the grammar it sits. Two places a string-shaped thing appears in the AST without being a full string expression at all are never touched, by construction rather than by a special case that could be forgotten: a `{foo = 1}` table key is a bare Lua string with no expression node for the walker to find, and `f"str"` sugar-call syntax stores its argument as a raw token, not a `StringExpr`. Measured potential before writing it (~10 KB across the whole tree, by far the smallest of the three passes) kept the bar for attempting it deliberately low-risk rather than clever.

Together, the release drops from **1907.2 KB to 1313.2 KB — headroom goes from 12.8 KB to 606.8 KB**.

None of this was trusted on "it parses now" alone. Every new operator's precedence and associativity was checked by *running* representative expressions — including ones designed to prove explicit parentheses survive exactly when they have to and get dropped exactly when they are genuinely redundant — both before and after minification, comparing actual return values. The dedup pass's two exclusions were checked the same way: a string that would otherwise qualify is confirmed to survive untouched in both excluded positions, and the program's output is confirmed identical either way. The two highest-stakes modules in the kernel, `kernel/sha256.lua` and `kernel/ed25519.lua`, were minified and run differentially against their own unminified originals across multiple inputs, with identical results every time. `test_minify_vars.lua` (75 checks) pins all of it, and the real release build (166 files) passes the existing `load()`-must-compile gate and every manifest digest check clean.

### The render path re-required its own helpers every frame

An optimization pass over the hottest Lua paths — the render loop and the command executor — looking for exactly the things OpenComputers' per-tick budget punishes: a module re-`require()`d on every call instead of once, and a string built one character at a time.

- **Five redraw-time `require()` calls were uncached.** `kernel.ustr` was re-resolved with a fresh `pcall(require, ...)` on every width/fit call in `shell.panels.draw`, `desktop` and `home` — once per row or tile, on every redraw — while the identical module two lines away in `home.lua` (and in `shell.panels.ui`) was already cached after first resolution. `shell.panels.home` and `shell.panels.apps` were the same story in `draw.lua`: re-required at five and two call sites respectively, each reached on an ordinary redraw, instead of once. All six now share one cached accessor per module, matching the idiom `kernel.event`'s `getProc` and `kernel.process`'s `getScreen` already use for their own hottest loops.
- **The disk-free status-bar widget re-required `shell.panels.helpers` on every repaint** — every keystroke in the command line, not a throttled clock tick — while every sibling widget in the same table touched only already-cached locals. Hoisted to a module-level require.
- **A constant lookup table was rebuilt on every keystroke in the editor.** The eight-scancode "is this a navigation key" set in `shell.panels.events`'s edit-tab key handler was a fresh table literal on every `key_down`, with nothing in it ever varying between calls. Hoisted to a module-level constant.
- **The command-line tokenizer built every token one byte at a time.** `shell.panels.executor`'s quote-aware tokenizer (#SEC M4) used `cur = cur .. c` per character; Lua strings are immutable, so that reallocated the whole string-so-far on every character — O(n²) in a single token's length. Rewritten to accumulate whole spans (the run to the next delimiter, quote-close or escape) and join once per token with `table.concat`. Verified byte-for-byte identical to the original across 26 quoting/escaping/unterminated-input cases, including the ones most likely for a rewrite to get wrong: empty quoted strings, escaped quotes and backslashes, and a lone trailing backslash at end of input. `test_executor_tokenize.lua`, and the function moved to module scope (it closed over nothing from `M.build`) so it's reachable for that test at all.
- **`kernel.ustr.fit`'s byte-math fallback had the same per-character concat.** Hit mainly off-box and on exotic hosts — a real OC machine normally has the `unicode` library this falls back from — but the off-box suite exercises it on every run, and the fix is the same `table.concat` pattern for consistency with the above.

### A broken source file stripped exactly as cleanly as a good one

`build/strip.lua`'s tokenizer partitions bytes into "comment" vs "not a comment" — it never checked that what it emitted was still valid Lua, and neither did anything downstream of it. A source file that was already broken (an uncommitted syntax slip, a stray merge-conflict marker) stripped exactly as cleanly as a good one, because stripping never looked at syntax either way: a broken dev file could ship as a broken release file with no warning. Every stripped `.lua` file is now compiled with `load()` — the same compiler frontend that will load it for real on the target machine — before it is written, and a failure hard-stops the build, matching the existing #SEC M-13 precedent for an unterminated comment or string. `test_strip_validates_output.lua` proves the gate on a file that is genuinely unparseable, under both a plain and a `--minify` build, and that an ordinary file still strips and still compiles.

### The open queue, worked through

Fixes and loose ends from the TODO queue, one at a time, each with a test that fails on the code before it.

- **The shell shows output again while a program waits in the background.** After Ctrl+B put calc behind the shell, every later command ran and printed nothing (`echo`, `ps`, all of them) until calc exited: the shell hid output whenever any program was recorded, not just when the command had started one. Now only the command that hands the screen to a program is silent. On the headless machine `ps` with calc in the background lists `prog:calc@1`. `test_bg_program_output.lua` (2 of 4 checks fail on the old code).
- **A chat group says who actually got the message.** It counted every member it had sent to as delivered, so a member whose machine was switched off was never named, and a send the network refused (no shared secret yet) showed only as a bare 0. Every machine now acknowledges each chat message it receives. A group send names a refused member with the reason, waits a few seconds for answers, and then reports "delivered to N of M", naming whoever did not answer. On two headless machines: "delivered to 1 of 2" with the other machine on, "delivered to 0 of 2 … no answer from m2" once it was shut down. `test_chat_app.lua` (fails on the old code).
- **Chat reaches a peer by its alias.** `net` names a peer by alias, address or prefix, but chat knew only address prefixes and hostnames, and every fresh TOS is called `tos`. So `m2: hello`, or a group whose members were aliases, could not reach anyone: on two headless machines the group called its member "unreachable" with that machine on and trusted. Chat now resolves aliases first, still only to peers trusted enough. `test_chat_parse.lua` (4 checks fail on the old code).
- **The Intercom's announcements reach the other machines** (intercom 1.0.1). The receiving side read each incoming network message as if it were the announcement itself. The announcement is inside it, so every one was turned away: no box, no line in `intercom log`, on any machine. It now reads what is inside. On two headless machines, `intercom play` on one raised "Warning: Reactor offline." on the other; three more alerts within twelve seconds raised no further box (the cooldown), the keyboard stayed usable, and `intercom log` listed all four. `test_intercom_mesh_seam.lua` sends through two real network stacks (3 of 6 checks fail on the old code). Ships in the next signed pack.
- **An Intercom cue stops where the catalogue says, on either Computronics** (intercom 1.0.1). The stop was timed at 4,096 bytes a second, which is Computronics for 1.7.10. Computronics for 1.12, and the Ocelot emulator, play 6,000, so every cue ran on about half again into the next recording; on the headless machine an 8,192-byte cue stopped at byte 13,500. The Intercom now watches the drive's position and stops it at the cue's end, within one packet (9,000 there), without ever holding up the keyboard. `test_intercom.lua` plays it at both rates (8 of 10 new checks fail on the old code).
- **`cluster-setup`'s first screen describes what its buttons do.** It ended by telling you to install the package yourself and run `cluster-setup` again, but picking Master or Manager on that same screen installs it and carries straight on. It now says so. `test_cluster_setup.lua` (2 checks fail on the old wording).
- **`cluster-setup` on a Master prints its pairing code.** The cluster package hands back its pairing window as one table; the wizard expected the code and the seconds as two values. It printed "Pairing window open for 0s." and then failed on the line that shows the code, so no Manager could be given one, on any Master. The wizard reads the table now, and a Master whose daemon is not up yet is told so instead of crashing. On the headless machine it prints "Pairing window open for 299s." and the code. `test_cluster_pairing_seam.lua` runs the real cluster package's API through the wizard (fails on the old code).
- **A Manager hears its Master's pairing confirmation.** A Manager trusts its Master before pairing, so the Master's confirmation arrives from a trusted machine, and trusted machines were not allowed to send pairing packets (only unknown ones were). Every pairing through the wizard reported "no confirm received" although the Master had paired and the Manager went on to register. Pairing packets are now accepted at every trust level short of blocked; they are checked against the pairing code either way. On two headless machines the Manager now says "Paired with the Master." `test_net_trusted_gate.lua` (3 checks fail on the old code).
- **Keys typed while earlier ones are still queued are kept.** When a program had input waiting, the scheduler handed it the oldest and dropped whatever arrived at that moment, the key just typed included. So after any slow step that left keys queued, such as a package install, the next few keys could vanish. On the headless machine `cluster-setup` lost an Enter at one prompt and a "n" at the next box this way. The new arrival now waits behind the queue, in order. `test_coop_yield.lua` (the new check fails on the old code: a key and a network message, both lost).
- **An OpenOS program on a second seat draws on that seat.** Each seat had its own cursor, but the OpenOS terminal drew everything through the boot display's GPU, which is seat 1's. A program run on seat 2 read its keys from seat 2 and painted its prompt and output over seat 1's shell. A seat with a GPU of its own now gets it; single-seat machines and everything without a seat draw exactly as before. On the headless machine with two seats, a program that prompts and reads a line now shows its prompt and its answer on its own seat, with both status bars intact. `test_compat_term_seat.lua` (6 of 27 checks fail on the old code).
- **A notice answered on one seat closes on every seat.** Every seat shows a `notify` box, and the first answer settles it for all of them. But each seat waits in its own copy of the box, and nothing closed the others: on the headless machine with two seats, OK on seat 1 left the box up on seat 2 until it was answered a second time there. Dialogs can now be closed from outside, and a notice's box closes once another seat has answered it. A box nobody has read yet still stays up when its notice expires. `test_notice_cleared_elsewhere.lua` drives the real dialog and the real `kernel.notify` (5 of 15 checks fail on the old code).
- **On a two-seat machine, each seat's login is its own.** The login screen kept the seat's display in variables shared by every seat, so both seats' logins drew on whichever seat started last. The other seat looked dead: its keys were read, but their echo landed on the other screen. Each seat now gets its own login. A fresh install also opens First Boot Setup on every seat, and once one seat set root's password the others stayed in theirs, refusing every answer as "Current password is incorrect". The other seats now say the password was set at another screen and go to the ordinary login, ending the session they had opened with the default password. On the headless machine with two GPUs, screens and keyboards, seat 2 now echoes its own keys, steps aside when seat 1 sets the password, and logs in with that password. `test_login_per_seat.lua` (9 of 16 checks fail on the old code).
- **A package's `/usr/bin` program runs as that package.** It already got the caps its package was granted, but not the package's name. So a notice it raised said "From: package" instead of naming it, and every such program shared that name's 10-second rate limit. Its `crypto.secret()`, which is scoped to the package name, did not exist at all. The shell now passes the owning package's name to the sandbox, as it does for package commands. On the headless machine a fixture package's program raised a box reading "From: hammer". `test_pkg_program_caps.lua` (2 of 3 new checks fail on the old code).
- **Tetris's quit footer fits its panel** (tetris 1.1.2). With the default bindings the side panel's last line read "P:pause ^Q / F10:quit", 21 columns in a panel 16 wide, so it ran over the right border on the headless machine. It now names the first key when they don't all fit, and plain Q, which always quits Tetris, when even that doesn't. `test_tetris_sandbox.lua` renders the panel with the shared shortcut table's label (3 of 4 new checks fail on the old code).
- **The System Monitor reports a refused service start as refused.** Enter on a service the machine cannot load (no network card) showed "Starting 10-discoveryd" and logged "Started", though nothing ran: rc refuses by returning false with a reason, and both the Monitor tab and the command-line switcher counted anything that did not raise as done. Both now go through `monitor.svcToggle` and show rc's reason; the switcher puts it on its help row until the next key. K or T on the shell's own row says "Refused: PID 2 is the shell this Monitor runs in", not "that is this shell". `test_monitor.lua` (60 checks).
- **Closing the System Monitor at the command line repaints the shell.** On a CLI seat, closing the Ctrl+T monitor left it on screen with the next prompt drawn over it, and switching to a process with Enter never told that process to repaint. Both lines started with `(` right after a `proc.setForeground(...)` call, which Lua reads as a call on its return value, so each raised before the repaint signal was sent. Both now start with `;(`, and `test_call_chain_lint.lua` scans every shipped Lua file for a statement that starts with `(` (it found only these two).
- **The System Monitor says why a service was never loaded.** On a machine with no network card it listed the network services as "stopped", as if they could be started, while `service` said "not loaded: needs network hardware". The Monitor tab, the command-line switcher and `monitor`'s text listing now share one wording, `monitor.svcStatus`, and the switcher's name column no longer pushes the status off the edge. `test_monitor.lua`, `test_monitor_app.lua` (the new draw check fails on the old code).
- **The splash bar stays under the header on a small screen.** On a T1 50×16 screen the progress bar was drawn on top of the Verifying line, leaving "Veri[####…]est.", because it was lifted to keep three rows of narration. It now stays under the header, and the narration gives up rows instead. Warnings in the narration are no longer cut at the bar's width, and the SAFE MODE and low-memory lines centre with the rest of a splash boot; text and verbose boots are unchanged. `test_splash_resize.lua` (the new geometry checks fail on the old code).
- **`lang dump` says why it could not write, and how to add a language.** As root, `lang dump /usr/lang/xx.lang` printed only "Write failed": `/usr` is a protected system path, and the template's own instructions said to save it there. The command now shows the reason and the route that works (dump to `/tmp`, then copy the file in under `protect off`, or ship it as a package), and the template and MANUAL 10.2 say the same. `test_lang_dump_refusal.lua` (3 of 9 checks fail on the old code).
- **`bootsettings ramgate` takes `always` and `never`.** The Boot Settings editor's RAM row says "always load" and "never load", but the command still printed and accepted the older "plenty" and "tight". It now uses the editor's words, and the old ones still work. `test_bootsettings_ramgate.lua` (5 of 12 checks fail on the old code).
- **Boot Settings, the POST screen and `hw` name the RAM sticks.** They were meant to read "2x T3.5" or "T3.5 + T2.5" and showed only the total ("[2048K]", or "Memory Tier: T2+ (est)" on the POST screen). No memory stick reports its size, and sticks are not components, so every stick count came out 0; the "RAM 4K" in an August boot log was the EEPROM, the only memory device that reports a capacity. Each stick's clock narrows it to two stock sizes, and TOS now keeps the one combination that adds up to the machine's total. When two sets fit (possible from three sticks up) it says "4 sticks, 1280K" rather than guess. `test_boot_screen_and_ram.lua` now uses the shapes OpenComputers and Ocelot actually report.
- **`scp` and `rsh` take a peer's alias.** `scp two:/public/hello.txt` answered "Peer is not TRUSTED" for the trusted peer `net alias` had just named "two"; only its full address worked. Both now take an alias, a full address or a unique prefix, as every `net` command does. `scp`'s usage no longer offers an upload that nothing implements, and the docs say `rsh` runs Lua (`rsh two print(1+2)`), not a shell command. `test_scp_rsh_alias.lua` (5 of 8 checks fail on the old code).
- **`cron` shows the saved jobs when the boot profile has it off.** In Safe Mode `cron list` said "No scheduled jobs" while `/etc/cron.dat` still held them. It now says cron is off for this boot, lists the saved jobs read-only without loading the scheduler, and refuses changes with E-404. `test_cron_profile_off.lua` (9 checks).
- **Safe Mode no longer runs a package's programs.** A package command shipped as a `/usr/bin` program still ran in Safe Mode, with its package's permissions, because the shell's PATH lookup found the file anyway; `run`, `bg` and the file browser would have run it too. All four now refuse a package-owned file in Safe Mode with **E-404 ERR_SAFE_MODE**, naming the package. Your own scripts still run. `test_safe_mode_programs.lua` (11 checks).
- **`backup snapshot` works on OpenComputers' clock.** It died with "number has no integer representation" whenever the game clock was not on a whole second: `os.time()` is game time, a float, and the snapshot header packs it as an integer. The time is now rounded down. `test_backup_snapshot.lua`, kernel.backup's first test, fails on the old code.
- **A broken boot disk is no longer a boot loop: d boots another.** When the saved disk's kernel or `/init.lua` was missing or broken (K4, I5, I6), the screen's only way on was a reboot onto the same disk. It now also offers "d: other disk", which passes that disk over on the next boot. What the scan finds still goes through the "Boot drive changed" approval, and a machine whose only disk is the broken one is offered it again. The BIOS is 3,966 of its 4,096 bytes. `test_bios.lua` (4 of the 10 new checks fail on the old BIOS).
- **The release fits its 2 MB-drive budget again, with room to spare.** Changes on 2026-10-16 took the release about 2.5 KB past its 1,920 KB limit (a Tier 2 drive less the 128 KB a first boot needs) and the suite did not notice, because `tos.py test` weighed the last build rather than a fresh one. Rationale comments came out of the release, and the minifier now also collapses runs of spaces and drops blank lines in code while leaving strings alone: the release is about 1,902 KB. `tos.py test` now builds before it tests (`--no-build` skips that). `test_strip_minify.lua` gains a case (3 of its checks fail on the old minifier).
- **A package command loads a third of the package manager.** Every package command, `pkg list` and `pkg info` loaded the whole manager (about 192 KB compiled) and kept it for the session. Installing, upgrading, repos, trust and fetching now live in `kernel.pkgops`, which loads the first time one of them is used, so `pkg list` holds about 170 KB where it held 237 KB. `test_pkg_split.lua` (19 checks).
- **Every package install and upgrade refusal has an error code.** **E-607** to **E-613** cover a package with no file hashes, a file that does not match its hash, a signature that does not verify, a signature required and missing, the wrong publisher, a protected target and a conflict. `why` gives the fix for each, and Appendix C lists them. `test_pkg_refusal_codes.lua` (9 of 26 checks fail on the old code).
- **A typo no longer loads the package manager.** The first unknown command of a session loaded all of `kernel.pkg` to ask whether a package provides that name, and it stayed loaded: on a 1 MB machine one typo took free memory from 63 KB to 22 KB. A machine with no packages installed now skips the question. `test_no_pkg_for_typos.lua` (3 of 17 checks fail on the old code).
- **A package can name the repos it comes from, and `pkg fetch` can use them, carefully.** A manifest, or one of its requirements, may list repo URLs. Installing it records them as *known*, never as configured or trusted (`pkg repo list` shows them, `pkg repo forget` drops them). When no configured repo has a requirement, `pkg fetch` tries those: a package signed by a trusted key installs as usual, one signed by an unknown key needs an admin to compare its fingerprint, type "trust" and name the publisher, and an unsigned one is refused with **E-606**. A service or driver from an unknown key is always refused. `pkg trust discovered tofu|trusted|off` sets the policy. `test_pkg_known_repos.lua`, `test_pkg_discovered.lua` (46 checks each).
- **File sharing answers requests.** `20-fileshare` was running on every networked boot and answered nothing until something else had loaded the transfer backend, such as an outbound `scp` from that machine, so a peer's request timed out. The network layer now loads a backend on its first packet even when another listener already exists for it. `test_fileshare_serves.lua` (9 of 22 checks fail on the old code).
- **Network file shares (`netfsd`, `netfs mount`) work.** `netfsd` reported itself running and served nothing: its sandboxed environment could reach neither the network nor the netfs module, and nothing ever set netfs up, so `netfs mount` found every share unreachable. netfsd now arms itself through `net` as fileshare and rshd do, netfs sets itself up wherever it loads, and `netfs status` says when the export file was rejected. `test_netfsd_serves.lua` (13 of 26 checks fail on the old code).
- **`pkg install` says when a file could not be read, not that it is missing.** At 1 MB, installing from a floppy reported "missing source file" for a file that was there: the read had run out of memory. An absent file now fails with **E-604** and an unreadable one with **E-605**, with the reason and, for memory, what the machine needs. `test_pkg_read_reason.lua` (12 checks).
- **The installer warns a 1 MB machine with a network card.** A network card costs about 170 KB, so with one TOS needs 1.25 MB, but the installer warned only below 1 MB, and the install gave a shell that could run no command. `test_install_memory_warning.lua` (4 of 11 checks fail on the old installer).
- **`tos.py floorcheck` re-measures the README's memory figures.** Each memory claim in the README is booted on the headless machine at that size and checked from both sides. Its first runs corrected the README: every figure had been measured without a network card, and with one the floor is 1.25 MB. `build/test_floorcheck.py` ties each case to the README text it checks.
- **A command makes room for the module it loads.** At 1.25 MB, `pkg list` worked as the first command and failed after `mem` with "needs 1280 KB of RAM; this machine has 1280 KB". The nine commands that load a module of their own now give back the other command groups and retry once when memory runs out, and `pkg` says free memory is short rather than total RAM. `test_require_roomy.lua` (24 checks).
- **Network services are not loaded on a machine with no network.** All five built-in services are network daemons, and boot loaded every one without a network card, about 94 KB, while `service` listed four of them as running. A service can declare `needs = "net"`; without a network it is listed as "not loaded: needs network hardware", and `service start` says what to add. A disabled service now reads "disabled", not "stopped". `test_rc_needs.lua` (16 of 27 checks fail on the old code).
- **`mem --boot` shows what each boot stage costs.** With `memprofile = true` in `/etc/boot.cfg`, boot records free memory after a collection as each stage starts, and `mem --boot` prints the table. It is off by default, so a normal boot pays nothing. `test_boot_memprofile.lua`.
- **A backgrounded program's chip says whether it is still running.** After Ctrl+B the program's chip in the top bar came up plain (frozen) at once, and once the program did freeze the chip kept saying busy, because chips were refreshed only when the top bar happened to repaint. It now reads busy until the program freezes, and updates within a second. `test_program_tab.lua` (30 checks).
- **ttt's Up arrow moves up a row** (ttt 1.0.1). Up stepped the cursor back four cells instead of three, so on the headless machine Up then Enter from the centre put X in the top-left cell, and Up from a corner jumped to the middle row. Down, Left and Right were right. The move is now `L.step` in ttt's pure `logic.lua`, and `test_ttt.lua` pins all four arrows from every cell; it fails on the old code.
- **stock closes on ^Q, as its footer says** (stock 1.0.1). The monitor's key bar ends "^Q quit", but only a plain Q closed it: the quit key is read as a cancel, which the main view ignored. On the headless machine `stock` kept the screen and the rest of a session typed into it. The quit key now closes the monitor, and Q still does. `test_stock.lua` runs the real command with no inventory hardware and feeds it the key; ^Q fails on the old code.
- **`service start` runs the code that is on disk.** Services were loaded once, at boot. A service package installed since then answered "Unknown service" until a reboot, although the picker had just said "Start service(s): ..." and the manual says `pkg install mail` then `service start mail`. After `pkg upgrade`, `service stop` and `service start` re-ran the old code, although the upgrade says that is how to run the new one. `service start` now loads the service from its file, through the same checks boot uses, and refuses a name that would reach outside `/etc/rc.d`. Removing or upgrading a package also drops the libraries the system had loaded from its files, so a restarted service gets the new library too. On the headless machine a restarted service went from running the old code to the new one, with no reboot. `test_rc_reload.lua` (6 of 14 checks fail on the old code) and `test_pkg_lifecycle.lua` (2 new checks fail on the old code).
- **The package picker's G notice has the key bar to itself.** G ticks every package in a category and says so on the bottom row, but it was painted over the start of the key bar, so the row read "Selected 3 in Games  / Filter · A All · N None ...", with the notice running into the keys beside it. The notice now replaces the keys until the next keypress, inside the bar's end caps. Found on the headless machine. `test_picker_bar_notice.lua` drives the real picker (2 of its 5 checks fail on the old code).
- **The command line repaints after the package picker.** `pkg install` from the CLI opens the full-screen picker, and closing it left a blank screen with a bare prompt: the header and the key bar did not come back for the rest of the session. The picker is a built-in that draws straight to the screen, so it asks the shell to repaint when it hands back, and the CLI's repaint did nothing. It now gives the same clean screen a full-screen program gets when it ends. The tutorial and the tape toolbox hand back the same way. Found running the picker checklist on the headless machine, which otherwise passed line for line. `test_cli_takeover.lua` (4 of 10 checks fail on the old code).
- **The Optional Utilities disk no longer looks like a test disk.** The boot self-test searches every mounted disk's `selftest/` folder for checks, and a pack disk keeps each package in a folder named after it, so the second Optional Utilities floppy carries a `selftest/`: the selftest package itself. With that floppy in the drive, `selftest list` showed its `package.lua` as a check, and an armed boot would have run the manifest and logged "FAIL package :: check file returned neither a function nor { run = f }", a failure that only means a disk was inserted. A `selftest/` that holds a `package.lua` is a package now, not a folder of checks, in the kernel's runner and in the `selftest` command, which keeps its own copy of the runner's discovery. Found on the headless machine. `test_selftest.lua` (both new checks fail on the old code) and `test_selftest_cmd.lua` (3 of 27 fail on the old code, one of them because the old runner really did run the manifest and count the FAIL).
- **The `selftest` package can be installed, and the pack can be indexed.** Its manifest built the description from three strings joined with `..`. `pkg` reads a manifest as data, never as code, and its reader refuses any expression. On a headless machine `pkg install-dir` answered "package.lua parse error: Unexpected character '.'" and `pkg install selftest` answered "package not found in any repo". It surfaced only at publish time, when `make-repo-index.lua` refused the signed pack with no reason given. Every other check had passed, because they all load manifests with Lua, which accepts `..`. The description is one string now. `build-disk.lua` decodes every manifest the way `pkg` does and refuses one it cannot read, naming the line, before anything is built or signed. `make-repo-index.lua` says why a manifest did not decode. `test_manifests.lua` decodes all 18 source manifests (selftest fails on the old one), and `test_build_disk.lua` builds a scratch package both ways (3 of its 4 new checks fail on the old builder).
- **`ls`, `head` and `tail` take the flags the manual gives them.** The manual has always listed `ls [-l|-a] [dir]` and `head [-n N] <file>`, and neither parsed a flag. `ls -l` treated `-l` as the directory and listed "0 items", which broke the manual's own `alias ll ls -l`; `head -n 2 file` answered "Cannot read: -n"; a directory that does not exist listed as empty. Now `ls -l` adds when each entry last changed, names starting with a dot are hidden unless you give `-a` (the count says how many), flags combine, and a missing directory says "no such file". `head` and `tail` take `-n N`, `-N` or a trailing count, and a file that is not there says "No such file" instead of a bare "Cannot read". The manual's examples now follow `/var/log/kernel.log`, the log the kernel actually writes (every 30 seconds), not `/var/log/tos.log`, which never existed; and its alias entry no longer claims `alias ls "ls -a"` works, since that is refused on purpose. Found running the alias checklist on the headless machine. `test_ls_flags.lua` (all 8 checks fail on the old code) and `test_head_tail_args.lua` (5 of 8).
- **`ps` names who owns each process.** Every owner read "?", root's own shell included: `ps` looked for an owner field the process list never had, while the Monitor, reading the right one, was fine. The visibility rule built on it went wrong the same way: a USER matched none of their own processes and saw every line as "(other user)". And `ps -v`'s capability column was always "-", because the list carried no capabilities; it now carries a copy. `test_ps_owner.lua` spawns real processes and runs the real `ps`; 5 of its 7 checks fail on the old code.
- **The command line comes back after a full-screen program, and says why the full interface would not start.** Two faults found running the CLI's emulator checklist on the headless machine. Quitting `calc` (or any full-screen package program) started from the command line left a blank screen, with no prompt and no header, until you typed blind: the program runs in its own process and tells the shell when it hands the seat back, and the command line never listened. It repaints now, and prints anything the program left behind. And when the full interface itself fails to load, the seat lands in a working command line as designed, but the reason was shown for two seconds and then replaced; typing `tui` failed the same way, silently. The command line now prints "The full interface could not start:" and the reason under its banner, every time. `test_cli_refocus.lua` runs the real command line and hands it the seat back (3 of 7 checks fail on the old code); `test_tui_failure_reported.lua` drives the shell's fallback (4 of 7).
- **A typed-word confirmation names its own button.** The box that makes you type a word before something drastic, such as `flash`, said "the word matches - choose Confirm" and "(Confirm stays inert until it matches)" beside buttons labelled Cancel and Flash. It names the button it means now. Found running the box's emulator checklist on the headless machine, where everything else held: the box keeps its size while you type, Backspace and pasting both work, Enter on the inert button does nothing, Esc and Ctrl+Q cancel, and a click on the inert button moves focus to it without firing. `test_dialog_confirm.lua` now drives the real dialog loop; 3 of its 5 new checks fail on the old code.
- **Rows are measured in screen cells, not bytes.** On the headless machine, `pkg verify-sig` on a tampered package printed its "DOES NOT VERIFY — signature does not match" with two cells of the file panel's border still showing at the end. The command-output area padded each line with spaces and cut it with a byte count; "—" is three bytes in one cell, so the row came up two cells short and the old contents showed through. A file name with "é" in it did the same to its file-list row, and the file viewer's cut at the right edge could split a character in half, which the screen draws as garbage. All of them now cut and pad by cells, counted the way the screen paints them; the viewer's search highlight also lands in the cell where the match starts rather than at its byte offset. `test_draw_cells.lua` counts the cells each row really fills: 5 of its 8 checks fail on the old code.
- **A command that cannot load says why, and `pkg` says how much memory it needs.** On the smallest machine TOS runs on, 1 MB, every `pkg` command printed "pkg module unavailable" and nothing more. The reason, thrown away, was the boot loader's "Syntax error in 'kernel.pkg': not enough memory": compiling the package manager needs more than the roughly 200 KB left once the shell is up. Measured on the headless OpenComputers machine, it loads from 1.25 MB (a Tier 3.5 and a Tier 1.5 stick), where listing, verifying, signing and installing all ran. `pkg` now says "cannot load: not enough free memory on this machine" and names 1280 KB against what the machine has; the loader calls an out-of-memory compile "Out of memory loading" instead of a syntax error; and eight more commands that dropped their reason the same way (`srm`, `doctor`, `vault`, `service`, `cron`, `netfs`, `kiosk`, `tutorial`) now keep it. The README's requirements and the manual's section 1.1 give the 1.25 MB floor for add-ons. Also: `pkg sign`'s abort message asked for a 12-character passphrase; the floor has been 20 since KDF v2, and the message now reads it from `pkgsign`. `test_module_load_errors.lua`, 13 checks, 4 fail on the old code.
- **#SEC — the password brakes wait in real seconds.** After three wrong passwords, login (H-5) and `sudo`'s elevation make the next attempt wait 5 seconds, doubling to 5 minutes. Both measured that wait with `os.time()`, and on OpenComputers `os.time()` is the in-game clock: a game day is 86,400 of its seconds and lasts 20 real minutes, so 72 of them pass every real second. The first wait lasted 0.07 s and the cap about 4 s, and since a wrong guess costs a password KDF, which takes longer than that, neither brake ever refused anyone on a real machine. Found running the Keller import's emulator check on the headless machine: the fourth `sudo` attempt, a second after the third, was judged instead of told to wait. Both now measure with `computer.uptime()`, which is real seconds, and stamp each failure with the boot it happened in. A stamp from an earlier boot, or one an older build wrote, counts only this boot's uptime, so a reboot can lengthen a wait but never shorten it. On the same headless machine the fourth attempt now gets "try again in 4s". `test_backoff_clock.lua` drives the real `users.lua` under a clock shaped like OpenComputers' (`os.time` at 72 times real speed, uptime starting again at every boot): 5 of its 8 checks fail on the old code. `test_elevation.lua` now moves uptime instead of `os.time`. The manual's section 3.3 gives the numbers.
- **No hint sends you to a command that is gone.** v1.4.0 retired `launcher`: the Desktop took its place, and the tape toolbox became `tape-menu`. Two hints kept sending people to it: `kiosk` said "Run 'launcher'" for the operator's menu, and `tape-auth`, after you built a personal menu, said "Then open it with: launcher tape". Both answered "unknown command". They now name `desktop` and `tape-menu` (the tape-auth half rides tape-authenticator 1.0.3, still waiting on the pack signing). `test_hint_commands.lua` reads every "run 'x'" hint in shipped code, the base OS and the add-ons, 38 of them, and checks the command it names exists in the shell's registry, as an add-on's command, or as a program an add-on installs; it fails on exactly those two before the fix.
- **Known issue: `rc` never hears the robot.** A TOS package cannot receive raw network traffic: the package sandbox drops every `modem_message` so that no program can listen in on another's, and the `net` capability carries only TOS-protocol messages, which a robot running the rc-pilot chip does not speak. So the answer to `rc`'s ping has never been shown on a real machine, and the obvious way for a robot to tell you its address, a reply to a discovery broadcast, would be dropped the same way. The rc-pilot test fed the host a raw `pullSignal` and could not see this; it now also runs `rc` through the real sandbox and pins the gap. Whether a package may hear the ports it opened itself changes what the sandbox allows, so it is an open decision in TODO, with options.
- **`flash --data` gives a robot's chip its secret.** rc-pilot's robot program reads its shared secret from the EEPROM's data field, and nothing on TOS could write that field: `flash` wrote only the code, `component eeprom setData` is refused because `flash` is the one way to write an EEPROM, and the sandbox hides the EEPROM from every program, the root `lua` prompt included. So a chip burned by following `rc`'s own instructions ignored every frame, without a sound. `flash <file> --data` now asks for the data field, twice and without showing it, before anything is written; a mismatch or a cancel leaves the chip as it was. A BIOS is refused `--data`, since the TOS BIOS keeps its boot address and the manifest anchor there. The not-a-BIOS warning also says when that is expected: for a chip going into a robot or a drone. `test_flash_data.lua` drives the real command against a fake EEPROM; 14 of its 20 checks fail on the old code. The robot still cannot tell you its address; that half is a pack change, on the TODO list.
- **snake keeps a high-score board per player** (snake 1.0.1). The package promised per-user high scores, but every game wrote its score to `/home/.snake_hs`, a file in `/home` itself rather than in anyone's home. Admins all shared one board, and an ordinary user, who may not write there, never had a score saved; the write is guarded, so nothing said so. Scores now go to `.snake_hs` in the player's own home, as tetris has always done, and a game played with no session saves nothing rather than starting a board everyone would share. `test_snake_scores.lua` plays real games through the real program as two players; 5 of its 10 checks fail on the old code.
- **`cat`, `mkdir` and `touch` take every path they are given.** Each read only its first argument and ignored the rest without a word: `touch a b c` made `a` and said "Touched: a", `mkdir x y` made `x`, and `cat a b` printed `a` alone. `rm` had the same bug until the keller import. Each path now gets the checks the single path always did, and a refusal on one is shown while the rest go on. `mkdir -p` is accepted (parents were always made; it used to create a directory called `-p`), and an existing directory now says "Already exists" instead of "Could not create", or nothing with `-p`. `cat` stops at the memory floor rather than starting the next file. `test_multi_path_cmds.lua`: 17 of 26 checks fail on the previous code.
- **A malformed remote package index is refused, not thrown.** `pkg fetch` used every key of a package's `files` list as a path string; an index that wrote the list as an array (`files = { "a.lua" }`) has number keys, and the fetch crashed with a Lua error instead of refusing. The whole list is now checked before anything is staged or downloaded, and the refusal names the repo. Two other refusals (an OPPM directory-copy entry, an unsafe path) left the staged index behind in `/var/pkg/remote`; every refusal now clears it. And a repo whose index cannot be read is named in the answer instead of reading as "not in any configured repo". `test_pkgremote_malformed.lua` drives the real fetch-and-install chain; 8 of its 38 checks fail on the previous code.
- **#SEC — a sandboxed program's `fs.mounts()` no longer hands out disk addresses.** A disk's component address is what `component.proxy` turns into raw access with no permission check below it, which is why `filesystem.get()` in the OpenOS compat layer has hidden it from non-admins since H15. The sandbox's own `fs.mounts()` handed every address out anyway. It now gives the same stable stand-in (`fs:` and 16 hex) that `filesystem.get()` does, from one shared derivation, to anyone below admin, and returns copies, so nothing a program writes into the list reaches the kernel. Admins still see real addresses. `test_securefs_session_bind.lua` gains 8 checks against the real fs, users, securefs and sandbox; on the previous code 2 fail and the run stops at the third.
- **Four more kernel waits stop yielding to the host.** On OpenComputers `coroutine.isyieldable()` is true in kernel context, because the kernel runs inside `machine.lua`'s coroutine. `net.waitFor` was fixed for that in the previous release. Four more places used the same test to mean "am I in a process?": a read from an empty pipe, which from kernel context waited forever instead of returning nothing; the sandbox's `pullSignal`, which lost its 3-second ceiling and its own timeout; and `proc.yield` and `proc.sleep`, which handed the next signal to nobody. That sleep is the one `os.sleep` uses, so an rc.d service's start code could stall until some signal arrived and then drop it. They ask the scheduler now. Outside a process, `proc.sleep` waits in 50 ms slices through the event loop, so listeners and timers still run. `test_inprocess_callers.lua` runs them under a host loop shaped like OpenComputers' (10 of 20 checks fail on the previous code), and self-test `97-inprocess` checks the same four on the machine.
- **The editor counts what the screen counts.** The screen draws one character per cell, but the editor counted bytes. From the first accented or box-drawing character on a line, the visible window, the horizontal scroll, the `>` marker, the cursor, the selection and the status bar's column were all off. An accent is two bytes, so a line like `local café = 1` lost its last character off the right of the highlighted view. Left and right stepped one byte, so the cursor could stop inside a character, and Backspace deleted half of it. The cursor now always sits between whole characters, and everything drawn is measured in screen cells. Moving up and down keeps the column you see. A byte that is not valid UTF-8 shows as `?` in its own cell, so it can still be reached and deleted. Also fixed: a click or drag on a line scrolled sideways put the cursor as if the line had not been scrolled. `test_editor_utf8_columns.lua` drives the real editor drawing and mouse handling; 19 of its 47 checks fail on the previous code.
- **Known issue: the cluster operator commands `cluster` and `cluster-manager` do not start.** Found by widening the accidental-global lint to the add-ons, and confirmed by running both in the sandbox the shell gives them. They were written to share the running daemon's state, but since the September sandbox hardening a program's libraries load privately inside its own sandbox. So the command can't load its library, and if it could, it would see a copy no daemon is using. The cluster services themselves start normally; until this is resolved, pair a Manager with `cluster-setup`. How to restore the commands is a decision about what a trusted package's own program may reach, and it is recorded in TODO with the options. The lint now checks every add-on file against the environment it actually runs in.
- **A service's settings are read from its code, not its comments, and a restart budget comes back.** The service manager reads what capabilities, restart setting and restart limit a service declares from its source, without running it. A comment that mentioned `restart = true` made a service restart, a commented-out capability table could be read instead of the real one, and a capability written as `net = true` instead of `["net"] = true` was ignored. The cluster storage daemon declares `net` that way, so it would have started with no network. Comments are now skipped and the capability table is read as data, so every way of writing it reads the same. Separately, a service's restart count never went back down, so a service that crashed once a week eventually used up its restarts and stayed down. A service that has stayed up ten minutes now gets its restarts back, and starting one by hand resets the count. A crash loop is still stopped. `test_rc_peek_decay.lua`: 7 of 17 checks fail on the previous code.
- **`rm` on a system path gives one answer, the right one.** `rm /tos/x` used to say "add -r", and `rm -r /tos/x` was then refused by the protected-path guard for a different reason, with a different fix (`protect off`). `rm` now asks the protected-path guard first and shows its refusal. The "add -r to confirm" step only appears once root has turned protection off, where the delete would really happen. `test_rm_system_guard.lua`.
- **A release says which commit built it.** The version number is set by hand, so a screenshot, a self-test log or a crash dump could not say which build of 1.5.0 it came from. The release build now stamps the commit it was built from (and `-dirty` if the source had uncommitted changes) and whether it was minified. `about` shows it, and so do the first line of every boot's kernel log and of `/var/selftest.log`. Run from the source tree, it says `source`. A release whose stamp could not be applied is refused at build time rather than shipped looking stamped.
- **#SEC — only root can install a boot self-test check.** An armed machine runs every check in `/usr/lib/selftest/` inside the kernel at boot, and arming has been root-only for that reason. But `/usr/lib/selftest/` was ordinary package space, so an ADMIN could install a package that left a check there. The next time root armed the battery, for any reason, that check ran as the kernel. A package that installs anything there now needs root, exactly as a service package does: for an install, for an upgrade into such a package, and for a dependency. `test_pkg_service_root.lua`: 5 of its 25 checks fail on the previous code.
- **Installing TOS keeps the `/init.lua` it replaces.** The installer used to replace `/init.lua` and keep nothing, so a disk that had OpenOS on it could not boot OpenOS again even after deleting `/tos`. The old file is now kept as `/init.lua.pre-tos`. Rename it back to boot the previous system while its files are still on the disk. A clean install, or `reclaim`, removes it together with OpenOS's files, because without them it can boot nothing. `test_install_preinit.lua`.
- **A cloned OPPM repository installs.** In an OPPM index, a file's path starts with the branch name (`master/gui/gui.lua`), because OPPM builds a download URL from it. A git checkout of that branch has no `master/` folder, so `pkg install` from a cloned OPPM repo on a disk reported every file missing. It now also tries the path without the branch when the literal one isn't there. Fetched and mirror-style repos still read the literal path first. `test_pkg_lifecycle.lua`.
- **Provenance is checked.** A new lint fails on any shipped file that shares eight or more consecutive code lines with the vendored OpenOS tree without crediting it, and on any shipped code that names that tree. It found one file: the OpenOS compatibility `internet` library keeps OpenOS's argument checks and its form-encoding loop word for word, so that ported programs behave identically. It now credits OpenOS (MIT).
- **A package can say what it needs to run.** Two optional manifest fields, `lua = "5.4"` (the oldest Lua architecture it works on) and `tos = ">=1.5.0"` (the TOS versions it works on). A package built for a newer Lua than the CPU runs used to fail when it loaded, as a syntax error in someone else's code. Now the install is refused before anything is written, with what to do about it ("sneak-right-click the CPU to switch its architecture"). Every dependency is checked the same way, so `pkg install --dry-run` shows it, and `pkg info` lists both fields. `--force` goes past them. `test_pkg_runtime.lua`.
- **Online repair: `srm repair --online`.** It puts back system files that fail their manifest digest, fetched through an internet card from the published release. It is built to be unable to make things worse. A fetched file is written only if its SHA-256 matches this machine's own manifest, and the manifest is trusted only if it matches the EEPROM anchor (`--unanchored` accepts an unanchored one; a manifest that fails its anchor is refused). It fetches this machine's own release, using a `build-<stamp>` tag that every publish now pushes, so it never upgrades. Everything is staged and checked before anything is replaced, so a dropped connection or a full disk changes nothing. Nothing under `/etc` is touched, because service scripts and their on/off markers are yours. It is a dry run unless you add `--apply`, which needs root. `test_netrepair.lua` drives it through every refusal.
- **The boot self-test battery is a package: `selftest`.** The runner has always been in the base image; the checks lived on a test disk that only a host-side script could prepare. The new `selftest` add-on (category `dev`, root install) installs the sixteen shipped checks into `/usr/lib/selftest/`, which the runner already searches. It also adds a `selftest` command to `arm` and `disarm` the battery (root), `list` what an armed boot would run and from where, read the `log` (a run that never finished is reported as stalled, naming the check it stalled in), and print a `template` for a check of your own. That template is the point: you can now test what you add to TOS on a booted machine, not just off-box. The command does not run checks itself, because several exist to test kernel context before the shell is up. `test_selftest_cmd.lua` drives the command against the real kernel runner: what `arm` writes is what the kernel reads, `list` is exactly what it discovers, and `log` reads a log the real runner wrote. Also fixed: the build check that compares the published pack against a fresh build never covered `stock`, `printer`, `write` or `intercom`; it now covers every package in the set.
- **A signed OPPM index keeps its signature through `pkg fetch`.** A repo can sign its whole `programs.cfg` with a `programs.sig` beside it, but `pkg fetch` copied out the one package's entry and never downloaded the signature, so a package from a publisher you trust was recorded as unsigned, and under `pkg trust require on` it was refused. `pkg fetch` now downloads the signature, re-reads the index, and stages the two together, so the package is checked against exactly the bytes that were signed. A host's error page or a refusal counts as "this repo does not sign". When the signature request gets no answer at all, the fetch is refused rather than guessed at. TOS's own repos sign each package individually and were not affected. `test_pkgremote_signed_index.lua`.
- **A crash report survives a broken filesystem layer.** A kernel panic is often caused by the filesystem code itself, and the crash report was written only through that code. Worse, when that write failed with an error, the report was still counted as saved, and the stop screen told you to read a file that was never written. When the normal write fails, the report is now written with raw component calls, which share no code with the filesystem layer. It goes to the boot disk first, or to another writable disk if the boot disk won't take it, but never to the tmpfs, which a reboot erases. A copy on another disk leaves out the recent log, which only admins may read. The next boot reports the crash wherever it was saved. `test_crash_dump_raw.lua`.
- **A broken install is no longer a boot loop.** The EEPROM boots its saved disk without asking. A disk whose `/init.lua` runs but whose system files are missing was refused with "MISSING n FILES", rebooted on a key press, and booted again, with no way out except moving the disk to another machine. That screen now offers **B**: it lists every other disk the BIOS could boot (never the one that failed), and pressing a disk's number makes it the boot disk, the same choice the BIOS's "Save it? Y" makes. With nothing else attached it says so, and B looks again once you have inserted the installer floppy. Any other key reboots as before. The BIOS's own halts (K4, I5, I6) still need an escape in the EEPROM itself. `test_boot_elsewhere.lua`.
- **cluster-master 1.0.2.** The two Master fixes of 2026-09-24 (pairing between machines whose clocks were started at different times, and refusing relayed packets that were not authenticated) landed 40 minutes after the Optional Utilities pack was last published, so the published `cluster-master` 1.0.1 is the code without them. The pack was re-signed with the fixes that night but never pushed, still numbered 1.0.1, so `pkg upgrade` would never have offered them to a Master already running 1.0.1. The new number ships with the next signed pack. `cluster-manager` is unchanged in both packs and keeps 1.2.1.
- **tape-auth can ask for a passphrase instead of taking it as an argument** (tape-authenticator 1.0.3). Every `tape-auth log` and `tape-auth menu` command took the passphrase as an argument, so it was kept in the seat's command history. Any passphrase argument can now be `-`, and you are asked for it without it being shown on screen. When the passphrase is being set (the first entry in an empty log or menu, or the new passphrase in `passwd`), you are asked twice, because a typo you cannot see would lock that region for good. A passphrase typed as an argument still works, so scripts keep working, and a note now says it stays in history. Previously, `-` was taken as the passphrase itself. If you used it that way, type `-` when asked. Ships with the next signed pack. `test_tape_auth.lua`.
- **rc-pilot ships the robot's EEPROM image** (rc-pilot 1.2.0). The robot side of `rc` existed only as commented source, about 6 KB, and an EEPROM holds 4096 bytes. The burnable image existed only if someone ran `strip.lua --minify` on it by hand. The pack build now does that step itself and installs the result with the package as `/usr/share/rc-pilot/eeprom-rc-pilot.lua` (3,683 bytes), covered by the package's hashes and signature. The build refuses to produce a pack if the image is over 4096 bytes or does not load as Lua. To burn a robot's chip, swap a blank EEPROM into the computer, `flash` that file, and swap your own EEPROM back. `test_build_disk.lua`.
- **The add-on pack ships its code without comments.** The Optional Utilities builder copied every add-on's source as written, comments included, so `blockfs.lua` took 53 KB of disk and RAM, and the TBFS boot blob carried all of it. The pack now strips comments from each file the way the TOS release itself does. Comments marked `--!` stay, and every line stays at its original line number, so error tracebacks still point at the right line. The add-ons' Lua shrinks from 825 KB to 537 KB, and `blockfs.lua` from 53 KB to 37 KB. The build refuses a file that parsed before stripping and no longer parses after it. `test_build_disk.lua`, `test_blockfs_perf.lua`.
- **A drive is named before it is erased.** `drive format` and `deploy drive` erase a raw drive behind a danger confirmation that could say nothing about what was on it, and `drive info` could only say "not a TBFS volume". A read-only probe now recognises what other OpenComputers systems write to a drive: TBFS, OSDI partition tables (with their partition names), OCGPT, MTPT (with names), SimpleFS (with its label), MS-DOS boot records (MBR or FAT), and blank drives. Anything else is reported as unrecognised, never as blank. Both confirmations now begin "It holds ...", and `drive info` reports the same for any drive that is not TBFS, even if blockfs is not installed. Names read off the disk have control characters replaced and are shortened before they are shown. `test_diskprobe.lua`.
- **The manual describes `profile` and `config` correctly.** The `profile` entry described the boot profile (minimal, normal, and so on), but the command edits your own settings in `~/.profile.cfg`: name, theme, starting directory, prompt, environment variables, and login commands. The `config` entry said anyone could run it, but only an admin can, and its help line said "Edit", but it only prints the settings. The entries for `config`, `bootsettings` and `profile` now each name the file they own (`/etc/tos.cfg`, `/etc/boot.cfg` and `~/.profile.cfg`) and point to the other two.
- **The command reference matches the commands.** Chapter 14 of the manual had no entry for 23 commands, among them `srm`, `vault`, `keychain`, `trash`, `menu`, `disk` and `env`. Fourteen entries made a command look open to everyone when it needs admin or root, and the shell has enforced that requirement since September: `pkg` (including `pkg list`), `service`, `edit`, `run`, `bg`, `fg`, `kill`, `programs`, `verify`, `reboot`, `shutdown` and `rsh` need admin, and `flash` and `lua` need root. A new check, `test_docs_sync.lua`, compares the manual against the command list the shell actually uses: every command must have an entry, every admin or root command must be marked as such, and every entry must be a real command. It also checks that README, the manual and CHANGELOG name the version `/init.lua` reports. On the old manual, the check failed every rule except the version one.
- **`vault` asks for its passphrase.** Every `vault` subcommand took the passphrase as an argument, so it was kept in the seat's command history, where `history` or the up arrow showed it to whoever sat down next. The passphrase is now optional. Leave it off (or give `-`) and `vault` asks for it without showing it, twice when encrypting, since a typo you cannot see would lock the data for good. A passphrase typed as an argument still works, and you are told that it stays in history. `vault` now refuses a file that is not encrypted, or is already encrypted, before it asks you for anything. Its man page described a `vault encrypt <path> [out]` command that never existed; it now describes the real one. `test_vault_prompt.lua`.
- **#SEC — `watch` and the tape toolbox no longer run commands without checking who is asking.** Since September the shell has checked, before running any command, that the person at the screen has the level that command requires. `watch` itself is open to everyone, and it ran the command it watched without that check. The tape toolbox did the same with each item on a card. So a guest could run `watch redstone set left 15`, drive a robot, eject a disk or mount a remote share, and a user's tape card could run admin commands. About forty commands depend on that check alone; many have deeper safeguards of their own, but the level check was skipped. `watch` now applies the check when it opens and on every refresh, so a temporary `sudo` that expires mid-watch stops the command. The toolbox applies it before each item. `test_watch_tier.lua`.
- **`ps -f` and `--live`.** Any command can now take `--live` to open the self-updating tab that `watch` gives it: `ps --live` is the same as `watch ps`. `-f` does the same for `ps`, `df`, `mem`, `uptime`, `log`, `net`, `battery` and `lsdev`, the status commands that have no other use for it. It does not apply to `trash` and `backup`, which already use `-f` to mean `--force`. Commands in a pipeline, and commands run through `sudo`, are left unchanged. `test_live_flag.lua`.
- **`pkg fetch` installs what a package requires.** It used to install only the package you named, leaving its requirements unmet. It now also fetches each requirement from the configured repos, checks it the same way as the package itself, and installs it first. Everything is downloaded and checked before anything is installed, so a requirement that no configured repo has, or that is available only in a version too old to meet it, cancels the whole fetch and leaves nothing installed. An installed requirement that is new enough is left alone. One that is too old is reported along with the `pkg upgrade` command that fixes it. Optional requirements are not fetched. A requirement's name comes from someone else's repo and is used to name a folder on disk, so it is now rejected unless it is a valid package name. That stops a name like `../../tos` from reaching files outside the download folder. `test_pkgremote_deps.lua`.
- **TOS no longer loads libraries from `/lib`.** The system's own module loader searched `/lib` before `/usr/lib`. TOS installs nothing in `/lib`, so on a drive that used to run OpenOS everything found there was OpenOS's own code, running with the system's full privileges. That code took priority over an add-on library with the same name. In Safe Mode, where TOS's OpenOS compatibility layer is switched off, a request for a library such as `term` loaded OpenOS's real `term.lua`, which is exactly the kind of code Safe Mode exists to keep out. `/lib` is no longer searched. Programs running in the package sandbox could never load from it anyway. `test_require_roots.lua`.
- **`pkg fetch` failures have error codes.** These are the first codes for the network and package areas. **E-501** means a remote host did not answer, **E-601** that no configured repo has a package by that name, **E-602** that a name is not a valid package name, and **E-603** that something the package requires could not be supplied. `why` explains each code, and Appendix C of the manual lists them. When a dependency cannot be found, the error carries only E-603, the code for the fetch that stopped, rather than also the E-601 from looking up that dependency. `test_why_failure.lua`, `test_pkgremote_deps.lua`.
- **The emergency terminal can diagnose, not just list files.** When no shell can start, the kernel falls back to a root-only emergency terminal, which had only seven commands: `ls`, `cat`, `mem`, `verify`, `reboot`, `shutdown` and `help`. It now also has `df` (disks and free space), `log [N]` (the last kernel log lines) and `srm status|scan|repair`. Each new command depends as little as possible on parts that might be what broke. `df` asks each disk directly rather than going through the filesystem layer. `log` reads `/var/log/kernel.log` when the in-memory log is gone. `srm` explains why if it cannot load. `test_emergency_recovery.lua`.
- **A generated kernel API reference, with checked permission marks.** `docs/API.md` lists every public kernel function, 755 of them in 63 modules, with its signature and documentation comment. It is generated from the code by `build/make_apiref.py` rather than written by hand, and the test suite fails if it falls out of date. A function that refuses callers below admin now says so: it carries a `--- @tier admin` mark, shown as **admin** in the reference. `build/test_apiref.py` fails if a function enforces admin access without the mark, or carries the mark without enforcing it. Twenty-two functions enforced admin without saying so, among them `pkg.install`, `pkg.installRemote`, `securefs.mount` and `trust.setSecret`. `tos.py check` runs the same check.
- **Two more error codes: a wrong vault passphrase, and a drive too small for TOS.** **E-305** marks a failed decryption, meaning the passphrase is wrong or the data was changed after it was encrypted. The code is added where `vault` checks the data, so every feature that decrypts with a passphrase reports it: `vault`, `tape-auth`'s log and menu, and the tape toolbox. **E-306** marks `deploy drive`'s refusal when TOS will not fit on the drive. `why` explains both, and Appendix C of the manual lists them.
- **The boot self-test battery runs with no window: `python tos.py selftest`.** The one manual step left in a round was pressing the power button in Ocelot. Ocelot is a window around Ocelot Brain, which is OpenComputers' machine without Minecraft, and its jar contains all of Brain. `build/HeadlessTOS.java` builds a computer from Brain's own classes, so it runs the same `machine.lua`, the same native Lua 5.3 and the same component code as the window. The parts match the Ocelot test machine slot for slot. It powers the machine on and runs it at 20 ticks a second. Each round gets a new machine in a temporary folder: a copy of the release, armed, with the checks on a second disk. A log left by an earlier round can never be read as this round's result. The machine powers itself off when the battery ends, and the command exits 0 when everything passed, 2 when a check failed, and 1 when the report is incomplete. On 1 it names the check that stalled and shows the last screen and the end of `kernel.log`. The full battery passes on this build in 25 seconds (115 checks pass, 1 skipped). A deliberately failing check and a deliberately stalled one were run to confirm the 2 and the 1. `--checks DIR` runs a developer's own checks instead. `build/test_headless_selftest.py`.
- **A shell session can be run from a script, on the same headless machine.** `build/headless-session.py SCRIPT` types at the keyboard, waits for text on the screen, and saves what the screen shows. `firstboot` and `login` steps get a fresh install to a shell. `--profile t1` and `--ram` try smaller machines. Its first session found the `reboot` bug below. `build/test_headless_session.py`.
- **`reboot` reboots.** Typed at the shell, it powered the machine off. The shell runs the shutdown inside its own process, and the shutdown's first step tells the kernel's main loop to stop. As soon as that process paused, the main loop ran a shutdown of its own with no reboot flag, and the shell's never finished. A reboot, once asked for, now stays in force for the rest of the shutdown. On the headless machine the shell's `reboot` now returns to the login screen in 15 seconds. `test_reboot_sticks.lua`: 2 of its 13 checks fail on the previous code.
- **A machine with less than 1.5 MB of memory starts at the command line.** The full interface needs about 1.5 MB to be usable. On a 1 MB machine it loaded, then ran out of memory and crashed the machine on the first command, while the command line on the same machine had memory to spare. With no `ui` set, TOS now starts the command line below 1.5 MB and says why. `tui` opens the full interface anyway, and `bootsettings ui panels` makes it the default. Measured on a headless OpenComputers machine. `test_bootcfg.lua`: 6 of its new checks fail on the previous code.
- **The memory TOS needs is stated as measured.** The README said 192 KB was enough to run TOS in a reduced mode and 256 KB enough for the whole system. On a headless OpenComputers machine with the default settings, this build needs 1 MB for the command line and 1.5 MB for the full interface. Below 1 MB it does not reach a usable shell. OpenOS boots in 192 KB on the same machine, as it does in the game, so the measurement can be trusted. The README, CONTRIBUTING and the installer's memory warnings now give the measured figures.
- **Too little memory for logins now powers off instead of rebooting forever.** On a 512 KB machine the user system does not fit, so nobody can log in. TOS said so, then rebooted with the same memory into the same screen, over and over. It now says the machine needs 1 MB and how to fix it, and powers off when you press a key. `test_no_user_system.lua`.
- **The installer checks the space before it copies anything.** It used to copy until the drive was full and then stop halfway. The common case is a Tier 2 drive that already holds OpenOS: TOS needs about 1.9 MB there, and 1.5 MB is free. It now adds up what the copy will take, including OpenComputers' 512-byte cost for each new file. If that is more than is free, it says how much it needs and that a Tier 3 drive holds both systems, and copies nothing. Its wording also caught up with the code: the clean install removes `/boot` as well as `/bin` and `/lib`, and the first boot asks you to set root's password rather than to log in. Run end to end on a headless OpenComputers machine: from OpenOS on a 4 MB drive the installer reaches TOS's first-boot setup in 44 seconds; on a 2 MB drive it refuses before copying. `test_install_space.lua`.
- **Commands that report in the status line are heard again.** Some commands report their result in the line above the prompt instead of printing it: `useradd`, `userdel` and about twenty more. The shell cleared that line after every command before showing the command's output, so whenever such a command printed nothing else, its report disappeared. `useradd alice` asked for the password twice, created the account and said nothing. The report now becomes the last line of the command's output. `test_lastout_kept.lua`.
- **The README is a front door: 117 lines, down from 674.** It has a contents list, the install line with its leading-slash warning as a callout, a first-ten-minutes walkthrough, the requirements, the add-ons, the known limitations and where to go next. Everything else moved rather than went: the boot sequence, the theme keys, the OpenOS library list and the no-preemption limit into the MANUAL, and a map of the source tree into CONTRIBUTING. The walkthrough was run step by step on a headless OpenComputers machine before it was written down, which turned up three bugs fixed above. From an outside review of the docs.
- **A mesh port that belongs to another protocol is named.** TOS talks on modem port 42, which is not on the community's registry of claimed ports. Nothing said that moving it to, for example, 4096 puts TOS traffic on a Minitel network. That still works, but the boot log now warns once and names the protocol, `net status` shows the port, and the manual lists 42 and the claimed ports. `test_net_reserved_ports.lua`.

---

### Package identity, and dependencies across sources

Slice 1 of federated package repos (`docs/FEDERATED-REPOS.md`). Scoping it turned up bugs in today's `pkg`, each reproduced by driving the real modules before it was fixed.

- **A dependency on another disk now installs.** `pkg install <name>` looked for dependencies only on the disk the package came from, so a package on one floppy that needed a library on another failed with "unknown package", although `pkg search` could see the library and the manual said dependencies resolve from any known source. The package's own disk is still searched first, then every other source; the H-20 rule (a directory must hold the package it is named after) now applies on each of them. `test_pkg_cross_source.lua` (8 of 16 checks fail on the previous code).
- **`pkg upgrade` no longer deletes a working package for a candidate it then refuses.** It ran every check before removing the old version except the signature check, which only the install step ran, after the removal. A candidate whose signature did not verify, or an unsigned one on a machine set to `pkg trust require on`, removed the installed version and was then refused, leaving neither. The signature is now checked with the others, before anything is removed. `test_pkg_upgrade_identity.lua` (7 of 14 checks fail on the previous code).
- **#SEC — `pkg upgrade` keeps a package's publisher.** The candidate was picked by name, so a package signed by a publisher you trust upgraded without a word to a newer-numbered copy signed by a stranger, or to an unsigned one; `pkg info` said so only afterwards. A package installed signed by a key now upgrades only to a copy signed by the same key, and the install step checks that key again against the files it actually copies. An unsigned package may still upgrade to a signed one. `--force` is the way through for a publisher who really has changed keys, and the log records the change. `test_pkg_upgrade_identity.lua` (16 of 38 checks fail on the previous code).
- **A dependency can pin its publisher.** A `requires` entry may carry `key = "<64 hex>"`, and that dependency is then only taken from a copy signed by that key. Copies signed by anyone else are passed over, so a disk can no longer stand in for a library by having a directory with the right name, and install checks the key again on the files it copies. A pin never makes a key trusted. An install is now worked out in full before anything is written (`pkg.plan`): a dependency installed from another publisher, or two packages pinning different ones, refuses the install up front with who needs what, and an invalid manifest anywhere in the set is refused before the packages ahead of it are written. `test_pkg_pins.lua` (7 checks fail on the previous code before it stops at `pkg.plan`, which it does not have).
- **Version constraints are kept, not just reported.** A `requires` constraint was only a warning, and only after the files were written: an installed dependency at the wrong version was skipped over, and `pkg upgrade` never asked whether the new version broke a package that depends on it. The plan now finds every case first: an installed dependency at the wrong version, no copy anywhere at the right one, two packages in one install needing incompatible versions, and a package going in that an installed one needs at another version. The install is refused, naming who needs what, with nothing written. A copy that meets the constraint is now preferred over one that does not, even off another disk. `pkg upgrade` refuses a new version that would break an installed dependent or that needs something missing or too old, but only for problems the upgrade would introduce, so a machine already in a bad state can still upgrade its way out. `--force` goes past either. `test_pkg_plan.lua` (23 of 31 checks fail on the previous code).
- **An optional requirement no longer blocks an install.** A package whose `requires` marked a library `optional = true` could not be installed unless that library was on some disk ("resolve failed: unknown package"), although nothing else treats a missing optional requirement as a problem. It is now left out when nothing can supply it, and still installed when something can. `test_pkg_optional_requires.lua` (1 of 7 checks fails on the previous code: the one that matters).
- **`--allow-unsigned` works.** With `pkg trust require on`, a package that is unsigned or signed by a key not trusted here is refused, and the refusal says to use `--allow-unsigned` for one install. No `pkg` command read that flag: `pkg install`, `pkg fetch` and `pkg upgrade` dropped it along with any other `--` word they did not know, and an install by name would not have passed it on to the package or its dependencies even if they had. Following the refusal's advice got the same refusal again, with nothing to say the flag had been ignored. All three commands now take it, and so does every form of `pkg install`: by name, by path, several names, the picker and `--prompts`. `pkg upgrade` also takes `--allow-unverified`, which its own refusal names, and the picker and `--prompts` now pass that one on too; both dropped it. Every existing test of the override set it on the kernel call beneath the command, which is how this went unnoticed. `test_pkg_flags.lua` (16 of 28 checks fail on the previous code).
- **`pkg install --force` works.** The manual says an install that would overwrite another package's files, or that the plan finds contradicted, is refused and that `--force` overrides either. `pkg install` dropped `--force` the same way it dropped `--allow-unsigned`. An install by name also did not pass it on to the step that checks for file conflicts, so a forced install by name could never have gone past one. It now works by name, by path, and from the picker and `--prompts`, and without it both refusals stand. `test_pkg_flags.lua` (6 of the 12 checks for it fail on the previous code).
- **`pkg install --dry-run` no longer installs.** Only `--all` and an install of several names looked at `--dry-run`. `pkg install <name> --dry-run` installed the package, `pkg install <dir> --dry-run` installed the directory, and `pkg install --dry-run` opened the picker and installed whatever was ticked. Every form now prints what it would install, or what the picker would offer, and changes nothing. `test_pkg_flags.lua` (9 of the 11 checks for it fail on the previous code).
- **`pkg install --dry-run` shows the plan.** It printed the names it was given and nothing else, so a dependency at the wrong version, or one pinned to a different publisher, was only found when the real install refused it. It now prints, for each name, what the install would put in (dependencies first) and every contradiction it would be refused for, says whether `--force` would go past them, and names a package it cannot find. Same resolver as the install, so the two cannot disagree about where a package comes from. `test_pkg_flags.lua` gains 12 checks; 7 fail on the previous code.
- **An option `pkg` does not know is refused, not dropped.** `pkg install`, `pkg upgrade` and `pkg fetch` ignored any `--` word they did not recognise. That is how `--allow-unsigned` went unread without anyone noticing, and a misspelt `--dry-run` installed for real. They now refuse, name the option, do nothing, and list the options they take. `pkg fetch` also takes its options before the name, as `pkg install` does; `pkg fetch --allow-unsigned x` used to look for a package called `--allow-unsigned`. `test_pkg_flags.lua` (13 of the 19 checks for it fail on the previous code).

---

### A kernel-side network wait could only time out on real hardware

The boot battery's second Ocelot round answered the question it was sent to ask: `coroutine.isyieldable()` returns **true** in kernel context on OpenComputers, because the whole kernel runs inside `machine.lua`'s coroutine. On a desktop Lua it is false, which is what every off-box test had assumed.

- **`net.waitFor` could not wait from kernel context.** It used that test to choose between yielding to the scheduler (from a process) and pumping listeners with `event.pull` (from the kernel). On hardware the kernel took the process branch. Its yield went to the host, the reply it was waiting for came back as the yield's result and was thrown away, and nothing dispatched it. So it could only time out, and it dropped every other signal on the machine while it waited. That is exactly what `verifyPeer` does inside the handlers for incoming netfs, `rsh` and file-transfer requests, so a trusted peer's verification could never succeed on a real machine. The choice now goes to the scheduler (`proc.inProcess()`), and `net.scan` uses the same wait.

`test_inprocess_waitfor.lua` runs the real `net.waitFor` inside a coroutine standing in for `machine.lua`'s, with a host loop that resumes it the way OpenComputers does (3 of 7 checks fail on the previous code). Self-test `96-waitfor` does the same on the machine. Not yet seen between two real machines: that needs a second computer.

---

### Component methods are callable tables, not functions

Found by the boot battery on its first Ocelot round after the fermi import. On real OpenComputers a component proxy's methods are callable tables (`machine.lua` builds each with a `__call` metatable), and `type()` of one is `"table"`. Seven places asked whether a component method was a `"function"`. Every off-box stub used plain functions, so the whole suite passed, and each of them was wrong on real hardware:

- **`term.gpu()` never marked the glass dirty after a GPU write.** A program with a display capability could change the GPU's colours behind `kernel.display`'s colour cache and the seat's shadow buffer, which is the path behind the black status bar. Its mutating calls are wrapped again.
- **`robot.durability()` answered "robot component has no durability()" on every real robot.**
- **The printer status line showed `?` for paper and ink.**
- **`component <type>` listed no methods at all.**
- The data-card probes in `kernel.datacard`, `kernel.compress` and `kernel.sysinfo` had the same fault in their fallback paths, which a normal boot never reaches.

`test_component_callable.lua` drives all seven with proxies shaped the way `machine.lua` shapes them (8 of 16 checks fail on the previous code), and self-test `92-term` now checks the premise and the wrapper on the machine itself. Self-test checks can also record an observation with `t.note`, which is how `92-term` now reports what `coroutine.isyieldable()` answers at boot.

---

### Eleven fixes from a second cloud session

A cloud session audited `dev` with the TODO's known-issue list in hand, so as not to re-report anything, and pushed eleven commits as `claude/affectionate-keller-8zppnt`, one fix each. Every new or changed test was run against the previous code and fails there; each commit message gives the count. The suite passes (276 tests). None of it has been seen in-game yet, and the first entry **changes how a self-test round is armed**.

**Security**

- **#SEC — the self-test battery no longer runs code from a disk the machine did not ask for.** A `selftest.on` on any mounted disk armed the battery, and the battery runs that disk's `.lua` files inside the kernel, so a floppy in the drive was kernel code execution at the next boot. Only `/etc/selftest.on` arms it now, and only root may create it. The disk still chooses which checks run and carries the options. `build/sync-emulator.py` arms the emulated machine for you (`--no-arm` opts out), and an unarmed machine booted with a test disk says so on the console. See `TOS-Extras/selftest/README.md`.
- **#SEC — a sandboxed program holding `internet` could overwrite any file.** `internet.download(url, dest)` wrote through the raw kernel filesystem, so the kernel, the user database or an rc.d script could be replaced by a package that declared no filesystem access at all. A download now needs `fs.write` and lands through the program's own securefs.
- **#SEC — `compat.io`, `compat.filesystem` and `compat.shell_api` need the `compat.io` capability.** Required by name, they gave a program that declared nothing read and write access to its user's files.
- **#SEC — the `net` capability is confined.** A program could hear every packet after decryption (`net.on("*")`), change a packet before the kernel's own listeners read it, remove the kernel's listeners, and send kernel protocol messages sealed as this machine. It now speaks and hears discovery, chat and the generic replies only, receives copies, and can remove only its own listeners.
- **#SEC — `/lib` and `/bin` are protected paths.** The kernel's `require` searches `/lib` before `/usr/lib`, and the shell looks in `/bin` before `/usr/bin`, so an admin could plant code that the kernel, or root, then ran.
- **#SEC — user code can no longer push the signals the shell trusts.** `tos_interrupt`, `tos_monitor`, `component_removed`, `interrupted` and others were pushable, and every seat's shell acted on them: cleared its command line, unmounted a disk, quit an editor. One rule in `kernel.event` now covers both push routes: the whole `tos_` namespace, and everything the machine itself raises.
- **#SEC — `sudo`'s elevation password gets login's backoff**, counted per account and kept across a reboot.

**Fixed**

- **`rm a b c` removes all three.** It removed the first and said nothing about the rest.
- **Installing several packages from media no longer repaints the whole shell between questions.** An `x and false or y` expression made the "another box follows" flag always nil. The same trap made `keychain.get` return an error beside a value it found and made a successful `transfer.request` return a timeout error. A new lint, `test_andor_lint.lua`, keeps the pattern out of every shipped file. Boot Settings had it six times, with no visible effect, because the config is normalised again after every change.
- **`transfer.request(..., { session = s })` works**, and a file request whose path does not normalise gets FILE_DENY instead of an error.

**Development**

- `run_tests.py` shows add-on tests at their real path on the published layout (`TOS-Extras/...` rather than `../TOS-Extras/...`).

---

### Fifteen fixes from a cloud session, re-verified before landing

A cloud session worked from a fresh clone of `dev` and pushed fifteen commits as `claude/wonderful-fermi-xdomgd`. Each was checked again before it landed: the new tests were run against the previous tree, where 18 of the 19 new or changed test files fail or hang, with the counts the commits give. The full suite passes (271 tests). Two changes still need an in-game check: H-06, and the sealed-traffic rule below. The add-on fixes (cluster Master, PaneUI, selftest) reach installed machines with the next signed utilities pack.

**Security**

- **#SEC — any account allowed to run `net` could rewrite the machine's peer aliases.** The kernel handed the alias module a nil user system, and its admin check read that as early boot. Aliases are admin-only again, and a missing user system now fails closed. The accidental-global lint missed the cause because it did not follow globals past a function's 256th constant; it does now.
- **#SEC — a trusted peer's packet could skip the MAC by leaving `enc` off.** With `encryptComms` on, a non-public packet from a TRUSTED peer we share a secret with must now arrive sealed, which is exactly when a correctly configured sender seals. **Worth checking on a mixed network:** a peer with `encryptComms` off, talking to one that has it on, now has its unsealed packets dropped (with a log line) instead of accepted.
- **#SEC — open sessions now follow the account.** Demoting an admin takes effect in their live sessions at once, and locking an account ends its sessions. `sudo userdel`, `sudo usermod <user> lock` and `sudo passwd <user>` now work; the kernel had checked the stored tier, not the sudo tier.
- **#SEC — chat pairing gives each link its own secret.** Every peer paired in one `net pair start` window used to hold the same secret, so one could read and forge another's mesh mail. Each side now adds a nonce. An older peer still pairs, with a logged warning to update it and pair again. Pairing codes also carry the full ~119 bits again (they had ~113), here and in the cluster Master.
- **#SEC — a guest could rename the machine.** Setting the hostname is admin-only and limited to 1–32 printable characters. Hostnames arriving in TRUST_REQ and HELLO are cleaned the way PING/PONG's already were, and names an older build saved raw are cleaned when `trust.dat` loads.
- **#SEC (cluster add-on) — the Master refuses RELAY_FORWARD.** A relayed packet carried no proof of where it came from, so any trusted Manager could speak for another. No Manager sends relays today.

**Fixed**

- **Changing your password no longer loses your keychain.** `passwd` re-keys `~/.keychain.vault`. When it cannot, or when an admin reset the password, the vault stays on the old password and `passwd` says so. Keychain and alias saves are atomic, and a refused save no longer leaves memory and disk disagreeing.
- **OpenOS compat: `keyboard.isKeyDown` works.** It raised on every machine with a keyboard, which crashed a ported program's Ctrl-C check. It answers for the caller's seat. **`term.read()` no longer freezes the machine** while it waits for a key (H-04), and **the cursor, `term.screen()` and the GPU fallback are per seat** (H-06, H-07). H-06 has not been seen in-game yet.
- **Beeps no longer stall every seat.** The gaps between tones yield. Each sound has a one-second cooldown (critical alerts excepted), so a chat flood plays one chime. A low volume no longer mutes the short sounds.
- **A key typed while a long command runs (`cp` over a tree, say) is no longer lost.**
- **`ping <peer>` works.** It sent a packet no receiver accepted; now it reports the reply time, and takes an alias or a `net scan` index. A new `hostname` reaches peers without a reboot.
- **`netfs` works between two real machines.** Its packets were refused at the trust gate.
- **The syntax highlighter keeps UTF-8 characters whole**, in the shell's editor and in PaneUI.
- **PaneUI's Move reports a refused rename** instead of claiming success, and **`fs.writeFileAtomic` reports a target it cannot replace** instead of a misleading rename error.
- **Cluster: a Manager booted more than five minutes apart from the Master can now pair.**
- **Development:** a fresh clone of `dev` runs green. The release build excludes `.git/`, and the one test that needs the vendored `Reference/` tree is skipped when it is absent.

---

### Every component call checked against the mod's own source

A systematic pass over every OpenComputers component method TOS calls, verified against the declarations in the mod's source rather than against memory or the wiki: `@Callback` annotations across 83 component classes (362 distinct Lua-visible names), plus Computronics' `TileTapeDrive.java` and OpenPrinter's `PrinterTE.java` for the two non-OC components TOS drives. The motive was `robot.durabilityLevel` in the entry below — a method name that does not exist, hidden behind a `pcall`, invisible to off-box tests because a mock proxy answers to anything.

**Found one more of exactly that kind, in the tape add-on:**

- **The tape drive has no getter for speed or volume, so `tape state`, `tape speed` and `tape volume` never reported either.** Computronics' `TileTapeDrive.java` declares `setSpeed` and `setVolume` and no counterpart getters; its whole Lua surface is `getLabel getPosition getSize getState isEnd isReady play read seek setLabel setSpeed setVolume stop write`. All three commands called `drive.getSpeed()`/`drive.getVolume()` inside a `pcall`, so the call failed on every machine: `state` silently printed no Speed or Volume line, and the two bare commands answered `Current speed: ?` forever. TOS now remembers what **TOS** set, per drive address, and labels it that way — deliberately narrower than a getter, because a value set by another computer on the same drive, or set before this reboot, is honestly unknown and is reported as such rather than guessed. Where nothing has been set, the commands say the drive does not report it. (`tape` 2.3.0 → 2.3.1; `test_tape_speed_volume.lua` fails 14 of its 22 checks against the pre-fix file, the source lint among them.)

**The pass is now a check that runs every time.** The mods' declarations are extracted once into `Reference/oc-component-api/oc_api.lua` (26 KB: 48 component types with their methods *and* signatures, the `computer.*`/`component.*` API from `machine.lua`, and the union of all 386 callback names) by `build/gen_oc_api.py`, and `usr/lib/tests/test_component_api.lua` checks every component call in the tree against it — offline, in the ordinary suite. Vendored rather than cloned on purpose: a check that needs 14 MB of Scala first is a check that skips on most machines, and a skipped check is one nobody trusts. Three things keep it honest: inline fixtures that re-create all three historical bugs and assert it catches each; a vacuity gate that counts how many calls it actually judged (the first draft resolved only *inline* proxy bindings, judged 18 calls, and happily passed the very tape file whose bug prompted it — real code writes `local drive = findDrive()`, with the `component.proxy()` inside the helper; resolving proxy factories took it to 318); and a run against the pre-fix files from git, where it names all five dead call sites by line. Its one stated limit: argument shapes are judged for literals only, so the real `use()` bug — which passed `sneaking or false` — is beyond it.

**Verified clean, recorded so it is not re-derived:**

- Every one of the 82 distinct OC component method names TOS calls exists, and exists on the component type it is called on — checked per call site, not per name, because a name existing *somewhere* proves nothing (`getData` is an EEPROM method; `getLabel` is on five different components; `move` takes one argument on a robot and three on a drone).
- Argument shapes match the declared signatures. The only flag the check raised was the robot/drone `move` homonym, which is correct as written.
- Every `computer.*` and `component.*` call in the core (`uptime`, `pullSignal`, `freeMemory`, `beep`, `shutdown`, `getBootAddress`, `getDeviceInfo`, `list`, `proxy`, `invoke`, `methods`, `slot`, `type` …) is in `machine.lua`'s own `libcomputer`/`libcomponent` tables. `component.gpu`-style field access appears only in `bootstrap.lua` and `install.lua`, which run **under OpenOS**, where that metatable exists — correct in context.
- All 14 OpenPrinter methods the `printer` driver calls exist in `PrinterTE.java`.
- The pass independently corroborated open bug **H-03** from a second source: `Keyboard.scala` declares zero `@Callback`s and `isKeyDown` appears nowhere in the mod, so `compat.keyboard`'s call really does index nil. H-03 had been verified against the Ocelot jar; it now has the mod source behind it too.

---

### Three shims, and the kernel hook a sandbox could forge

The compat layer answered to 12 of OpenOS's 25 library names. Which of the missing 13 to add was settled by measurement rather than taste: every `require()` in the nine OpenComputers loot disks and in the OpenPrograms corpus (Vexatos, Magik6k, Gopher) was extracted and checked, discounting libraries a program ships beside itself and the OC globals. Three names came back — `robot`, `process` and `note` — and nothing else. `thread`, `uuid`, `rc`, `bit32`, `tty`, `sh`, `vt100`, `devfs`, `transforms`, `package` and `pipe` were required by no program in either corpus, so they stay unshimmed until something asks. Full method and numbers in `docs/OS-SURVEY-2026-09.md`.

- **#SEC (AUDIT 5, H-01) — any sandbox could forge a display capability and drive the real GPU.** `isolatedModule()` gives each sandbox its own module *table*, but its `__index` reads **through** to the real module — so a function the kernel puts on a compat module purely so `sandbox.lua` can call it was reachable by the sandbox too. `compat.term._gpuForCaps` is exactly that: it gates on a caps table passed as an **argument**, and it sat right beside the override that binds `term.gpu()` to the sandbox's own caps. `compat.` is an allowed `require` prefix, so reaching it needed no capability at all: `require("compat.term")._gpuForCaps({ gpu = true })` handed a capless program a mutation-capable GPU proxy. Reproduced against the real `sandbox.build` with no display cap, where `term.gpu().setBackground()` correctly returned false and the forged builder reached the hardware. `isolatedModule` now takes a set of keys to **mask**: they read as nil and do not appear in `pairs()`, while the kernel keeps the real module table and calls the hook directly. `compat.process._forProgram` is masked for the same reason. Masking is opt-in per module because a function `__index` would put a Lua call on every field read a sandboxed program makes, and on a 192 KB box that is not free. The existing isolation test passed the whole time the bypass was live, because it only ever asked the sanctioned door — authority passed as data is only authority if the caller cannot forge the data. (`test_sandbox_module_isolation.lua`, 7 new checks; both the capped and capless paths through `gpu()` still assert.)
- **`require("robot")` now answers, and it is a rename layer, not a second implementation.** `tos/peripheral/robot.lua` already did the work; what was missing was the OpenOS *shape*, where the direction is in the function name (`swingDown()`, `dropUp(count)`, `detect()`) rather than in an argument. `compat/robot.lua` binds each name to a side and forwards; it holds no proxy, checks no capability and never touches `component`, so the `peripheral.robot` check inside the peripheral module stays the only gate (#SEC H34). `robot.level()` returns 0 — the experience upgrade is a separate component type, and reaching it from under this capability would hand a program a component its capability never named. (`test_compat_robot.lua`)
- **`robot.use()` raised a bad-argument error on every call, on real hardware.** OpenComputers' own `Agent.scala` declares `use(side:number[, face:number=side[, sneaky:boolean=false[, duration:number=0]]])`. TOS passed `sneaking or false` as argument **2** — a boolean where the mod checks for the integer `face` — and because of the `or false`, it passed one there even when the caller asked for no sneaking. Fixed by never putting a boolean in the face slot: when nothing needs arguments 2 and up, the side goes alone and the mod applies its own defaults. `swing` and `place` now take `face` and `sneaky` properly too.
- **Every robot reported an empty tool slot.** `robot.durability()` called `p.durabilityLevel()`, which does not exist anywhere in OpenComputers — the callback is `durability` — inside a `pcall` whose failure branch returned "no tool equipped". So a robot holding a tool said it held none. The real method is called now, an empty slot still reports itself, and a proxy lacking the method reports *that* instead of mistranslating it. Neither bug was visible off-box before, because a mock proxy answers to any method name with any arguments; the new test records the exact argument list and count.
- **`robot.select()` with no argument reads the selected slot** instead of returning "invalid slot", which is what the mod does and what an OpenOS program means by it. `compare`, `compareTo`, `transferTo`, `tankCount`, `selectTank`, `tankLevel`, `tankSpace`, `getLightColor` and `setLightColor` were added to the peripheral module so the shim could forward them rather than reach around it.
- **`require("process")` provides `info()` and `running()`.** Every real use of this API is a program finding its own directory (`fs.path(process.running())`), which makes a plausible-but-wrong path worse than none: a wrong one writes a state file where nobody will look. So `info().path` is the launch path, threaded in by `sandbox.lua`, which is the only thing that knows it; a process *name* like `prog:tetris@1` is never offered as a path, and outside a sandbox there is no launcher to ask and `path` is nil. `process.load()`, `internal.*` and the `list` table are deliberately absent — spawning belongs to `kernel.process`, where the budgets and capabilities are. The binding hook is masked from the sandbox view for the same reason every other kernel hook on a compat module is (#SEC AUDIT 5, H-01). (`test_compat_process.lua`)
- **`require("note")` converts note names, MIDI codes and frequencies.** The mapping is computed rather than tabulated — OpenOS builds 75 entries plus a reverse table plus a pass for the flats — and the test round-trips every code in the `a0`–`b6` range that `computer.beep` can sound. Two departures, both deliberate: `play` clamps a duration to 5 seconds, because a beep blocks the whole machine and on a multi-seat box that stalls every other seat; and it honours `audio off`, because a program that makes noise the operator has switched off is a program they cannot switch off. (`test_compat_note.lua`)

---

### A loot disk offers to install itself

- **A read-only boot disk now gets the install offer.** `/init.lua` offers to copy TOS onto a hard drive when it boots from a floppy, and it recognised a floppy by size alone (`spaceTotal() <= 512 KB`). OpenComputers mounts a loot disk — the TOS floppy found in dungeon chests — through `ReadOnlyWrapper`, whose `spaceTotal()` returns `spaceUsed()`: the size of what is on it, about 1.8 MB for TOS (verified in OpenComputers 1.8.10). So the one disk that most needed the offer never got it. It booted into a root that cannot save a password (the Stage 0a warning), with no way forward short of OpenOS and `install.lua`. A read-only boot disk now gets the offer at any size, and the screen says "read-only disk" rather than "floppy". The one-time-boot skip (#SEC H1) and both confirmations (#SEC H2) are unchanged.
- **Only a writable disk is an install target.** The offer took the largest other filesystem, so a second loot disk, or any larger read-only one, was chosen over the hard drive and the copy failed on its first write. Read-only disks are now skipped.

(`test_init_readonly_install.lua` fails 10 of its 24 checks against HEAD.)

---

### The ADMIN/ROOT split made real

An ADMIN could become root two ways, so every ROOT-only line elsewhere — the shadow file's write, root-level accounts, `protect off`, mounting over a protected path — was a courtesy an admin could walk around. Both are closed, and command packages, the common case, still install on ADMIN.

- **Installing a service package now needs ROOT.** A service is trusted with the machine: rc.d runs it as the principal it declares, and as root when it declares none, through the kernel loader — outside the capability sandbox that confines a command package (MANUAL §15). `pkg install` gated only on ADMIN, so any admin could run code as root at the next boot. `pkg.install` and `pkg.upgrade` now require ROOT for a `service` manifest, checked before any file is written, and a service pulled in as a dependency hits the same gate (the batch rolls back). Command, app, lib, runtime, theme and driver packages stay ADMIN — they run sandboxed with only their declared capabilities. The kernel/boot session (the installer) is exempt. (`test_pkg_service_root.lua`)
- **`cron.add` cannot schedule above your tier.** `opts.user` sets the identity a job runs as, and the tick mints that user's own session, so a tier-2 admin passing `user = "root"` ran the job as root. You may now schedule as an account only if you at least match its tier, so scheduling as root needs root. (`test_cron_actor_tier.lua`)

Still recorded, not changed:
- **A headless machine keeps its boot session.** `kernel.headlessMain` binds `bootSession` to the kernel session and never sets `bootCompleted`. So on a machine with no screen, `users.currentSession()` and `securefs.sessionOf()` answer "kernel" to any caller that has no process principal, for the machine's whole uptime. Nothing found runs user code outside a process principal: event callbacks are bound to their process, and OpenComputers disables `__gc` by default. This is a missing line of defence, not a hole found. `users.currentSession()` also ignores `bootCompleted`, which `securefs.sessionOf()` checks.
- **Remote exec leaks `string.dump`.** The sandbox's `string` copy drops `dump`, but `("").dump` reaches the real one through the string metatable. TOS is open source and `load` is not exposed, so a dump gives nothing away. Noted in case either changes.

---

### A mesh message is delivered, or still held

The operator's design, following the relay-flood fix: relays hold copies only while they can afford to, and the sender is the one that promises delivery.

- **Relay copies follow free memory.** A relay keeps up to 8 passed-through copies while holding one would still leave 48 KB free, and drops them all, oldest first, as soon as free memory falls under that. They are a courtesy, not a promise.
- **The sender keeps its copy and asks.** Every 30 s it floods a small probe ("do you have this?") instead of the whole message. The receiver answers ACK if it has the message and WANT if it never saw it. Only a WANT, or four probes with no answer, sends the whole message again. The second case is how a node too old to answer probes still gets its mail.
- **A re-send now actually arrives.** The sender used to re-flood under the same id, and every relay that had seen the first flood dropped it as a duplicate. A receiver that was offline for the first flood never got the message unless a relay still held a copy: in a three-node line, HEAD never delivered it. A re-send now carries a resend counter that relays treat as new, and the receiver still dedups delivery by the message id.
- **Message ids no longer repeat after a reboot.** They restarted at the same numbers, so a receiver that remembered the old ones dropped a rebooted sender's first messages as duplicates. Ids now carry a per-boot prefix.
- **Nobody in between can mark a message delivered.** Any node could clear a sender's copy with a bare ACK. An ACK or WANT about a sealed message now carries a MAC under the pair's shared secret, and must come from the receiver. Relays still drop their own copies on seeing any ACK, which costs only the courtesy copy.
- **Both ends survive a reset.** The sender's messages awaiting delivery and the receiver's last 64 delivered ids are kept in `/var/lib/mesh/state.dat`. That directory is now admin-read-only, because a message sent with `allowPlaintext` is stored as written. A restarted sender picks up where it was, and a restarted receiver answers a probe with ACK instead of taking the message twice.
- **Smaller:**
  - the tick after a send no longer floods it a second time;
  - a sender holds at most 16 messages awaiting delivery, and a 17th is refused;
  - `meshPending` counts only the sender's own messages, not relay copies.

(`test_mesh_reliability.lua` fails 21 of its 29 checks against HEAD.)

On keeping conversations: each computer needs only its own side, because the other side is what it received. Mail keeps received messages only. A sent folder in the signed mail package would give each end the whole conversation, and waits for a re-pack.

---

### A mount lands where TOS says, not where the disk says

- **`drive mount` took its mount point from the disk.** Without an explicit mount point it joined the TBFS volume's own label onto `/mnt/`, and a label is whatever the disk's author wrote. So `../../var/pkg/secrets` put the disk over that directory when an admin mounted it. The hot-plug mount had always sanitised labels; this path did not. It now uses the same sanitiser, `helpers.safeMountName`.
- **A mount point was checked for ADMIN and nothing else.** `fs.mount` takes any empty or absent directory, so an admin could put a disk where the protected-path guard stops even an admin writing, and so could a label, as above. Two examples: an empty `/var/pkg/secrets`, whose files `crypto.secret()` reads back raw, or an empty `/etc/rc.d`. `securefs.mount` now holds the mount point to that guard, case-folded, with root's `protect off` override as for a write.

  `/mnt`, homes and `/tmp` are unaffected, and `jbod` and `netfs` already kept to `/mnt`. The kernel's own `require` reads the boot disk directly, so no mount reached kernel code. (`test_mount_points.lua`)

Recorded, not done:
- On a USER seat the hot-plug mount is refused, because `securefs.mount` needs ADMIN. `autoMount` ignores what `mount` returns, so the shell still announces the disk at `/mnt/<label>` with nothing mounted there.

---

### A redirect that failed said it had written

- `cmd > file` checked the ACL, wrote through securefs and then reported "Output written to …" whatever the write returned. The ACL lets an ADMIN into `/etc`, but the protected-path guard behind it does not, so `ls > /etc/passwd` was announced as a success and the file was never touched. A full disk or a directory target went the same way. The shell now shows the refusal. (`test_redirect_result.lua`)

Also checked this round and found sound: the three command-line tokenizers (`pipe.parse`, `syntax.tokenize`, compat `text.tokenize`) raised on none of 20,000 fuzzed lines and took under 50 ms on 8 KB pathological ones. Chat pairing (a 24-character code, about 119 bits, one attempt per address per window), `transfer.lua`'s and netfs's path confinement, and the OpenOS compat filesystem, which goes through securefs, all held.

---

### A trusted neighbour cannot fill a relay

- **Mesh relays held whatever they were sent.** A relay keeps a copy of each unicast envelope it passes on and re-floods it for two minutes, and nothing bounded how many it kept. Measured with the real `mesh` and `meshctl`: 40 unique 7 KB envelopes a second for two minutes left a relay holding 3,840 of them, 28 MB. It re-flooded them 13,440 times for 4,800 received. The dedup cache kept 512 ids of any length, so 7 KB ids made it 3.5 MB, and a `ttl` of 1e9 was honoured. Mesh traffic comes only from TRUSTED neighbours, but every relay forwards to its own, so one bad node anywhere in the mesh could exhaust every relay.
  - An envelope must carry a short string id (at most 96 bytes), a list for its path, and a numeric `ttl`, which is clamped to 16. A `ttl` sent as a string used to raise.
  - A relay holds at most 8 copies, the oldest going first, and none over 4 KB. A bigger envelope, or one carrying a plaintext payload table, is relayed once and not held. The origin still retries its own messages until they are acknowledged.

  The same flood now leaves the relay holding nothing and 79 KB in all, with one broadcast per relayed packet. Most of those 79 KB is the dedup cache itself, full at 512 short ids: a real cost on a busy mesh, left as it is because a smaller cache means more duplicate deliveries. (`test_mesh_bounds.lua`)

---

### /var/pkg belongs to the package manager

- **One package could rewrite another.** A package's `files[]` was confined to `/usr/` and `/var/pkg/`, but `/var/pkg/` also holds the manager's own trees, and nothing kept a package out of them.
  - `/var/pkg/installed/<name>/package.lua` is every installed package's manifest: its commands, its capabilities, and the signature verdict `pkg.scan` believes because only `install()` is meant to write it. A package shipping `/var/pkg/installed/mail/package.lua` replaced mail's manifest. After a rescan, `pkg info mail` showed the replacement as signed by "TOS Project", with mail's command running the writer's code. A package could also plant a manifest for one that was never installed.
  - `/var/pkg/secrets/<name>` is each package's `crypto.secret()`, read back raw, so a package could plant or overwrite another package's key.
  - `/var/pkg/remote/` is the remote-fetch staging area.

  All three are refused now, case-folded like every other target check, with a message that says why. The rest of `/var/pkg/` stays package space, and no shipped package writes under `/var/pkg/` at all. (`test_pkg_reserved_targets.lua` drives the real `pkg.install` and fails 9 checks against HEAD.)

---

### One 8 KB packet, 240 KB of heap

- **A packet could fill the machine before anyone looked at it.** `net.handleIncoming` decodes every packet first: before `protocol.validate`, before the BLOCKED check, before any trust decision. So any modem in range reaches the decoder. The M14 comment in `protocol.deserialize` promised a much tighter entry ceiling for network packets, but only `maxBytes` was ever passed, and the decoder's own caps apply per table and are generous. Measured through the real decoder, one 8 KB packet built:

  | Packet | Heap |
  |---|---|
  | `{{},{},…}` (2730 tables) | 215 KB |
  | `{{{}},…}` | 240 KB |
  | distinct keys | 83 KB |
  | distinct strings | 70 KB |
  | `{1,1,…}` | 66 KB |

  The first two are more than a 192 KB machine has. Whether OpenComputers halts, or the decode's `pcall` catches the out-of-memory error, was not tested on a real box.

  `serialize.decode` now takes an optional budget:
  - `opts.maxCost` charges what the decoded value will hold, weighted from Lua 5.3's sizes.
  - `opts.maxKeys` caps distinct string keys, so a field name repeated on every row is paid for once.

  `protocol.deserialize` passes 48 KB and 256 keys. Every hostile shape above is refused after 27–39 KB. The costliest real packets still decode: a storage page that fits one packet is charged 39 KB of the 48, and a 256-name netfs listing 27 KB. Decoding without `opts`, as config files do, is unchanged. (`test_net_decode_budget.lua`)
- **A repo index or a floppy's manifest could do the same at 128 KB.** `pkgremote.index` decodes a `programs.cfg` fetched from a configured repo URL. pkg reads `package.lua` and `programs.cfg` off floppies and network mounts before any signature is checked. Both had only a byte cap, and a hostile 128 KB index built 805 KB of tables (`{{},…}`) or 1.5 MB (`{{{}},…}`) before the per-table entry cap refused it. Whoever runs a configured repo could take down every machine that ran `pkg search` against it. Both now decode under a 64 KB budget, which refuses those after 34–53 KB, and pkg checks a manifest's size (at most 64 KB) before reading it at all. The largest real manifest, Optional Utilities' 8.6 KB `programs.cfg`, is charged 26 KB. (`test_untrusted_index_budget.lua`)

Recorded, not done:
- **storaged's default page does not fit in a packet.** `cluster-storaged` answers `STORE_LIST` with up to 128 rows, and 128 rows fit in 8 KB only when every key is 4 characters or shorter. With 20-character keys the reply is 10,204 bytes, `net.send` refuses anything over 8,192, and the master hears nothing. The fix is to page by bytes or send fewer rows. It lives in the signed cluster add-on, so it waits for a re-pack.

---

### The disk folds what the ACL compares

The third pentest round (2026-09-11) threw generated path spellings at the real ACL instead of reading it again: 4000 of them, then case, Kelvin-sign and trailing-dot variants of every secret and protected path.

- **On a Windows or macOS host every read rule could be walked around.** OpenComputers' default buffered filesystem goes case-insensitive there. Ocelot Brain's `FileSystemAPI.isCaseInsensitive` probes the save directory with `oc_rox` / `OC_ROX`, and `BufferedFileSystem.segments` then resolves each segment with Java's `toLowerCase`. `users.checkAccess` and securefs's protected set compared exact strings, so any USER read `/ETC/USERS.DAT` (every password hash), `/Home/bob`, `/VAR/MAIL/bob`, `/VAR/LOG` and `/ROOT` through the default "a USER may read" rule. An ADMIN could write `/ETC/USERS.DAT`, which is ROOT's alone, and `/TOS/kernel` past the protected-path guard. The Kelvin sign, which `toLowerCase` sends to `k`, did the same with no capital letter: `/var/pKg/secrets`. `ls /HOME` listed every home, and a PATH entry of `/TMP` ran planted programs.
  - `users.pathKey` folds every spelling the disk may merge: ASCII case, the Kelvin sign, U+0130 (Turkish locale), and a trailing dot or space, which a Windows host drops. `checkAccess` decides on the path as written and on its key, and grants only when both do. The key can take access away, never add it, so a case-sensitive host loses nothing.
  - securefs's protected check, its `/home` and `/var/mail` listing filters, and compat `shell.execute`'s unsafe-root check use the same key.
  - `users.create` refuses a name that differs from an existing one only by case, because the two would share a home and a mailbox. (`test_path_acl_properties.lua`)
- **`canAccessAs` failed open on a non-path.** A number, table or boolean became `"/"`, which any USER may read, so the check said yes; a NUL byte made it raise; `securefs.writeFile` with a NUL raised in the protected check. All are refused now, before the root shortcut, and securefs names them "invalid path".
- **`dirIsSafe` judged a PATH entry as typed.** `tmp`, `/usr/../tmp`, `./home/x` and `mnt/` all probe user-writable roots (the probe's join roots a relative entry at `/`), and every one passed as safe. The entry is resolved and folded first now. (`test_alias_which.lua`)

Recorded, not done:
- securefs copy's "into itself" check still compares exact strings. On a case-insensitive disk, `cp /home/a/d /HOME/A/d/sub` should recurse into its own output until Lua's C-stack limit. Not reproduced. Folding the check would refuse legitimate copies between case-distinct directories on a case-sensitive host.
- Accounts made before this change can already differ only by case, and on a case-insensitive host each pair shares one home. `users.create` stops new pairs; existing ones need an operator.
- Trailing-dot folding is defensive. The buffered filesystem keeps `etc.` distinct in memory, and whether its save to disk (or `bufferChanges=false`) merges it with `etc` on Windows was not verified.

---

### The RAM pass: measured, then fixed

A second pentest round (2026-09-11) aimed at memory, because on a 192–256 KB machine running out of it is both the commonest failure and a denial of service anyone can cause. Every figure below was measured off-box (Lua 5.4, `collectgarbage("count")`), and every fix has a test that pins the number and fails against the pre-fix code.

- **A dead program was never freed.** `kernel.event` refused to *run* a dead process's listeners and timers (the M-11 generation check) but never *removed* them, and each entry pins its program's whole environment. `proc.kill` removed the source `proc:<pid>`, which `compat.event` never uses, and a natural exit removed nothing. Every run of a program that listened and exited leaked it: about 257 KB per run in the test, on every route. `event.purgeOwner` now runs on both death paths. (`test_event_owner_purge.lua`)
- **Decoding a packet cost 16–26× the packet.** `serialize.decode` built every string one byte per table slot: 138 KB for one 8 KB packet, and every packet from every peer is decoded before its trust is checked. Strings now copy whole runs between escapes: 1.3–2.6×. `crypto`'s XOR fallback had the same per-byte shape on exactly the card-less machines with the least RAM: 138 KB → 32 KB per 8 KB payload. (`test_serialize_alloc.lua` — with a round-trip property test and a mutation fuzz — and `test_crypto_xor_alloc.lua`)
- **Copying a file needed the file.** `fs.copy` read the whole source into one string, so a 150 KB file could not be copied on a 256 KB machine. `fs.copyFile` streams 4 KB blocks (peak 203 KB → two blocks), and `grep`, `wc`, `head` and `tail` read a line at a time through `helpers.eachLine` (peak 0.9 KB for a 187 KB file; `head` reads one block). (`test_fs_copy_stream.lua`, `test_helpers_eachline.lua`)
- **Showing a file held it up to three times.** `cat` read the whole file into one string and made a `{ line, colour }` table per line. The executor wrapped that into a second table per line, and the view tab wrapped the result into a third. A 32 KB file peaked at 305 KB, more than a 256 KB machine has, and an 8 KB one at 76 KB. `more`, the browser's View and the context menu's View read files whole too.
  - `expandBuf` passes a line that already fits through as the same entry, and a view tab no longer re-wraps output the executor has already wrapped.
  - All four stream the file through `helpers.readLinesCapped`, which stops while 32 KB is still free and says what to use instead.

  The 32 KB file now peaks at 152 KB, the 8 KB one at 39 KB. A view tab still keeps about 170 bytes a line. (`test_view_memory.lua`)
- **Deploying the OS read every file whole.** `deploy <mount>` (an install disk) and `deploy drive` (a raw TBFS drive) each read every OS file into one string before writing it out. The largest are 67–120 KB (`extras`, `init`, `pkg`, `core`, `admin`), and with the panels shell running a 192 KB machine has less than that free.
  - The install disk copies through `F.copy`, which streams 4 KB blocks.
  - The raw drive gets each file in 4 KB pieces, which blockfs appends at the handle's position. Each piece is still all-or-nothing, and the capacity pre-flight runs before anything is erased.

  (`test_deploy_mount_streams.lua`; case D of `test_deploy_drive_preflight.lua` compares 10 KB files on the drive byte for byte.) Two smaller ones have no test of their own: `bg` kept a script's whole source alive for as long as the task ran, and `flash` read a file whole before checking it against the EEPROM's 4 KB.
- **Every package command stayed loaded forever.** Measured on the real add-ons, one cached entry costs 20–82 KB (tetris 69, calc 82, write 82, tape 76, printer 60), so tetris, calc and a document pinned about 230 KB until an uninstall. The two most recently used stay; with under 48 KB free, only the one in use. (`test_pkg_cache_bound.lua`)
- `net`'s discovered-peer table grew by one entry per distinct address that ever pinged; it is capped at 64, evicting an UNKNOWN before anyone trusted.

Measured and left alone: the kernel log ring (64 entries, 16 or 32 on small machines), SHA-256 (one schedule table per call, reused per block), and `srm` and `pkg`, which do not load at boot. The panels shell's transitive heap (`shell.panels.events` ≈ 374 KB off-box) is why the CLI exists and is not a leak.

---

### A pentest, and the sandbox's side doors

An adversarial pass (2026-09-10/11) over the sandbox, securefs and accounts, the shell's command gates, the network stack, and the package manager and boot chain. Every fix below has a regression test that fails against the pre-fix code; the pre-fix run was done by hand for each, against `git show HEAD:` copies. Suite after: FAIL=0.

#### The sandbox had a door for everything

- **A program could name its own principal.** `securefs.forSession` appended the bound session *after* the caller's arguments, so `fs.readFile(p, { tier = 3 })` ran as root from any program holding `fs.read`. The proxy now has fixed arity. (`test_securefs_session_bind.lua`)
- **An open file was the whole disk.** `securefs.open` returned `kernel.fs`'s handle, `proxy` field and all — the raw filesystem component, no ACL below it. A handle is now read/write/seek/close and nothing else.
- **Open modes are a closed set.** Anything without `w`/`a`/`+` counted as a read, and TBFS opens every mode but `"r"` writable, so `open(p, "x")` wrote files the caller could only read — on a raw-drive boot disk, the kernel. Only `r rb w wb a ab` pass.
- **`compat.component` was the raw component bus.** Every sandbox could `require` it — `.filesystem`, `.eeprom`, `.proxy` — with no capability consulted. It is now the same shape over the sandbox's filtered component table and needs the `component` cap. `compat.internet` now needs the `internet` cap (its header claimed it did; the card was reached through the kernel's own component library). A sandbox's `compat` has no `init`/`setProcSleep`, which could replace the `os.sleep` other programs share. `shell.ext` — command code, not an API — left the allow list. (`test_sandbox_compat_caps.lua`)
- **An installed library ran as the kernel.** A sandboxed `require` of a `/usr/lib` library went to the kernel loader, which compiles in the real `_G`, so any package could ship a library beside its command and have it run unconfined, whatever its manifest declared. A library now loads inside the sandbox that required it; rc.d services keep the kernel loader. (`test_sandbox_userlib_env.lua`)
- **A module table was everyone's.** `shell.keys`, `peripheral.*`, `compat.io`, `compat.filesystem` and `kernel.net` came back as the very tables the shell and kernel use: `require("shell.keys").is = f` ran `f` inside every seat's shell, on every keystroke. Every module is now a per-sandbox view that reads through and keeps its own writes. (`test_sandbox_module_isolation.lua`)
- **The `net` capability is a facade.** It was the whole of `kernel.net`: `getTrust()` (set any peer's level, read any secret), `handleIncoming` (inject a packet from anyone), `setServiceArm` (arm rshd), `shutdown`, and the live discovery records, whose `.addr` a program could rewrite to redirect everyone else's `ssh`. Programs get send/listen/find-peers and copies; services keep the module. (`test_sandbox_net_facade.lua`)
- **`computer.pushSignal` forged input.** Only the `tos_*` signals were dropped, so a program holding `component` could push `key_down` or `touch` into another seat's foreground — typing into a root shell. Hardware input and `modem_message` are now refused too; `notify.result()` answers only for a program's own notices. (`test_sandbox_push.lua`)
- The shell's fallback environment (used when `kernel.sandbox` fails to load, which on 192 KB can be memory) handed over the real `string` library and `getmetatable`.

#### Files, secrets and accounts

- **Copying a directory skipped every ACL below its top.** `cp /home /tmp/x` took every home and `cp /etc ~/x` took the shadow file. Each entry is now checked as the caller. `kernel.fs` also recursed forever copying `/` into itself.
- **Secrets at rest were world-readable.** "`/etc` and `/var` are readable by any session" covered `/etc/trust.dat` (every peer's shared secret), `/etc/elevate.dat` (the sudo hash), `/etc/entropy` (the software RNG pool), `worker_bridge_secret`, the kernel log (whose auth entries the log command hides from users), crash reports, swap and `/var/pkg/secrets`. All are ADMIN-read now, and so is an atomic save's `.tos-tmp` copy.
- **An admin could take root.** `changePassword` let any admin reset root's password; `setLocked`, `setTier` and `delete` never compared against the target's tier. Nobody may now change an account that outranks them. The login screen's principal could name any actor and create a root account; it now manages only its own password. Tiers are validated.

#### The shell's tiers were only advice

The tier each command declares was read by `help` and nothing else, so any command without its own check ran for a guest. The shared executor now enforces it. `drive read` (raw sectors, under every ACL on a TBFS volume) is admin-only, `date tz` no longer lets a guest change the machine's clock, and the low-memory rescue power-off no longer mistook the GPU tier for the user's. (`test_dispatch_tier.lua`)

#### Network

- **AES never engaged.** The data card is AES-128 and refuses any key that is not 16 bytes; TOS passed the 32-character peer secret, so every encrypt failed silently to XOR — which a carded receiver then refused as a downgrade. The key is now the first 16 bytes of SHA-256(secret) on both ends. (`test_crypto_aes_key.lua`)
- `netfs` passed a peer's open mode to the backend unchecked (`"x"` created files on a read-only TBFS export; a number crashed the handler). `net pair` installs a shared secret and now needs admin. A peer's claimed hostname is a short printable string or nothing; a numeric one crashed `net peers` for everyone. (`test_netfs_open_mode.lua`, `test_net_pair_gate.lua`, `test_net_peer_claims.lua`)

#### Packages and the boot chain

- A service package could install `/etc/rc.d/20-rshd.lua` — the kernel-tier allowlist is by file name — or any `/etc/*.cfg`, including `component_caps.cfg` and `pkg_trust.cfg`. Package targets are now shape-checked, system rc.d stems and system configs are refused, and an existing file no package owns is never clobbered. `/usr/bin` is no longer a kernel library root: the shell requires add-on names in kernel context, so a command file named `mail.lua` ran unconfined. (`test_pkg_protected_targets.lua`)
- `pkg` parsed `package.lua` and verified its signature on two separate reads, so storage that answers each read differently (a netfs mount) could pass a forged manifest as trusted past `pkg trust require on`. It reads once. (`test_pkg_manifest_read_once.lua`)
- A 404 or 500 body came back from a fetch as success, and a failed append truncated a download that was then renamed into place. (`test_internet_transport.lua`)

#### A fresh Windows clone was red

Git on Windows defaults to `core.autocrlf`, and there is no `.gitattributes`, so a clone checks out CRLF. Two tests pattern-match source text across lines and failed before anyone changed anything. Both normalise line endings now.

#### Recorded, not done

- **Service packages are full trust** (above, and MANUAL §15). Making them confinable means a separate principal per service and library loading that does not need kernel context; recorded rather than half-done.
- **blockfs accepts any open mode** and treats it as a write. Every TOS caller now checks first; fixing the driver itself changes a signed package, so it waits for a signed re-pack: `if mode ~= "r" and mode ~= "w" and mode ~= "a" then return nil, "unsupported mode" end`.
- **Network, from the auditor's notes, unverified:** the mesh seal's MAC omits the sender and user fields, so a relay could rename the sender of sealed mail; a TRUSTED peer's packet without `enc` skips the MAC; a relay's outbox and seen-cache are unbounded against a TRUSTED neighbour; one pairing window's secret is reused for every peer paired in it; `findPeer(name)` takes the first match rather than the most trusted.
- **Other notes:** a guest can read everything under `/etc` except the secrets above; `/tmp` and `/public` have no sticky bit; the Settings app's status-bar choice is machine-wide and writable by any user; the redirect cap in `kernel.internet` is dead code, since the card follows same-scheme redirects itself; `ed25519.verify` accepts small-order keys (no path reaches it without an operator trusting a degenerate key); `users.currentSession()` still falls back to the legacy global the emergency shell sets. A registry of sessions `users.lua` minted would retire the whole "any table with `.tier` is a principal" class; it would touch most of the suite's fixtures, so it is recorded here.

---

### A crash you can read from across the room

#### The stop screen

A kernel panic used to print a red `KERNEL PANIC` banner and the raw error into
the black boot log. It now draws a full-screen STOP page: solid blue, white
text, the error's code, the failure itself and the way out — an homage to the
blue screen, in TOS's own words. It reads as "this machine has crashed" from
across a room, which is most of what a crash screen is for.

The colour is not the obvious one. OpenComputers' Tier 2 GPU draws from OC's
own 16-colour palette, not VGA's, so the classic VGA blue (`0x0000AA`) would
snap to whatever happened to be nearest. That palette's blue is `0x333399` —
confirmed against the emulator's `PackedColor` — and that is what Tier 2 paints.
Tier 1 is monochrome and has no blue at all, so it gets inverse video. Only
Tier 3 draws `0x0000AA`.

Two things the old screen could get wrong are handled on the way. A long
traceback scrolled the error's own first line off the top of a small screen;
the lines now carry priorities, so on a 50×16 Tier 1 screen the spacers, the
hex and the traceback's tail give way first, and the STOP line and the error
itself are the last to go. And the page resets the GPU to the visible buffer
before drawing, since a panic landing mid-frame would otherwise paint it onto
an off-screen page. `test_stop_screen.lua` lifts both functions out of
`/init.lua` and runs them; that file has to stay Lua 5.2-parseable, so the test
also checks the new code uses no 5.3-only operator.

#### Error codes, in three spellings

Every error TOS names now has one entry in `tos/kernel/errors.lua` and three
spellings: `E-402` for an operator to read, say and search for;
`ERR_PATH_PROTECTED` for programs and for `why`; and `0x00040002`, a
machine-only reference on the stop screen. The hex is computed from the
E-number, never stored, so the two cannot disagree. Numbers group by subsystem
— 1xx boot, 2xx kernel, 3xx files, 4xx access, through 8xx shell — and a code
is never reused once it has shipped.

The EEPROM's fault codes keep their two characters (`C1`, `K4`): the digit is
the beep count, so a machine with no screen still says which fault it hit, and
the BIOS has about 150 bytes to spare. Each maps to a registry entry whose
index is that same beep count — `K4` is `E-104 ERR_KERNEL_MISSING`. SRM's
explanations moved into the registry too, so what SRM says and what the stop
screen shows come from one table.

Refusals carry their code at the end of the message —
`[E-402 ERR_PATH_PROTECTED]` — which survives every path a message travels
without threading a second value through each of them. `test_error_registry.lua`
scans every Lua file the manifest ships and fails on any tag naming a code the
registry lacks, or the wrong symbol for a real one.

#### `why` reads codes

`why` used to identify a refusal by matching words in its message — a substring
match against text defined in another file, which needed its own test just to
notice being reworded. A tagged refusal is now identified by its code alone, so
its wording can change freely; prose matching stays only for messages that
predate the registry and the ones OpenComputers writes itself. And `why` takes a
code directly — `why E-402`, `why ERR_PATH_PROTECTED`, `why K4` — so a code read
off a stop screen or a log can be looked up after the reboot. Anything that is
not recognisably a code still means a command: `why ls` is unchanged.

---

### A failed write changes nothing

From a follow-up review (2026-09-10) that re-checked every finding of the
first against the code rather than the changelog — 12 of 14 fixed, one fixed
better than suggested, two open — and found one new defect.

#### TBFS leaked blocks when a volume filled — blockfs 1.2.1

A write that ran out of space returned false, which was right, and kept every
block it had already allocated, which was not. `mapBlock` links each new block
into the in-memory inode as it goes; the write bailed halfway, and `P.write`
returned without writing that inode back. The bitmap held used-bits for blocks
nothing referenced. On the reviewer's 256 KB reproduction, 8 blocks went each
time the volume filled — recoverable with `fsck --repair`, which nobody has a
reason to run after an ordinary disk-full error.

Fixing it exposed a second, quieter fault in the same loop. It mapped and wrote
one block at a time, so a write that ran out of space had *already overwritten*
every existing block it passed on the way: a failed write into the middle of a
file left the front of the target range changed and the size unchanged — data
modified by a call that reported failure.

Writes are now all-or-nothing, as OC's own managed filesystem is. A first pass
maps every block the write needs and journals each allocation and link; if one
fails, the journal is undone newest-first and no data has been touched. Then
the data goes down. The I/O is identical — the reviewer's own harness reads
1,096 sectors and writes 649 before and after — because the same `mapBlock`
calls happen, just ahead of the data writes instead of between them, and
metadata still lands after data, so the crash-ordering guarantee holds.

`test_blockfs_enospc.lua` is the reviewer's reproduction, shipped as they wrote
it, with an all-or-nothing section added. Against the old driver it fails
twice: the 8 leaked blocks, and `last 100 now: NNNNNNNNNN...`.

#### `deploy drive` erased the drive before finding out TOS would not fit

The review flagged that `deploy drive` never checked the inode budget against
the manifest. Driving the real command against the real driver showed that was
half of it. The command formatted first and found out afterwards: a drive too
small for the OS was wiped — 890 sector writes in the test — and then filled
until it ran out, printing a `FAIL <path>` line for each file that didn't make
it. And a drive with room in bytes but too few inodes quietly lost every file
past the inode limit: 50 of 300 in the test, on a 1 MB drive with space to
spare.

Both are knowable before touching the drive. `blockfs.plan()` is the layout
`format()` will write, and `format()` is now built on it, so the two cannot
disagree. `blockfs.blocksFor()` is what one file costs, indirect pointer blocks
included. `test_blockfs_plan.lua` checks both against the real on-disk layout
and the real allocator at every mapping-tier edge. `deploy` now refuses *before
the erase prompt* when TOS will not fit, and says nothing was erased. Too few
inodes is fixable rather than fatal: deploy knows exactly how many it needs, so
it sizes the table for that instead of taking the one-per-4-KB default.
`test_deploy_drive_preflight.lua` drives the real command against a fake drive
that counts its sector writes, so "nothing was erased" is measured.

For today's 152-file manifest, bytes run out first; the inode case needs
roughly 250 files on a 1 MB drive. It is covered because the manifest grows.

#### Recorded, not done

The review's install-profile item (`install.lua --profile minimal`) is in the
ROADMAP with its measurements: the release grew ~102 KB in six days with the
file count flat. So is its note on the network install — `bootstrap.lua`
verifies downloads against a manifest fetched from the same host, proving
consistency rather than provenance, and pinning an Ed25519 key in the bootstrap
would move the root of trust to the one file an operator can read first.

---

### Findable

An outside review of why nobody finds TOS, acted on where it is code and
documentation rather than marketing.

#### The README was written for contributors who don't exist yet

951 lines, and the order was backwards for everyone who is not already here.
Line 14 was branch policy — a stranger learned which branch to open pull
requests against before learning what TOS *is*. Five consecutive release-note
sections ran from line 33 to line 330. System Requirements was at 332. The
install command, which is genuinely one line and genuinely good, was at 557.

Reordered, not rewritten: the hook, the requirements, the one-line install and
the answer to "why not just use OpenOS" are now the first forty lines. The
release notes moved to `CHANGELOG.md`; the two oldest were not duplicated
there — the CHANGELOG *pointed back at the README* for them — so those were
moved rather than deleted. The branch table moved to `CONTRIBUTING.md`, where
the audience for it already is.

**The Minecraft and OpenComputers versions are now stated literally**, in the
first paragraph, where every forum reply will ask for them. "Lua 5.3/5.4
architecture" was in there, decodable to OC 1.7+ by someone who already knew;
an unanswered version question reads as abandonware.

#### TOS is invisible to OPPM, the package manager everyone already has

`oppm` hardcodes the branch name `master` when it fetches a repository's
`programs.cfg`. TOS's branches are `main`, `dev` and `optional-utilities`, so
`oppm register` on this repo has always failed silently. TOS reads OPPM repos
as one of its four manifest formats and is absent from one; the irony was worth
two files.

`build/oppm/programs.cfg` is the index for a stub `master` branch carrying
nothing but itself and a copy of the bootstrap. It is validated from both ends
by `test_oppm_index.lua`: it must parse the way *OpenOS* parses it (a bare
table, in an environment with no functions — not merely the way Lua would), and
TOS's own `programs.cfg` reader must accept it. Using our own parser as the
checker is the only thing that keeps the index we publish and the reader we
ship from drifting apart.

#### The bootstrap deleted files it did not own

Writing that package surfaced a real bug. `bootstrap.lua` removes itself once
the install succeeds, and the comment above that block has always said "only
when that is a plain file at the root — never a guess." The code did not check:
it prepended a slash to a relative name and deleted whatever `arg[0]` pointed
at, anywhere on the disk.

Harmless while the only documented install put it at `/`. Not harmless with an
OPPM package, which installs it to `/usr/bin` and keeps an ownership record —
self-deleting from there leaves the package manager certain it installed a file
that is gone, and `oppm uninstall` then fails on a machine whose install
worked. The guard now matches its own comment. The decision is a named function
that `test_install_bootstrap.lua` **lifts out of the shipped file and calls**,
because a pattern check would pass against a guard rewritten to do nothing.

#### Recorded, not rushed

Reading an OPPM index with our own parser turned up a second discrepancy: the
translator keeps the leading `master/` segment as an on-disk path, so it
expects a directory literally named `master` inside the repo. A git checkout of
that branch has no such directory — the segment belongs to the URL `oppm`
builds, not to the tree. It costs nothing for the index published here, and
whether treating the key literally was deliberate is not obvious, so it is in
the ROADMAP with the existing test fixture that encodes the same assumption,
and pinned as `[known gap]` so a fix fails loudly instead of passing silently.

Still open, and the largest one: **there is not a single image in the
repository.** `docs/screenshots/SHOTS.md` is the shot list, the capture method,
and the publish prerequisite; the README carries the markup already, commented
out, waiting for the files.

---

## v1.5.0 "Aletheia" — the OS that fits in the machine you have

Named for the Greek spirit of truth, because that is what this release was
about. It began as a TODO burn-down and turned into an audit of TOS's own
claims: comments that justified behaviour the code did not have, prose that
described commands that had been renamed, config keys documented as doing work
that nothing read, and — over and over — packages with a passing test file that
had never been run end to end. Nine subsystems were broken at a seam where two
halves each looked correct alone: cluster pairing, the cluster Master's shipped
package, the worker bridge, `tape store` on a directory, tape-authenticator's
`init`, rc-pilot, the TBFS write path, `drive`'s mount handling, and the
network installer's own hasher.

The method that found them is worth stating, because the passing tests are what
hid them: find a seam where two components must agree, write a test that drives
**both real sides**, and prove it fails against the code as shipped. A test
asserting that a line *exists* passes forever; three of the four bugs an
operator found in the public build had exactly such a test standing guard.

Also here: an operator ran the GitHub release in an emulator and reported six
faults across two rounds — errors running off-screen, a bootstrap that never
cleaned up, flickering dialogs, a trash that silently turned recoverable
deletes into permanent ones, a BIOS that refused to boot anything but TOS, and
a `why` command that could not explain the refusal it was reached for. All six
are fixed. The suite went from 192 passing with 2 failing to 213 passing with
none, and the new tests were each proved to fail against the code they replaced.

### `why` could not explain the refusal it was reached for

`why` with no argument printed its own usage after the operator hit the guard
that stops `rm -r /tos`. It knew about exactly one kind of failure: a tier
denial, recorded by `rootOnly`/`adminOnly`. The protected-path guard is not a
tier check — it sits deliberately *above* the permission model — so the single
most likely refusal on the system was the one `why` had nothing to say about.
Neither did a trash refusal, an out-of-memory, or an unknown command.

The shell now remembers the last thing it printed in the error colour and
`why` explains that. The recording happens in the executor's output sink —
the one place every command's output already passes through, and the reason a
command written tomorrow is covered without knowing `why` exists — plus
`helpers.fail`, which is the shape every refusal already had, so keypress-driven
actions in the file browser (F8 being the reported one) are covered too. The
explanations are matched against messages the producing code really emits, and
`test_why_failure.lua` builds each one *from the module that produces it*
rather than from a copy, so rewording a refusal breaks the test instead of
silently breaking `why`. Where nothing matches, `why` says it has no
explanation and points at `log` — a confident wrong answer being worse than
the usage line it replaced.

### `swap` is a command again, and `optimize` is a real umbrella

Two things the operator asked for, from using the release rather than reading
it. v1.4.0 had folded `swap` into `optimize swap`; the verdict after living
with it was that it reads wrong — `optimize swap status` parses as "optimise
the swap status". `swap` is back as a top-level command, and both spellings
call one function, so the boot-config toggle cannot grow two implementations.

`optimize` gained `power`. The hazard was obvious from the start: a power-saving
mode is the easiest feature in the world to fake, and TOS was already carrying
two config keys that claimed to do this job — `powerSave` ("reduce refresh rate
when on battery") and `refreshRate` ("TUI refresh target") — that were read by
nothing, anywhere, ever. Both are gone. `refreshRate` was deleted rather than
wired, because the shell is event-driven and honouring it would have meant
inventing a polling loop to make a documented knob true.

What replaced them are levers OpenComputers actually bills for, checked against
the config the mod ships rather than recalled: a computer costs a tenth as much
per tick while blocked in `pullSignal` (`sleepFactor`), a screen is billed per
*non-blank* character on it, GPU writes are billed per changed cell, and disk
I/O per kilobyte. So `optimize power save` stretches the idle repaint cadence,
blanks the screen after two idle minutes, and forces the dirty-cell display
buffer on. The blanking draws spaces on black and nothing else — a prettier
screensaver would cost more than the screen it replaced. `optimize power` on
its own reports the machine's *measured* energy and draw rate rather than a
figure computed from constants a server may have retuned.

`swap`'s own report now says that paging spends disk writes, so the two
features do not both claim to be the saving.

### The BIOS refused to boot anything but TOS

Flashing the TOS EEPROM stopped the machine booting OpenOS. The device scan
picks a boot disk by `/init.lua` existing — which OpenOS satisfies — and the
next line demanded `/tos/kernel/init.lua` and **halted** when it was absent.
So any disk that was not a TOS install was found, rejected, and the machine
stopped, on a fault screen advising the operator to run `srm`: a command on
the system that had just refused to start.

The kernel is owed by the `/init.lua` that cannot run without it, which is
ours. The check now reads the file first and applies only when that file is
TOS's own. Keying on the file rather than on a `/tos` directory also survives
a half-deleted install, where leftovers would otherwise go on condemning a
disk that boots perfectly well. Cost: 29 bytes of the 4 KiB EEPROM, leaving
153 free.

Reported by an operator who suspected leftover TOS files and doubted it was
the BIOS. It was the BIOS. `test_bios.lua` grew the three cases that matter —
a foreign disk boots, TOS debris does not block it, a healthy TOS install
still boots — and all three fail against the old EEPROM.

Two related things are written down rather than fixed: a broken TOS install
on the *committed* boot device still loops (the fallback-approval prompt only
appears when the saved address does not work at all), and installing TOS
replaces `/init.lua` with nothing to put it back.

### Four from an emulator round on the public build

An operator ran the GitHub release in Ocelot and found four. Three of them
had a test that passed throughout, because it checked that a line existed
rather than that it worked.

**Errors ran off the right edge.** Deleting `/usr` printed "Delete failed:
Refused: removing /usr is a protected system path. This guard sit" and
stopped mid-word at column 80 — the half of the message that explains the
refusal is exactly the half that got cut. The single status row fits text to
itself by construction; a message that does not fit now uses the multi-row
output region that already existed, which grows upward and stops at the top
of the content area. Short messages still take one row.

**The bootstrap could not clean up after itself**, though it was written to.
`fs.remove` cannot delete a non-empty directory: OpenComputers' filesystem
component does not recurse (the disk-backed one is Java's `File.delete()`),
and OpenOS hands the path straight to it — its own `rm` implements `-r` in
the shell. So every network install left a second full copy of the release,
about 1.2 MB, behind, and a retry's stale-directory sweep could not clear it
either. There is a recursive remove now, used at all four sites. The other
half of the report: the script left *itself* at the filesystem root, so on
success it now removes the file it was run from and says the one-liner will
fetch it again.

**Dialog buttons flickered.** Both modal loops repainted the entire box —
shadow, frame, title, message, buttons — for *any* signal that woke them, and
a dialog waits inside `coroutine.yield()`, which returns on timers, modem
messages and component events alike. None of those change the box. That is
invisible where the dirty-cell shadow has room to elide identical cells, and
plainly visible on a seat where memory pressure has gated it off. Measured
against the old code: six full repaints where one was needed, 90 draw calls
instead of 15. It now draws once and repaints only when the focused button or
the typed text changes, inside the seat's frame so the repaint lands in one
blit.

**The trash, twice.** `rm` asked the trash to take the file, captured its
refusal into a local it never read, fell through to a hard delete and printed
"Removed". A file the operator expected to be recoverable was gone and the
sentence explaining why — "file too large for trash" — had been computed and
discarded. It now prints the reason and stops, naming `--hard` as the thing
the operator can type. A session with no trash at all still falls through,
which is what that path was always for: a guest's `rm` is the irreversible
action they asked for. Separately, the file browser's F8 never used the trash
at all — it called `fs.remove` directly, under a dialog reading "This cannot
be undone", which was true only because of the bypass. It goes through the
same door now, with the same system-path exceptions, and the prompt only
claims permanence when that is true.

### The cluster Master shipped without a file its daemon requires — cluster-master 1.0.1

`clusterd.lua` opens with an unguarded `require("cluster.store_client")`, and
`store_client.lua` was in neither the package manifest nor the builder's
source map — the two places that would have had to know about it, both
missed. It sits beside the six libraries that *are* listed, so everything
works in the source tree and every test passes; the **installed** package was
missing it, and the Master daemon died at load on the machine that installed
it. `cluster-master` is one of the sixteen packages in the published pack, so
this shipped. The pack now carries 44 files rather than 43.

`cluster-storage` had the neighbouring bug: `requires = { "cluster-protocol" }`,
and nothing has ever been named or provided that — `protocol.lua` ships inside
`cluster-manager`. Installing it would have failed resolution on a dependency
nobody could satisfy; it never bit because that package is 0.1.0 and the pack
excludes anything below 1.0.0. `cluster-manager` now provides the alias, the
way `tape` does for `tape-storage`. That is a bandage, and the manifest says
so: a Storage Node should not install a whole Manager daemon to get the wire
format.

Both are linted now. `test_manifests.lua` checks that every module a shipped
file requires from its own package namespace is itself shipped, and that every
declared dependency names a package that exists.

### The worker bridge dropped about one ping in twenty — cluster-manager 1.2.1

`canonicalFrame` — the byte string a frame's MAC is taken over, duplicated in
the Manager-side bridge and the OpenOS worker because the worker cannot
require TOS code — renders numbers with `tostring`. Lua 5.3+ prints an
integral float as `100.0`; Lua 5.2 prints it `100`. OpenComputers ships both
CPU architectures and OpenOS runs on either, so a worker and a Manager on
different CPUs canonicalized the same frame differently and the MAC failed.

Both sides put `computer.uptime()` in their PING/PONG, and uptime advances in
0.05 steps — so roughly every twentieth ping landed on a whole second and was
silently dropped, and the worker was marked "unresponsive" for no reason an
operator could see. Neither side reads the field, so both now floor it. No
lockstep upgrade: a receiver canonicalizes whatever arrived, so an old worker
and a new Manager still agree.

Checked while there and found sound: the two `canonicalFrame` implementations
agree byte-for-byte on ten shapes including raw bytes and nested tables; the
worker's hand-rolled SHA-256 matches FIPS 180-4's own vector; and its HMAC
matches `kernel.crypto`'s, including the past-block-size key path. The format
itself is still architecture-dependent for any future float field, which is
written down rather than fixed — that one changes every MAC and the OpenOS
worker is hand-copied to each box.

### PaneUI's nine themes are pinned to TOS's

PaneUI runs on OpenOS and cannot require `kernel/theme.lua`, so it keeps a
copy of the preset table with a comment saying it is "kept in sync" — and the
README claims it renders TOS's themes "color-for-color". Nothing enforced
either. They do agree today, nine presets and eighteen colours each;
`test_paneui_themes.lua` is what keeps them agreeing, and it names the colour
that moved when one does.

### Creating a directory creates its parents, and the reason it didn't was a false belief

`kernel.fs.makeDirectory` now walks the path and creates each missing level.
Nothing below it does: OpenOS hands the path straight to
`node.fs.makeDirectory` and its own `mkdir` has no `-p`, and the disk-backed
OpenComputers component compiles down to Java's `File.mkdir()`, not
`mkdirs()`. Single-level, every backend.

TOS believed otherwise in writing, and it was costing something. `pkg.init()`
carried a comment saying "the OC proxy creates parents recursively, so a
single call covers /var, /var/pkg, /var/pkg/installed" — and then made that
call. On a fresh *managed* disk it failed at `/var/pkg` and only logged a
warning, so a first install had no package store until something else
happened to create the parent. `backup.lua` had hand-rolled the segment loop.
TBFS grew its own recursion, which is what left the two backends disagreeing:
code written against a raw drive would break when moved to a managed one.

So the guarantee lives in the kernel layer now, once, where every caller
already is. It refuses a file standing in for a directory, names the level a
backend refused rather than returning a bare `false`, and keeps the return
contract callers test (`true` created, `false` already there). The proxies
below stay single-level and portable; TBFS keeps its own recursion because
the boot blob and `deploy drive` hold the proxy directly and pass whole
paths, and its comment now says that is a superset rather than the contract.
Found by an external reviewer who checked the OpenComputers source instead of
taking the comment's word for it. (`test_fs_mkdir_parents.lua`)

Also from that review: `test_rc_pilot.lua` passed here and failed from a
clean clone — its module path listed only the monorepo layout, where
`TOS-Extras` is a sibling of `TOS-Dev`, and not the published `dev` branch
where it is nested inside the source tree. The full suite now runs green in
both. And `CONTRIBUTING.md`'s "roughly `PASS=187 FAIL=0`" is gone in favour of
the property that cannot go stale: `FAIL=0` is the contract, and the runner
prints its own totals.

### The operator decides where cluster task code runs — cluster-manager 1.2.0

An assignment carries Lua source. It comes from the Master this Manager
paired with, so the question is not hostile code — it is what a *runaway*
costs. Mid-task cancellation needs `debug.sethook`, which OpenComputers
withholds, so a task that never returns cannot be stopped: inline, it holds a
kernel timer callback until OC's watchdog reboots the whole computer, every
seat with it. That was the only available behaviour, and it was not written
down anywhere an operator would look.

`task_execution` in `/etc/cluster-manager.cfg` now picks:

- **`inline`** (default, unchanged behaviour) — tasks run on this Manager. A
  runaway reboots this box. `start` warns once, loudly, that the bound is not
  there.
- **`bridge`** — never run task code here; hand every task to an OpenOS
  worker, where a runaway takes out a machine whose only job is running
  tasks. An assignment with no idle worker is rejected rather than quietly
  run here.
- **`refuse`** — run nothing. Assignments carrying task code are rejected at
  ACK time with a reason, so the Master schedules around this node instead of
  collecting a failure per task. The right setting for a Manager that
  contributes storage or presence rather than compute.

A typo'd policy falls back to `inline` with a warning rather than failing
shut. `mgr.status().task_execution` reports the live setting.

### `drive` unmounts, works, and remounts — asking only when it matters

`format`, `check --repair` and `defrag` open a second driver handle on the
sectors, so they cannot run while the volume is mounted. Refusing outright
was correct and useless: it made the operator do the unmount, the work and
the remount by hand every time, for a volume that usually has nothing at all
using it.

They now unmount the volume, do the work, and remount it at the same path.
The question is asked *only* when something would actually be disturbed — an
open file handle, or a process whose working directory is inside the mount —
and it names what: "3 open file handle(s)", "edit (pid 12) is in
/mnt/data/d". The remount runs on the way out of a failed action too, so a
drive is never left detached because an fsck errored. A read-only `check`
touches none of this.

The driver reports its open handles (`blockfs.openHandles`), and
`kernel.fs.mounts()` surfaces that as `openFiles` — nil, not zero, when a
driver cannot say, because "unknown" is not "idle".

### `tape store` on a directory restored nothing — tape 2.3.0

The archive stores each path relative to the base by stripping the prefix as
a string, which leaves the separator behind: with a base of `/home/docs`,
`/home/docs/a.txt` became `/a.txt`, and the base directory itself became `/`.
Restore's path guard refuses an absolute path by rewinding and *returning*,
so the very first entry aborted the whole restore. A directory archive
restored exactly nothing and explained itself only as "REFUSING
absolute/tainted path from tape: /".

Single files were fine, which is why it lasted: `fs.split` returns the parent
*with* its trailing slash, so the same arithmetic came out clean, and the
obvious manual test passed.

Paths are now made relative properly, and the base directory is stored as
`.`. Restore *strips* a leading slash rather than refusing it — the join
under the destination plus the containment check is what actually confines a
hostile path, so `/etc/users.dat` on a crafted tape lands under the
destination instead of aborting the restore, `..` segments and NUL are still
refused, and tapes written by the old code restore too.
`test_tape_archive.lua` drives the real store and restore over a writable
fake tape: 12 assertions fail against the old code.

### Cluster pairing never worked, and a cancel could run the job anyway — cluster-manager 1.1.0

`cluster pair` could not succeed. The Master verifies a Manager's
`CLUSTER_PAIR_INIT` with a MAC over the *Manager's* address (what it saw on
the wire) and signs its confirm the same way; the Manager computed both MACs
over the *Master's* address. Every pairing died at "pair_init MAC mismatch",
and the Manager's own comment named the right address while the code used
the other. Neither side's tests could see it — each was checked against a
hand-built packet by the same author. `test_cluster_pairing.lua` now runs the
real Manager against the real Master pair module over a routed wire with the
real `kernel.crypto`, and fails six assertions against the old code.

A `CLUSTER_CANCEL` landing between an assignment's ACK and its dispatch (one
event-loop cycle later) found nothing inflight, reported "cancelled", and the
assignment then ran anyway and reported a second result. Assignments are
inflight from the ACK. Also: `onCancel` checked the sender *after* the
unknown-id branch, so any peer could make a node emit results to its Master;
the Master's negotiated heartbeat interval was stored and never read (every
Manager heartbeated at the 2 s floor); `tasks_inline` was not type-checked.
`test_cluster_manager_lifecycle.lua` drives the daemon itself.

Mid-task cancellation is another `debug.sethook` casualty: on OC the hook
never installs, and an inline task in `while true do end` freezes every seat
until the watchdog reboots the box. The comment now says so and
`mgr.status().cancel_midtask` reports it; between-task cancellation works
everywhere.

### tape-authenticator: `init` wiped a card that held only a menu — 1.0.2

The refusal to re-initialise a keycard looked at the log alone. A card whose
log was empty but whose menu was not — the common shape, since the menu is
what the launcher uses — was overwritten without a word. Both are checked
now, and `info` reports the menu.

### rc-pilot never worked end to end — rc-pilot 1.1.0

The one add-on with no test, and it could not have passed one. The host put
sixteen *raw* random bytes in the nonce of a frame the EEPROM parses with
`nonce="([^"]+)"`, so one frame in sixteen carried a `"`, the robot saw a
shorter nonce, the MAC failed, and the keystroke vanished — hex now. On a
`modem_message` the host threw the payload away and blocked on a second
`pullSignal()` with no timeout, losing the pong and hanging until a key was
pressed. Prefix resolution called `net.listPeers`, which does not exist. And
the EEPROM was 12 KB of source, 6.9 KB stripped, for a 4096-byte chip that
`flash` refuses to overfill: it could not be burned at all. Rewritten
compact with the same wire format, SHA-256/HMAC and replay window; 3,683
bytes minified.

`test_rc_pilot.lua` drives the real host module against the real EEPROM
source with the real `kernel.crypto`: the robot moves for the host's MAC and
not for a replay, a tampered MAC, a changed op, a wrong magic, a MAC-less
frame, or a different or absent secret; ping is answered; the minified image
fits the chip. `--secret` on the command line is called out as landing in
history, and the host prompts masked when the keychain has no entry.

### TBFS: the cost was writes, and there were two handles on one drive — blockfs 1.1.0

Measured with a counting fake drive before touching anything: writing 64 KB
cost 384 sector writes and 131 reads for 128 data blocks. Three writes per
block — the data, the allocation bitmap rewritten for every *bit*, and the
indirect pointer block rewritten for every *pointer* — and every block was
read before it was written, to preserve bytes a freshly allocated block does
not have. The 4-slot cache added earlier had fixed the read side of that
shape and left the write side alone.

Now 136 writes and 2 reads. A 4 KB file costs 18 sector calls instead of 35
(the TODO's original figure was 58). Removing one file from a twenty-entry
directory costs 7 writes instead of 25. Format halves.

How, without giving up write-through: bitmap and pointer writes are
**coalesced per operation** — pinned in the cache and flushed once when the
outermost batch closes, before the caller is told anything was written. Data
blocks are never deferred. A machine that dies mid-batch leaves data blocks
the bitmap still calls free and no inode referencing them: the same window
the old per-bit writes had, and the one `fsck --repair` already closes. A
test tears a 64 KB write with a drive that vanishes after 40 writes and
proves the repaired volume is structurally clean, with the neighbouring file
intact and later writes working. Fully overwritten and just-allocated blocks
skip the read. File data no longer streams through the cache and evicts the
inode and bitmap sectors on every large read. Block counts are kept as
blocks are gained instead of re-walking the map after every write.
(`test_blockfs_perf.lua`, budgets pinned as loose ceilings)

**Two handles on one drive.** `drive check --repair`, `drive defrag` and
`drive format` opened a *second* driver handle on a drive that could still
be mounted, and the mounted proxy has its own cache, free count and open
files. A repair or defrag rewrote the bitmap and inodes under it; the next
write through the mount would allocate from a stale bitmap. Silent
corruption, and there was no `drive unmount`. Those three now refuse while
the drive is mounted and say why; `drive unmount <addr>` exists; a read-only
`check` of a mounted volume runs but does not count the dirty flag it is
guaranteed to see.

**The dirty flag was permanent.** `kernel.fs.unmount` dropped the mount
entry and never told the proxy, so TBFS's clean bit — set at mount, cleared
by the proxy's `unmount()` — was never cleared through `umount`, and every
fsck of a used volume reported "not cleanly unmounted". The kernel now calls
a proxy's `unmount` when it has one; managed OC disks do not, and are
untouched. (`test_fs_unmount_hook.lua`)

**Two gaps against the interface TBFS claims to match exactly.**
`makeDirectory` did not create parents, which OpenComputers' does and
`kernel.fs` relies on — `pkg` installing into a nested path failed on a TBFS
root. And `rename` would move a directory into its own subtree, cutting the
only path to it. Both fixed.

The pack ships the driver source unstripped, so its size is RAM on the
machine; the new test holds it under 52 KB, and stripping pack files the way
the release tree is stripped is written down in the TODO.

### The black status bar, seventh time: a page keeps its own colours

Every OpenComputers GPU buffer — the screen and each video-RAM page — is
its own `TextBuffer` with its own current foreground and background.
`setBackground` while a page is active sets *the page's* colour and leaves
the screen's alone; `bitblt` copies cells, never that state. Read off the
emulator's own GPU classes with `javap`: `setBackground` dispatches through
`screen(bufferIndex, f)` to whichever buffer is active, and `GpuTextBuffer`
carries its own colour setters over its own data.

The seat proxy kept **one** colour cache for both. A full redraw opens a
frame, paints everything onto the page with the status bar last, and
closes it — so the cache says "the GPU is at `statusbar_bg`". True of the
page. The screen is still at the prompt row's black from the last draw
outside a frame. The 1 Hz tick then re-emits the bar, skips `setBackground`
as redundant, and every cell lands black while the shadow records
`statusbar_bg`. That is the operator's log line (`screen=000000
cache=<statusbar_bg>`), the screendump that showed the page holding a
correct bar over a black glass with an honest blit, and the "sometimes":
it needs the page's last colour to equal the next outside draw's, which a
theme change reshuffles. Four rounds of writer-declaration fixes could not
see it because nothing drew outside the proxy — the proxy's own arithmetic
was wrong about what a buffer switch does.

The cache now describes the *active* buffer and the other buffer's pair is
stashed across `beginFrame`/`endFrame`. The shared test fixture and the new
test give every buffer its own colours, because a fixture with one shared
pair is exactly what kept this green for six rounds.
(`test_screen_page_colors.lua`, `fixture_glass.lua`)

Three things found beside it:

- **The audit checked the wrong cell.** It spot-checked the origin of the
  first draw each second; for the status bar that is column 1, the ramp
  cap, inside the region every tick re-emits anyway. It now audits a cell
  the draw is about to *trust* — an elided prefix or suffix, a corner
  outside a fill's changed box — and a draw that elides nothing audits
  nothing.
- **The audit would have fired every second on a T3 GPU.** It compared
  the cached colour against `gpu.get`, and a T3 stores cells in a 6×8×5
  cube (`0x103C4E` reads back as `0x004940`). The proxy now reads one cell
  back the first time a colour is emitted and remembers what the hardware
  made of it, so the comparison is like against like on any tier. Not
  seen on the operator's T2, where TOS snaps theme colours first;
  unverified on a real T3.
- **The status bar re-sent itself every second.** `drawRampBar` filled
  the whole row with the filler glyph and wrote caps and label over it,
  so the dirty-cell diff saw every cap and label cell change twice per
  tick — four GPU calls a second per seat for an unchanged bar. Filler is
  now painted only where filler ends up; an unchanged tick costs nothing.
  Rendering pinned byte-for-byte against the old algorithm.
  (`test_ui_rampbar.lua`)

### A timer that cancelled another fired twice

`kernel/event.lua` walked its timer array by index, in reverse, and removed
a fired one-shot by that index *after* its callback returned. A callback
that cancelled a timer registered earlier (a lower index) shifted the
array under the walk: the one-shot fired again in the same pass, and the
index removal then deleted a different, already-processed timer. A cron
job cancelling its own retry, or the net layer cancelling a resend from
inside its ack timer, is exactly that shape. TODO.txt had called it
"survivable by argument" because "a fired one-shot is already gone" — it
was not.

Two passes now: collect what is due, then settle each timer's bookkeeping
by identity *before* its callback runs, so a callback may add or cancel
anything. In passing, a rescheduled interval now bounds the pull's wait
(a 0.1 s interval used to wait the full 0.5 s default).
(`test_event_timer_reentry.lua` — 4 of 14 fail against the old loop,
including "fired once on the first pull: got 2")

### The OC sandbox sweep, and what was already true

Against the emulator jar's `assets/opencomputers/lua/machine.lua`: OC
withholds `io` entirely, `os.execute/exit/remove/rename/tmpname`,
`collectgarbage` (absent, not "not always"), `print` (nil until an OS
defines one), every `debug.*` but `getinfo/traceback/getlocal/getupvalue`,
and forces `load` to text mode. TOS already guarded all of it bar one: the
sandbox's own `print` wrapper fell through to the global `print` when a
program had no stdout, and on a low-RAM boot — compat skipped — that
global is nil, so the wrapper meant to serve `print()` would have raised
from inside it. Guarded.

### Prose that said things the code no longer did

README's Known Limitations still described hook-based preemption and the
`preempt.txt` breadcrumb as working; both have been dead on OC since the
`debug.sethook` finding. README and the MANUAL's `edit` entry still
advertised `Ctrl+C` copy, removed when the clipboard landed. README
counted 52 blockfs tests (85). And TODO.txt carried four external-review
items as open — the KDF salt, `pkg trust key` reading masked, manifest
digests, bootstrap verification — that this changelog had already recorded
as done. All corrected; the blockfs one-sector cache is the one that is
genuinely still open.

### The network install died on the hasher it had just downloaded

First install onto a bare OpenOS machine, and it failed at
`fetching the hasher ... sha256:25: attempt to index a nil value (global
'string')`. The suite was 187 green throughout, and could not have been
otherwise: every check on this path reads bootstrap.lua's *text*, and no
amount of reading source reveals a missing global.

`bootstrap.lua` runs the downloaded `sha256.lua` in a sandbox, which is
correct — it is code fetched from the internet. But the sandbox was `{}`,
and a pure-Lua hasher still needs `string` and `table`. The module's body
is nothing but local function definitions, so it loaded and returned a
table quite happily; the failure only arrived when `hex()` was first
**called**. The one call not wrapped in `pcall` was that one, so instead
of taking the "unusable, downloads will NOT be verified" path sitting
right beside it, the error escaped and dropped the operator back to a
shell prompt mid-install.

The sandbox now holds the minimum a hasher needs and still withholds
`load`, `loadstring`, `dofile`, `require`, `os`, `io`, `component`,
`computer` and `fs`. The idea was right; the contents were not.

Bootstrap also **known-answer-tests** the module before trusting it —
SHA-256("abc") against FIPS 180-4's own vector — because "loads and
returns a table" demonstrably does not mean "works", and the alternative
was checking every download with a broken tool.

The regression test executes rather than greps: it lifts the real
`HASHER_ENV` out of bootstrap.lua, loads the real `sha256.lua` into it,
and hashes. Reverting the sandbox to `{}` in a scratch copy produces 6
failures including *"hex() RUNS in that sandbox"*. It also asserts each
dangerous global stays absent, so this cannot be "fixed" later by handing
over `_G`.

Installing is now one line, and runs bootstrap by **absolute path**:

```
wget -f https://raw.githubusercontent.com/Evan450/TOS-Terminal-Operating-System-/main/bootstrap.lua /bootstrap.lua && /bootstrap.lua
```

The old instructions said to save to `/bootstrap.lua` and then type
`bootstrap.lua`, but the filesystem root is not on OpenOS's `PATH`, so
that is "command not found" from every directory and only worked after a
`cd /`.

### Signing keys: the passphrase left the command line, and got a salt

`pkg trust key` took the passphrase as an argument. The argument is now the
publisher *label*, and the passphrase is read masked — the same way `pkg sign`
already did it. The old form echoed the private key across the screen as it was
typed and left it in `S.cmdHistory` for anyone at that seat to recall with
Up-arrow. Passing a second argument is refused rather than guessed at, since a
passphrase with a space in it would otherwise derive the wrong key and print a
public key that is not yours — which you would then publish. `trust key` also
joined the `#SEC M5` history denylist, because someone who learned the old form
will type it once before the refusal tells them not to, and by then the line
exists.

Correcting something said in the previous entry: this history is
`S.cmdHistory`, in memory and per session, not a file. The advice to "clear it
afterwards" was wrong — there is nothing on disk to clear, and no command that
clears it. The exposure is the seat, not the filesystem.

**KDF v2**, which changes every derived key. Three changes, and they are not
equally important:

- **A salt: the publisher label.** One precomputed passphrase→key table can no
  longer yield every publisher at once; each identity has to be attacked
  separately. It adds no secrecy — the label is public and printed in the repo
  README — and does nothing against someone targeting one publisher.
- **4096 rounds, was 512.** Three bits. Recorded plainly rather than dressed
  up: a KDF that could defend a guessable passphrase wants 10⁵–10⁶ rounds, and
  this shares one CPU with every other seat on a 192 KB machine. Defence in
  depth, not a defence.
- **A passphrase floor of 20 characters and 10 distinct ones, enforced.** This
  is the one doing the work. Against a generated 32-byte passphrase the round
  count is irrelevant; against a memorable phrase no round count reachable here
  saves it. So the entropy is the whole defence and is now a refusal rather
  than a paragraph of advice. The distinct-character check is a crude floor,
  not an entropy measure, and does not claim to be.

The salt is **required**, and that is the substantive design call. An optional
salt is the dangerous kind: the same passphrase would derive one key with a
label and a different one without, so a publisher who forgot the flag once
would ship under a second identity with nothing in the output to show it. So
`--as` and `TOS_SIGNING_NAME` are now mandatory, and the label is normalised
(trimmed, lowercased) because a human types it on two machines months apart and
`Discover` must not become a different publisher than `discover`.

Derivation now yields every 256 rounds. At 4096 rounds this is a real watchdog
risk on-box rather than a theoretical one, and the resolve-lazily-tolerate-absent
pattern is copied from `ed25519.lua` so the module still loads under plain Lua
for the off-box signer.

Verified: 187/187, and in a scratch tree the same passphrase under two labels
produced `7ce7390b…` and `6193be2d…`, with a full 16-package pack signed under
a label verifying end to end. Both off-box signers refuse to start without a
label, before writing anything.

**This is a re-key.** Already-published signatures still verify — verification
reads the public key out of the signature record and never runs the KDF — but
the pack has to be re-signed and the README's trust line will carry a new key.
Done now, one day after first publishing and with no adopters, rather than
later.

### The Optional Utilities pack is signed, and says whose signature it is

The published pack now carries an Ed25519 signature on all 16 packages, under
key `0db57e70…` (fingerprint `2D77 9F3E 6B63 1C25`). Operators add it once with
`pkg trust add <name> <key>` and every install from the repo reports `trusted`
from then on.

The pack README carries that line, because without it the signatures were
inert: every install would have read `unknown` — valid, publisher unrecognised
— with no published key to get to `trusted`, and `pkg trust require on` would
have refused the whole repo. The key is read back out of the staged `.sig`
records rather than written into the script, since a hardcoded copy of a
generated value is the drift this project keeps getting caught by. A pack
signed by two different keys is refused outright: operators trust one publisher
identity, so a mixed pack verifies in parts.

Two corrections to guidance that was actively misleading. `sign-package.lua`
closed with "rebuild the pack to carry these into `dist/`", and `CONTRIBUTING`
repeated it. Source signatures cannot reach the pack and never could — the disk
builder injects a `hashes = {…}` block as it assembles each manifest, so calc's
goes 2140 → 2375 bytes and a signature over the source bytes verifies as
`invalid` against the shipped copy. Measured by copying one across and asking
the real verifier, not argued from the code. `tos.py pack --sign` is the
command that publishes; the other two sign source trees for handing someone a
directory to `pkg install` directly.

`Test-Published` verified the 43 files each package *installs* and never
`package.lua` itself — the file carrying those hashes — nor `package.sig`. A
manifest normalised in transit would have broken all 16 signatures while every
content hash still passed: the same blind spot the CRLF break came through, one
file further in. It now compares both byte-for-byte against the staged copies,
which settles it without a second Ed25519 implementation in PowerShell to keep
in step with `kernel/pkgsign.lua`.

Verified against the live branch rather than the build: all 16 signatures
validate over the bytes GitHub actually returns, and a deliberately
CRLF-normalised manifest is caught while all 43 content hashes still pass.

### The suite only passed because of which terminal it was launched from

Three tests enumerate the tree with `io.popen`, and were calling POSIX `ls` and
`find`. Native Lua routes `io.popen` through `cmd.exe` whatever shell started
the run, so those commands resolved only when Git's bin directory happened to
be on PATH. From Git Bash: green. From `cmd.exe`: `'ls' is not recognized`, and
three failures. The Windows `find` is a text search utility rather than a file
finder, so the older comment claiming portability "across Git-Bash and cmd" was
wrong on its own terms.

The failures did not look like a shell problem. Each test opens with a "did I
find anything at all" gate, so an empty enumeration surfaced as
`file enumeration works`, `found at least one top-level dev script` and
`found source manifests to lint` -- which read as a broken checkout. Those
gates are the reason this was catchable at all: without them an empty
enumeration passes every assertion vacuously.

They now use `dir` and `cd`, cmd builtins that need no PATH lookup, with the
working directory stripped back off so paths keep the shape POSIX `find` gave.
Verified from `cmd.exe` with Git's tools removed from PATH, and from Git Bash,
187/187 in both.

This also corrects the previous entry. The same three tests had been failing
intermittently under the parallel pool, and that was attributed to contention
over shared scratch and fixed by serialising them. Wrong cause: it was the same
PATH lookup, failing occasionally when 16 workers resolved `ls` at once and
deterministically when it was not there at all. With builtins there is nothing
to look up, so the three went back into the pool and have been stable across
six runs. Serialising them fixed nothing; it hid it, and the note explaining
why has been corrected in place rather than left to read as settled.

### Signatures reach the network, and one command runs the toolchain

`programs.cfg` now advertises each `package.sig`. It had to: `pkgremote`
downloads only what the index lists and `pkg.install` looks for the signature
beside the manifest, so a signed pack was arriving UNSIGNED over `pkg fetch`
while verifying correctly from a floppy. With `pkg trust require on` that is
the difference between installing and being refused, and nothing would have
told an operator which half was wrong. `test_repo_index.lua` fails if a
signature exists in the pack and is missing from the index; proved by deleting
one entry and watching it name the file.

`build/sign-package.lua` signs one package in place, or `--all`, or prints the
public key with `--key` and signs nothing -- the thing a publisher needs before
they have anything to sign. It drives `kernel/pkgsign.lua` over a filesystem
shim exactly as the disk builder does, so a package signed off-box, one signed
by `pkg sign` on a booted machine and a pack signed by the builder cannot
disagree about what a signature is. Writing it turned up an ordering trap worth
recording: `ed25519.lua` requires `kernel.sha512` at load time, so the hashers
must be in `package.loaded` BEFORE it loads. Loading all four and registering
them afterwards leaves ed25519 the only one that quietly fails, and the error
then reads as "no crypto modules found" -- pointing at the search path rather
than at the ordering.

`tos.py` is one entry point for the whole toolchain: `test`, `build`, `pack`,
`sign`, `key`, `check`, `roadmap`, `publish`. Every path resolves from the
script rather than the shell, so it works from any directory, and it echoes
each command it runs with the directory it ran in -- the point is to remove the
choreography, not to hide it. `check` is the useful one day to day: only the
checks that catch a generated file drifting from its source, which is the
mistake this project makes most.

Adding it immediately tripped `test_release_excludes.lua`, which derives the
top-level dev scripts rather than trusting a hand-written list and so knew
about `tos.py` before either build script did. It had already shipped into
`TOS-Release` once by then. Both build scripts exclude it now.

### verify stops taking the filesystem's word for it

`system_manifest.lua` now carries a SHA-256 per entry, so `verify` and the boot
self-check test that files are *unmodified* rather than merely *present*. The
consumer side turned out to have been there all along — `kernel.verifySystem`
has read a `file.hash` field since #SEC C1 and counts a mismatch as damage —
and nothing ever wrote one. `strip.lua` injects them over the emitted bytes,
which is the only place they can be taken: the source file differs from the
stripped one, so a digest computed in `TOS-Dev` would be wrong for every
release. The Dev manifest stays digest-free by design, or every source edit
would dirty it.

The manifest cannot carry its own digest — injecting one changes the bytes the
digest was over — so that single entry is left alone and vouched for by the
EEPROM anchor instead. That is the shape of the chain: EEPROM vouches for the
manifest, the manifest vouches for everything else. The first version of the
generator emitted `critical = false hash = "..."`, missing a comma, which
`serialize.decode`'s permissive parser accepted while real Lua refused — so the
manifest read back perfectly and would have bricked the release. Caught by
parsing the output with plain `load()`, which is what `init.lua` actually uses,
and pinned that way in `test_manifest_digests.lua`.

`bootstrap.lua` now verifies every download against those digests: it fetches
the hasher first, checks it against its own manifest entry, verifies each file
*before* writing it to the staging tree, and refuses the whole install on any
mismatch rather than handing a partly-suspect tree to the installer. The
comments state plainly what that does and does not prove — the manifest and the
files come from the same host over the same connection, so this establishes
"these are the bytes that repository is serving", not "these are the bytes
Strata published". Closing that gap needs a signature checked against a key
pinned in `bootstrap.lua` itself, which is written down and not done.

### Contributors can build and sign an add-on now

`TOS-Extras` is published inside the `dev` branch, so one clone carries the OS,
the add-on source and the whole test suite: `PASS=187 FAIL=0`, no skips. The
skip mechanism added last round stays as a fallback, but nothing needs it.

That layout change broke three things quietly, and each is worth naming. The
disk builder located `kernel/sha256.lua` only via a sibling `TOS-Dev`, so a
contributor's first build produced packages with **no hashes at all** — and
`pkg.install` refuses an unverified package, so their work would have looked
broken for a path reason. `--sign` failed the same way on `sha512`, `ed25519`
and `pkgsign`, meaning signing was unavailable to exactly the people it exists
for. And `build-release.sh` would have swept every package's source into a
contributor's OS image, because the exclude list had no `/TOS-Extras/`. While
fixing that last one it turned out `build-release.cmd` had already drifted from
the `.sh` — missing `CONTRIBUTING.md`, `ROADMAP.md` and `SECURITY.md` — because
the lint only pins the names it is told about. All four are pinned now.

Signing itself needed no changes: the passphrase comes from
`TOS_SIGNING_PASSPHRASE` rather than a flag, because argv reaches shell history
and that passphrase *is* the private key. Verified end to end in the nested
layout with a throwaway key, 16 of 16 packages signed. Documenting it did
surface an inconsistency worth fixing: `pkg trust key` takes the passphrase as
an argument, which is the thing the builder refuses to do. Written into the
queue; the doc warns the reader in the meantime.

### Checking the published thing, not the thing we published

`pkg fetch` was refusing 39 of the pack's 59 files, and had been since the
pack went public. The build hashed the bytes it wrote; publishing put those
bytes through git, which normalises text to LF in the stored blob. This is a
Windows checkout with `core.autocrlf=true`, so 64 of the 87 source Lua files
carry CRLF, the recorded SHA-256s were computed over those CRLFs, and
`raw.githubusercontent.com` served LF. Fixed at the one seam where package
content is read, so the bytes hashed, the bytes written and the bytes git
stores are the same bytes — which is what `strip.lua` has always done for the
release build.

The interesting part is why nothing caught it. On a physical floppy the
manifest and the files travel together unnormalised, so the disk path verified
correctly the whole time; the two halves disagree only after git has touched
one of them. Every guard was on this side of that boundary — the index matched
the built disks, every advertised path returned 200, the built pack matched its
source. All true, and all measuring the wrong side.

So publishing now fetches the artifact back and checks it as a stranger's
machine would: every manifest hash against the served bytes for the pack, all
152 manifest paths plus the BIOS byte budget for the OS branches, and for `dev`
that the private working notes are genuinely absent. It runs automatically
after a push and standalone via `-VerifyOnly`. It caught one thing immediately
— itself: measuring `dev`'s unstripped `bios.lua` against the 4 KiB EEPROM
budget, which is what the strip pass exists to achieve and not a property of
the source.

Two more guards on the same fault line, since this is the third time a
generated artifact has drifted from its source with nothing watching the join:
`test_repo_index.lua` refuses any CRLF in the pack and checks every manifest
hash against the bytes on disk, and `test_build_disk.lua` now diffs the
checked-in pack against a fresh build by content rather than by mtime — mtime
being a proxy that calls a touched file stale and a byte-identical rewrite
fresh. Both were verified by breaking them deliberately.

### An outside reader ran the suite, and it was red before they started

Someone reviewed the published repo and sent findings. The most useful one was
also the most embarrassing: a fresh clone of `dev` reports 14 failures, because
14 tests drive add-on packages from a sibling `TOS-Extras/` tree that is not
published anywhere. `CONTRIBUTING.md` tells people the suite should be green
before they start work, and it cannot be. They spent several attempts trying to
reconstruct the tree from the `optional-utilities` branch before concluding it
was not possible — correctly, since that branch ships the *installable* layout
(`write/usr/modules/write/init.lua`) and the tests want the *source* layout
(`modules/write/init.lua`).

Publishing that tree is a decision already in the queue, so the fix here is the
honest interim one: `run_tests.py` notices the sibling tree is absent and
reports those tests as SKIPPED rather than FAILED, with a note saying why. A
fresh clone now reads `PASS=151 FAIL=0 SKIP(needs TOS-Extras)=14`. The signal is
the test's own source — a test that names `TOS-Extras` is one that drives it —
because matching on failure *output* misses most of them: they fail with
package-specific messages like "could not load tape-authenticator" that never
mention the tree. It only ever downgrades a failure, and only when the tree
genuinely is not there; with a full checkout a broken Extras test still fails,
which was verified in both directions before this was believed.

The disk requirement in `README.md` was wrong by a factor of sixteen. It said
100 KB. The 152 files the manifest installs are ~1,518 KB, and OpenComputers
charges a per-file cost on top, so the real footprint is ~1,594 KB — a Tier 2
disk, not the floppy or Tier 1 HDD the old figure implied. An operator
provisioning by the README would have run out of space partway through their
first install.

`SECURITY.md` now exists, with a private reporting route and a scope section
that names the known limits up front rather than letting someone spend an
evening rediscovering them. The manual's security model gained three more
honest limits: `securefs` ACLs are policy inside a running TOS and evaporate
when the disk is moved to another machine, the manifest records presence rather
than integrity, and `bootstrap.lua` verifies the size of what it downloads
rather than the bytes.

`blockfs.close(nil)` raised `table index is nil` from inside the driver instead
of returning false — it now points the caller at their own missing check on
`open()`.

Not everything in the report held up. It said no unit test covers the
filesystem: `test_blockfs.lua` has covered create/write/read, rename, remove,
remount, fsck, repair and defrag for some time — the reviewer could not see it,
because it lives in the unpublished tree, which is finding one wearing a
different hat. It said the software RNG merely warns: secret-bearing stores
already refuse (`#SEC CR-7`), and the pool already mixes free memory, heap
addresses, keypress timing and a cross-boot persisted blob. Its three
bytecode-blocker line numbers point at `main`, not `dev`, and there are two of
those loaders rather than three.

What did survive from the filesystem section was the boundary cases. The
existing test writes a 90 KB file, which lands deep in double-indirect and
proves the tiers work; it never tests the *seams*. `test_blockfs.lua` now writes
4096, 4097, 69632 and 69633 bytes — exactly the 8 direct pointers, the first
single-indirect byte, the last address single-indirect can reach, and one past
it. All four pass, so this is coverage rather than a fix, which is the good
outcome. 54 assertions to 81.

Three findings are real and deliberately not fixed yet, written into the queue
instead: digests in `system_manifest.lua` (today `verify` proves presence, not
integrity, and third-party packages are held to a higher standard than the OS),
verification of what `bootstrap.lua` downloads (blocked on the digests), and a
one-sector cache in `blockfs` (writing 4 KB costs 58 component calls; the
managed-filesystem equivalent is three). The measurements in that section were
reproduced exactly — all six rows of the reviewer's call-count table matched.

### The Optional Utilities pack installs over the wire

The add-on pack is published as a third branch, `optional-utilities`, laid out
as a `pkg` repository: `pkg repo add` it and `pkg fetch calc` installs over an
internet card with no floppy involved. Nothing new had to be invented on the
machine side — `pkgremote` already fetches into a staging tree and hands it to
the ordinary local installer, so hash verification, write-root confinement and
the unverified-package gate are the same code they always were.

Two build-side pieces make that safe. `make-repo-index.lua` generates the
`programs.cfg` index from the package manifests' own `hashes` tables rather
than by walking the disk, so the index cannot advertise a file the installer
would then reject — one source of truth instead of two that agree until they
don't. And it writes with sorted keys: `serialize.encode` walks with `pairs()`,
and Lua randomizes its string-hash seed per process, so the same table encoded
in a different order every run — fine for a wire format, useless for a file
under version control. The format is still proven, by round-tripping the result
through the real decoder before writing.

Packages below 1.0.0 are held back from the public pack (`cluster-storage`,
`rbmk-control` — both still have an open spec draft beside them). The rule is
the version, not an opinion. That also answers the reported symptom: those
packages used to appear in the picker as "not on any installed disk", which
reads as a missing floppy rather than as a deliberate omission; now they are
not advertised at all. `test_build_disk.lua` gained the inverse assertion so a
half-finished package cannot silently rejoin the disk either, and
`test_repo_index.lua` checks that every advertised file actually exists in the
published tree.

### TOS is public, and the repo now has a source branch

TOS is released. The public repo carries two branches with different trees:
`main` is the release build that installers download, and `dev` is the source
— full comments (including the `--!` security and invariant notes the release
strips), the off-box test suite, and the build tooling. `main` is generated
from `dev` by `build/strip.lua`, so a commit made against `main` is destroyed
by the next release build; `CONTRIBUTING.md` and a pull-request template say
so in the two places a contributor will actually look.

Installing works from either branch — both carry the same tree shape and the
same `tos/system_manifest.lua` — so a contributor can test a change on a real
machine with `bootstrap.lua <owner>/<repo> dev` before opening the PR.

`ROADMAP.md` is the public view of the open queue: 61 items, grouped by status,
generated from `TODO.txt` by `build/make_roadmap.py`. `TODO.txt` itself stays
private — it interleaves the open work with a long done-history and names local
paths on the author's machine — so the generator extracts only the open entries
and scrubs anything machine-local. Entry bodies are emitted fenced, because
they are indentation-significant and full of `<addr>`-style placeholders and
leading dashes that GitHub would otherwise eat as HTML tags and stray bullets.
`test_roadmap.lua` pins it: the roadmap must match the markers in `TODO.txt`,
and must not leak a drive path, a home directory or an email. It skips cleanly
on a dev-branch clone, where the generator and its input are deliberately absent.

### A disk-free install path, and the assumption it exposed in the old one

`bootstrap.lua` is a new root-level script for a bare OpenOS machine that
has an Internet Card but no TOS files and no physical install disk at
all. It fetches the release file set (bios.lua, install.lua, and every
file `/tos/system_manifest.lua` declares) from GitHub over
`raw.githubusercontent.com` into a scratch directory, then hands off to
that downloaded `install.lua` exactly as if it were a mounted floppy —
FORCE-WIPE confirmation, BIOS fingerprint check, and post-copy size
verification all run unchanged, because it IS the same installer. It
talks to `component.internet` directly rather than through OpenOS's own
`internet` library, the same low-level approach `kernel.internet` uses
once TOS is installed, so a damaged OpenOS `internet.lua` can't take the
bootstrap path down with it. It also doesn't assume the repo's default
branch (`main` vs. `master`) or layout (bare root vs. a `TOS-Release`
subdirectory) — it probes both before giving up, and a fork or
nonstandard layout can be pointed at directly with CLI args.

Building the handoff surfaced a real assumption in `install.lua` itself:
its disk auto-detection required the source to be mounted literally at
`/mnt/<name>` (`scriptPath:match("^(/mnt/[^/]+)")`), which a
network-staged directory under `/tmp` was never going to satisfy. That
check is now a plain "does the directory this script lives in contain
`tos/kernel/init.lua`" test, with no path prefix assumed — and a
scripted or chain-loaded install (bootstrap.lua included) can skip
detection entirely by naming its source directory as `install.lua`'s
first argument. The other filesystem-scanning method in the same
function also picked up pcall guards around each component probe, so
one disk that throws on `exists()` (e.g. ejected mid-scan) can no longer
abort detection for every other disk on the machine.

### The self-test battery reported its own shutdown as unsafe

Nine on-box checks now (up from seven): `80-pkg-signing` audits real ed25519
and the real `/etc/pkg_trust.cfg` write path through securefs — tamper
detection with no override, trust add/remove, the require-signature gate —
and `90-internet-absence` proves the no-card path and the kill switch. Both
port items off the long-open "Emulator checklist" backlog in `TODO.txt` that
turned out to be provable on a single machine; the rest of that list (a real
printer, a live internet server, a second machine, or a human eyeball) is now
triaged and written down there so it stops being re-litigated every round.

Running the expanded battery for the first time surfaced a real bug, and not
in the new checks: `kernel.selftest`'s `shutdown=true` option called a raw
`computer.shutdown()`, which skips `kernel.shutdown`'s own last act — stamping
`/var/run/pwrstate` "C" for clean. Every armed round was powering the machine
off "successfully" and then reporting *that exact shutdown* as unsafe (a
warning plus two beeps) on the next boot. A battery whose own exit path corrupts the
signal it exists to keep trustworthy is worse than one that doesn't shut down
at all. Fixed to prefer the real `kernel.shutdown` when it's reachable —
which, by construction, is always, except from the off-box harness that has
no kernel table, which is exactly when the raw fallback is what keeps this
testable without a full boot. Confirmed on real hardware: `pwrstate` reads
`C` again.

`sync-emulator.py` — the script that deploys a build and the checks into an
Ocelot workspace by finding the boot disk and the test floppy *by content* —
had no test coverage at all. It does now (`build/test_sync_emulator.py`,
19 cases), wired into `run_tests.py` rather than left for a bare `pytest` to
find on its own: pytest's own defaults silently skip any directory literally
named `build`, which is exactly where this file has to live.

### Two more places still said v1.3.2

The welcome tutorial's first page and a `bootsteps` test fixture were still
quoting the version two releases back (v1.3.2 "Argus"; the OS has been on
v1.4.0 "Iris" since its own release notes went in). The tutorial's line no
longer hardcodes a version at all — it reads `_G._TOS.version` like the
kernel's own boot-log line does, so this can't drift out from under it again.
The root `init.lua` bootstrap's decorative header comment was further behind
still (v1.2.6) and is not wired to anything at runtime; bumped by hand, the
same way `install.lua`'s own banner comment learned to stop doing after an
earlier two-place version drift (see the comment above `INSTALLER_VERSION`).

### screendump was reporting the cache, not the screen

Chasing a status bar that goes black after the menu bar closes, the obvious
move was to have the operator capture the screen. `screendump` exists for
exactly that — "capture this screen to a text file (for bug reports)". It read
the dirty-cell **shadow** whenever the shadow was enabled.

So the tool for diagnosing display faults reported the display cache's own
account of the screen. For the one class of bug TOS keeps having — the shadow
and the glass disagreeing — that is precisely the wrong witness: a row the
shadow believes is painted dumps as perfect, which is the exact case somebody
would be running `screendump` to investigate.

It also captured characters only. A fault that changes **colour and not text**
left no trace at all, and "the status bar went black" is that fault exactly:
same characters, wrong background.

`gpu.get` is the truth and is now used whenever it exists; the shadow is a
labelled fallback rather than the default; the capture says which surface
answered, because one that cannot say where it came from is the same trap in a
different hat; and the background colours come back run-length encoded, so a
correct full-width bar is one line and a broken one says which columns. The
file also records the theme's `bg`, `statusbar_bg` and `menubar_bg`, so a
reader can compare against what the row was supposed to be without guessing.

That costs one component call per cell — about 2,000 on an 80×25 screen, enough
to spend the per-tick call budget and make OpenComputers sleep. Acceptable for
a deliberate, rare diagnostic, but not while holding the machine: it yields
between rows, the way everything else long-running now does.

### SRM was the one long job that never yielded

Reported from a booted machine: `srm` freezes the computer for its whole run
rather than merely slowing it down, and the operator asked whether that was
just because it is the longest command or because it is an outlier. **It is the
outlier.**

SRM reads and hashes every file in the manifest — the longest job in the OS by
a wide margin — and it was the only long job with no cooperative yield in it.
Ten other modules have one: `compress`, `pkg`, `fs`, `ed25519`, the executor's
output chokepoint, and the walk loops in the command files. So `srm scan` did
not run slowly, it stopped everything: no other seat drew, no timer fired.

On OpenComputers that is worse than a freeze. The machine kills a computer that
goes too long without yielding, and TOS's own preemption cannot save it —
`debug.sethook` is not in the OC sandbox. A large enough manifest takes the
whole computer down, and the breadcrumb that would name the culprit is itself
written from inside the hook that never runs.

All five per-file walks now open with the same slice the rest of the OS uses.
It goes **between** whole files, never inside one: `readHashed` reads and
hashes in a single resume, and yielding in the middle of that would let the
hash describe a file that changed underneath it — the test asserts on that
function's body, not on a call trace.

### `help` advertised two commands that no longer exist

`swap` was folded into `optimize swap` in v1.4.0 and `device` into `hostname`,
and the hand-written reference table in `core.lua` kept listing both. Typing
either answered "unknown command", which reads as a broken install. (The boot
settings menu's swap entry is *not* wrong — `swap` is a boot feature name there,
which is a different thing from a command, and the operator's own guess about
that was right.)

`test_command_registry.lua` already checked command → help line. This is the
other direction, and it is the one that rots: the registry entry goes and the
prose stays. It has now happened three times — `ver` was the first, and was
fixed by restoring the alias. The audit walks the reference table, takes the
first token of each row, and requires it to dispatch; two syntax examples
(`cmd1 | cmd2`, `cmd > file`) are listed as the only exceptions.

Getting the audit's boundaries right mattered more than the audit: a first
version cut the table at a marker that does not exist, ran to end-of-file, and
started reading `man` and `keys` prose as command rows. It now ends at the
table's own closing line and rejects any first token followed by punctuation —
which is what separates a row from `fields: ...` or `e.g. ...`.

### Five ways to log out, one of which dropped your elevation

Found by pulling on an operator's observation: the menu bar's Reboot and Shut
Down keep working when `core` will not load. They do — and correctly. Those
menu actions call `helpers.canPowerOff` and then the kernel directly, never
touching the command table, which is exactly why they survived a low-memory
box and let the operator shut down cleanly instead of cutting power and leaving
the dirty bit to cry wolf next boot.

Checking whether the two paths agreed turned up the one next door that doesn't.
`sudo -s` registers a *second*, elevated session and points the seat at it.
Dropping it means three things: restore the shell's token, restore the process
principal, and log the elevated session out. There were **five** logout paths —
the `logout` command, the System menu, the F10 power menu, the `^Q` prompt and
the Desktop — and only the command did any of it. Its own comment states the
rule: *"never carry elevation across logout."* The other four pushed
`tos_logout` straight out, and the kernel's handler retires
`sessionTokens[seat]`, which is the **original login token** — a different
object from the elevated one.

What that actually cost, stated precisely rather than inflated: the elevated
token is discarded with the shell state, so nobody can present it; there is no
session cap to exhaust; and nothing enumerates sessions to an operator. It
lingered as a phantom entry until `sweepSessions` retired it, within
`SESSION_TIMEOUT`.

It is fixed centrally anyway, for two reasons that outlive today's blast
radius. `sudoDrop` also restores the shell process's principal, and that stays
harmless only while every logout path also *kills* the process — the kernel's
handler does, but a future "switch user", or a CLI handoff that reused the
process, would not, and then the elevation rides across. And five copies of a
security rule is four chances to update it in the wrong number of places.

There is now one `helpers.logout(S)`: drop, then push, in that order — a drop
scheduled after the signal would be racing the process kill that follows it.
The Desktop keeps a single inline fallback for the case where `helpers` cannot
load, and that fallback drops the elevation itself; the test allows exactly that
one raw push and fails on any other. Requiring `helpers` at the top of
`desktop.lua` was the obvious move and the wrong one — it is lazily loaded and
would have dragged `computer` in behind it, which is precisely the wrong
direction on a box already short of memory. (`test_logout_elevation.lua`)

### You can always reboot

Reported from a real machine: on a box short of RAM the `core` command
category fails to load, and `help`, `reboot` and `shutdown` stop existing.

All three live in `core`, which is the largest command file in the tree — so on
a tight box it is precisely the one that fails, because reading it wants a large
contiguous buffer and a machine at ~56 KB free has not got one. The dispatcher
returned nil, and the operator was advised to free some memory and try again: by
closing tabs, or rebooting. Which is the command that had just failed.

**That is a trap, not a wording problem.** The advice was correct and impossible
to follow. An earlier pass had already improved the *message* — it used to say
"unknown command", which was worse, since it told the operator their OS had no
`reboot` — but the thing the message was about was still there.

The escape hatch must not need the thing that broke. `reboot`, `shutdown`,
`help` and `mem` are now served from the dispatcher itself, which is already
loaded by the time any of this can happen, and only when the real command is
missing — so a healthy box gets the full versions exactly as before and this
costs nothing. They are deliberately minimal: every line of them is a line that
has to work when nothing else does.

Three things that mattered in the details. The power gate is the *same* one the
real commands use (`helpers.canPowerOff`), with a bare tier check as a fallback
that needs no module load, and it fails **closed** — the rescue is not a way for
a guest to power off a machine other people are using. It prefers the kernel's
clean shutdown and only drops to the raw component call if the kernel handle has
gone, because an unclean restart costs a repair pass next boot, which beats a
machine that cannot be restarted at all. And `mem` is included because the free
figure is what decides between closing a tab and rebooting.

The OOM path already declined to cache the failure, which matters more now: a
box that recovers gets its real commands back without a restart. That is pinned
too — the rescue must hand back the ground it borrowed. (`test_lowmem_rescue.lua`)

### The splash measured the screen before the kernel changed it

Reported from a real Minecraft install rather than the emulator: on a splash
boot with a **Tier 3 GPU and a resized, multi-block screen**, the loading bar
and the wordmark are shoved to the right-hand edge and almost entirely cut off.

`/init.lua` reads the resolution once, immediately after `gpu.bind()` — and
`bind` leaves an OpenComputers screen at its **maximum**. The kernel then
applies the resolution policy from `kernel/screen.lua` (density-based, floored
at 80×25) part-way through `kernel.boot()`, *while the splash is live*, because
`bootProgress` is the callback driving the bar. Everything the splash draws
afterwards is still positioned for the width it measured at the start.

On a Tier 3 GPU over a multi-block screen that is a genuine reduction, 160×50
down to 80×25. Geometry centred for 160 puts the bar at column 60 spanning
60..101 — on a screen 80 wide. Which is the report, arithmetic-exact.

And it explains why the operator saw it *only* there. A Tier 2 GPU maxes at
80×25; a single Tier 3 screen block maxes at 50×16. In both cases the policy
asks for the resolution that is already set and nothing moves. It takes a big
screen **and** a Tier 3 GPU for the boot-time measurement and the applied
policy to disagree at all.

The bar's geometry now lives in `bootsteps.splashGeometry` — pure, so it can be
tested against every screen size — and `/init.lua` recomputes it instead of
measuring once. A `resync()` on each progress message re-reads the live
resolution and, when it has moved, rebuilds the **whole** composition rather
than just sliding the bar: the wordmark and status lines above were centred for
the old width too, and OpenComputers clears the screen on `setResolution`, so
there is nothing up there worth keeping. One `getResolution` per progress
message, a few dozen over a boot, splash-mode only.

Hoisting the `kernel.bootsteps` require above the new `geom()` was not
cosmetic: a local declared *below* a closure is not an upvalue of it but a nil
global read, and `geom` would have taken its fallback branch forever while
looking correct. That is the same failure this release has now found in five
other places, so `test_splash_resize.lua` asserts the ordering directly.

### Two budgets that OpenComputers never let us have

`debug.sethook` is how TOS enforces two limits: the scheduler's wall-clock
preemption budget in `kernel/process.lua`, and the remote-exec step budget —
plus the memory-pressure abort inside the same hook — in
`kernel/net/remote.lua`, wrapped around attacker-supplied Lua from a trusted
peer.

**OpenComputers does not export `debug.sethook`.** Its `machine.lua` builds the
sandbox's `debug` table out of exactly four entries — `getinfo`, `traceback`,
`getlocal`, `getupvalue` — and withholds `sethook` deliberately: the machine
uses its own hook to enforce the "too long without yielding" deadline, and
guest code able to call `sethook` could disarm it. That file ships inside the
Ocelot jar, so this is readable rather than inferred; and OpenOS, which is real
OC code, only ever calls `debug.traceback`, never `sethook`, anywhere.

So on every real machine `if debug and debug.sethook then` is false, no budget
is ever armed, and — the part that matters — **it happens silently**. The
source reads exactly as though the control were active. The comment in
`process.lua` went further and asserted the wall-clock fallback worked on OC.

What this costs, stated plainly rather than left to be rediscovered. A runaway
process or a runaway remote command is still stopped, but by OC's machine
watchdog, which kills **the whole computer** — precisely the blast radius the
preemption code was written to shrink, and on a multi-seat box it takes
everyone down. The `preemptCrumb` breadcrumb that would name the culprit after
such a reboot is itself only written from inside the hook, so it never gets
written either. For `rsh`, the memory-pressure abort is gone too; the
entry-time `MIN_FREE_MEM` check, `CMD_LIMIT`, `OUTPUT_LIMIT`, the TRUSTED
requirement and per-request challenge-response all still hold.

The missing hook cannot be fixed. The claim can. Both modules now expose an
honest probe — `proc.preemptionAvailable()` and `remote.stepBudgetAvailable()`
— so `doctor`, `ps` or any future caller can state the real position instead of
inheriting an assumption; `remote` logs once when it runs a command with no
budget; and the comments say what is true. The hook is still installed wherever
one exists, which is every off-box run, so the suite still exercises the
enforcement path. (`test_sethook_absent.lua`)

Whether `rsh` should *refuse* to run without a budget is an operator's call,
not a bug fix — it would disable the feature outright on the only platform TOS
ships for — so it is written up in `TODO.txt` with both sides rather than
decided here.

One more thing this exposes: the off-box suite runs on stock Lua 5.4, where
everything exists, so **this entire class of bug is invisible to it by
construction**. Same blind spot that hid `ustr` falling back to byte math.
`machine.lua`'s sandbox table is the authoritative list of what TOS actually
gets, and it is sitting in the emulator jar.

So that list is now a test. `test_oc_api_surface.lua` pins the sandbox surface
— `os` is four functions, `debug` is four, `coroutine` has no 5.4-only `close`
— and fails if any file in the manifest reaches for something outside it
without a stated reason. The only acceptable reason is that the call site
guards *and has a real fallback*: `redstone.pulse` uses `os.sleep` when it
exists and `computer.pullSignal` when it doesn't, which is fine; a guard with
no fallback is the bug, not the fix. It carries a self-check so it cannot pass
by having stopped matching, and the header says how to regenerate the list from
the jar rather than edit it to go green.

The rest of the non-UI sweep came back clean, which is worth recording too:
`ustr` survived 33,921 column-math property checks (fed a real `unicode` for the
first time — mixed ASCII, Cyrillic, box-drawing and double-width CJK), and
`serialize`, `fs.normalize`, `net.protocol` and `kernel.pipe` came through
15,000 round-trip and model-comparison checks without a violation, including
hostile input to every decoder.

### Off-box tests can look at the glass now

`70-screen-truth.lua` — the in-emulator check written after three display bugs
"resisted static reading" — opens by saying "no off-box test can see that
because off-box there is no glass". That was true when it was written, and it
is why the suite stayed green while the status bar went black a fifth time: the
existing backbuffer mocks *count calls*, and a call-count mock is perfectly
happy while the code blits the wrong pixels.

`usr/lib/tests/fixture_glass.lua` is glass. It models video-RAM pages, and
`allocateBuffer` hands back a **blank** one exactly as OpenComputers does —
which is the single detail the whole frame bug depended on. Two things fall out
of having it:

**`test_shell_glass.lua`** runs the real panels renderer across thirteen shell
states — tier 1 and 3, 40×12 up to 160×50, empty directories, over-long command
lines and paths, an elevated prompt, a scrolled list — and then *looks* at the
result. It asserts two properties, both of which have been broken before:
*coverage*, that a full redraw leaves no cell untouched (the file-list row that
stopped one column short read as a cursor "partly in one place and fully in the
other"); and *sufficiency*, that a partial redraw repaints everything that
changed. The measure needs no golden file — compare against what a full redraw
of the same state paints, and any difference is something the operator can see
that is no longer true.

That second property immediately found one. **Tab-completion left up to fifteen
rows of the previous command's output on screen.** The inline overlay
(`S.outLines`) is drawn *upward* from the output row, over the bottom of the
file list, so removing it means those list rows have to be repainted. The event
loop knew that and floored the draw to level 2 — but only on the path where the
browser moves. Tab-completion with an ambiguous prefix clears the overlay to
make room for its "N matches:" line and asked for level 1, which repaints four
rows and none of the ones the overlay covered. Measured at 1,119 stale cells for
a fifteen-line result. The rule now lives with the overlay rather than at each
site that clears it: whenever it was showing and is now gone, the draw is
floored, whoever cleared it and for whatever reason.

The fixture also carries a **`unicode` module**, and that matters more than it
sounds. `kernel.ustr` probes for OC's `unicode` and falls back to *byte* math
when it is absent — which is every off-box run. So off-box,
`ustr.width("F2 ▸ tiles")` answers 12 instead of 10, and every column
calculation touching a box-drawing glyph is over by the continuation bytes.
The first version of this test duly reported the path rail as two columns short;
it is not, in-world. It cuts both ways, and that is the real cost: until now a
genuine column-math bug in translated or glyph-bearing text was equally
invisible to the suite.

### Nobody was listening when the screen changed size

`d.w`/`d.h` — kernel.screen's idea of how big each seat is — were written in
exactly two places: `screen.init()`, and `screen.fitDisplay` when TOS itself
sets a resolution. Both are cases where TOS is the one doing the resizing.

OpenComputers resizes the glass on its own as well. Add or break a screen block
in-world and the GPU resolution is clamped to the new maximum, and OC announces
it with a `screen_resized` signal — which appeared nowhere in the TOS tree.

Everything downstream then describes a screen that is not there. The seat
proxy's `syncSize` compares against `d.w`/`d.h`, so with both stale it sees no
change and keeps a shadow indexed for the old width, eliding repaints of cells
that are no longer where it thinks they are. Worse, the panels layout counts
`SUM_ROW`, `OUT_ROW`, `CMD_ROW` and `STAT_ROW` back from `S.H` — so on a screen
that *shrank*, the status bar and the prompt are drawn past the bottom edge,
where the GPU clips them. That is a third way for the status bar to disappear,
and this one takes the command line with it.

OpenOS treats this as load-bearing: `lib/tty.lua` listens for the signal *and*
intercepts `gpu.setResolution`, with the comment "the gpu can change resolution
before we get a chance to call events and handle screen_resized".

`screen.onResized(addr, w, h)` re-reads the resolution from the GPU (preferring
its answer over the signal's numbers — the signal reports the *screen's* new
size, and the resolution is a separate thing OC may have clamped elsewhere),
and invalidates the seat caches when it actually moved. It is a plain function
rather than a listener registered inside `kernel/screen.lua`, because that
module deliberately requires only `component` and `computer`; the kernel wires
the signal to it at boot, and the shell relayouts off the same signal.
(`test_screen_resize.lua`)

### The black status bar and the second cursor were the same bug

Two symptoms the operator had reported separately, and neither was where it
looked. The status bar going black had already been chased and fixed four
times — `display.scrollUp` leaving the glass black, compat's `term.gpu()`
handing out the raw GPU, a `restoreRow` helper inside the self-test written to
*detect* this, `withContext` restoring a colour cache across the same GPU — and
it kept coming back, because every one of those was a way for the caches to go
wrong, and this is a way for them to be *right about the wrong surface*.

**A seat proxy keeps two things.** A dirty-cell shadow that says "this cell
already reads like that, skip the repaint" — and it describes *the glass*. And,
on an OC 1.7.5+ GPU with video RAM, an off-screen *page*: `drawMod.all` opens a
frame, every draw lands on the page, and one `bitblt` puts the finished picture
up without tearing.

Those are the same surface only for as long as nothing has been drawn since the
last blit. **In TOS, most drawing is not inside a frame.** `drawMod.all` is the
only thing that opens one. Every `applyDraw` level 1 and 2 — which is every
keystroke on the command line — the once-a-second status-bar tick, the
file-list fast path and every dialog paint straight to the glass.

So the elision inverts. The frame's redraw skips exactly those cells whose
*glass* content already matches, which means they are never written to the
*page*, and then the closing blit paints the page's stale version over them. On
a page that was just allocated, the page's version is blank black. `beginFrame`
said so in as many words — "the page holds the PREVIOUS frame's pixels, which
is exactly what the shadow says the screen holds" — and that was an assumption,
not an invariant, wrong once because OpenComputers hands back a *blank* page
from `allocateBuffer`, and wrong again for every cell painted between frames.

That is both bugs:

- **The status bar** is the most exposed thing on the screen, because it is the
  one element repainted on a *timer*, outside any frame. By the time a frame
  opens it is always "already correct", so it is always elided, so the blit
  always reverts it — to background black. And it never heals, because the
  shadow goes on insisting the row is painted, so the 1 Hz repaint that would
  fix it is skipped as redundant, every second, forever.
- **The cursor** duplicates because the page still holds the inverse-video
  block from where the cursor *used to be* when the last frame closed, while
  the live one is drawn where it is now. The stale one never moves again — an
  inert cursor, exactly as described.

The fix is one line of intent: **seed the page from the glass before drawing
into it**, so the invariant `beginFrame` assumed is one it establishes. It
costs a single `bitblt`, and only when something has actually drawn outside a
frame — `claimGlass`, the chokepoint every `set`/`fill`/`clear` already goes
through, sets the flag, so a drawing method added later cannot forget to. Set
against the forty-odd `gpu.set` calls a full redraw makes, it is not a cost
worth optimising away.

Worth noting what did *not* find this. The existing backbuffer tests pass
against the broken code, because they count `bitblt` calls: the blit happened,
in the right order, the right number of times. It was simply blitting the wrong
pixels, and a call-count mock has nothing to say about pixels. The new
`test_screen_frame.lua` models a GPU with **real pages** — `allocateBuffer`
returns a blank one, `set`/`fill` write into whichever page is active, `bitblt`
copies — and then reads the glass back and counts the cursors on the row. It
fails on the unfixed build with `expected 0x0000AA, got 0x000000` and
`expected 1 cursor, got 2`, which is the operator's bug report in two
assertions. `test_screen_shadow.lua` gained the matching call-pattern
assertions, including that an unchanged page is *not* re-seeded.

### Nine bugs that read perfectly and did nothing

A pass through the tree looking for defects rather than features. What it
turned up was not a scattering of unrelated mistakes: seven of the nine share
one shape, and it is a shape that survives review.

**A name that is nil at run time looks exactly like one that isn't.** Lua
resolves an undeclared name against `_ENV`, so a missing `local` — or a name
that is a *parameter of one function* used inside *another* — compiles, reads
correctly, and evaluates to nil. Three lived here:

- **`sudo <cmd>` crashed while reporting a crash.** `sudoRunElevated` wraps the
  elevated command in a `pcall` so a command that throws can never leave a
  shell sitting at root — the restore runs on every path, then the error is
  printed. The printing half had never worked: `o`, the output function, is a
  parameter of each *command body*, and the helper never took it, so the one
  line that tells an operator what went wrong was itself an "attempt to call a
  nil value".
- **The out-of-memory message never said how much memory was free.**
  `panels/commands.lua` guarded the figure behind `if computer and ...`, in a
  file that requires nothing at all. The guard was always false, so the one
  number that tells you how much you need to free was silently absent from
  every OOM message.
- **Three kernel module inits were handed `serialize = serialize`** with no
  such local in `kernel/init.lua`. Harmless, because `profile`, `i18n` and
  `net.aliases` each fall back to requiring it themselves — but the dependency
  wiring was stating something untrue.

Note how the last two failed: a guard and a fallback each turned "this name is
nil" into "this feature is quietly absent". Nothing errored, nothing logged,
and there was nothing to notice. That is why
**`usr/lib/tests/test_global_leaks.lua`** now exists. Nothing in the source can
distinguish the two cases, so the lint asks `luac` what each chunk actually
reaches for through `_ENV`, across every file `/tos/system_manifest.lua`
declares, and demands a stated reason for each exception (the boot files really
do run under the OC BIOS environment; `net/remote.lua` really does want
`table.unpack or unpack`). It carries a self-check so it cannot pass by having
stopped working.

**The OpenOS compatibility tables were being built by undefined behaviour.**
`sides`, `colors` and `keyboard.keys` are all two-way — a name maps to a
number and the number maps back — and all three built the reverse half by
adding keys to the table *while walking it with `pairs`*. Lua's manual is
explicit that you may clear or modify existing fields during a traversal but
not add new ones, and this did not stay theoretical: the rehash triggered by
the first insert made `next` skip entries, so a random subset of the reverse
map was never written. Measured on the shipped files, `colors` lost anywhere
from 0 to 13 of its 16 entries and `keyboard` kept only 32 to 75 of ~99 — **a
different set on every boot**, because Lua seeds string hashing per process.
`sides` was worse again: every face there has two names, so even a walk that
happened to finish picked the winner by hash order, and `sides[0]` came back
`"bottom"` one boot and `"down"` the next. OpenOS's own `lib/colors.lua`
snapshots the keys into a second array before writing, and its `lib/sides.lua`
spells the canonical reverse names out literally; TOS now does both.

**`event.listen` refused the second signal.** OpenOS identifies a listener by
the *pair* (name, callback) — `full_event.lua` matches on both in `listen` and
in `ignore`. The shim keyed its map on the callback alone, one signal deep, so
the ordinary case of one handler serving several signals broke two ways at
once: `listen("touch", f)` then `listen("drag", f)` saw `f` already present and
returned false without registering, and `ignore("touch", f)` removed whichever
single signal `f` happened to be mapped to.

**`battery` answered "nil".** `kernel.power` loads on every machine — that is
the point of it — but `statusString()` returns nil off a battery, deliberately,
so a status bar has nothing to draw. `shell/ext.lua` handed that straight to
the output function, which `tostring`s whatever it is given. On any ordinary
computer, which is most of them, the answer to `battery` was the word "nil".
`kernel/diag.lua` had branched on the nil all along; only the command didn't.

**A truncated archive raised instead of answering.** `compress.unpack`'s
contract is `(data)` or `(nil, err)`, and `decompress` calls it unprotected and
prints the error. `isPacked` accepts a container from 9 bytes up — enough for a
*stored* header — but a *compressed* one needs 11 before the chunk count can be
read, so a container truncated to 9 or 10 reached the `u16` read with nothing
there and threw a bitwise-operation-on-nil out of a function that is supposed
to hand back a message. Every longer truncation was already caught inside the
chunk loop; only the header itself went unchecked.

Two more in the add-ons: **Tetris ignored `^Q`**, because the game loop
destructured the key *char* into a discarded `_` and then passed a nil global
to its quit check — leaving only the F10 and Esc scancodes working, and leaving
an operator who rebound quit to another `^`key with no exit at all. And
**`rbmk-controld`'s `_lastLevel` was a leaked global**, the one piece of
reactor state that escaped the module, and the piece the
warn-once-per-transition rule depends on.

Every one of the nine has a regression test that was run against the broken
code first and watched to fail: `test_sudo_report.lua`,
`test_compat_tables.lua`, `test_compat_event.lua`, `test_ext_battery.lua`,
`test_global_leaks.lua`, plus new sections in `test_compress.lua`,
`test_tetris_sandbox.lua` and `test_rbmk.lua`. The compat-table test carries a
source lint as well as value assertions, because the values alone would have
passed on a lucky boot.

Two findings are recorded in `TODO.txt` rather than fixed. `gmatch`'s
empty-match rule differs between the Lua 5.3 and 5.4 architectures TOS
supports, which would make ~15 line-splitting call sites emit a stray blank
line on a 5.3 CPU — but only 5.4 is installed on the dev box and 5.4 masks the
behaviour completely, so there is no way to see the bug or prove a fix from
here, and fifteen edits on a recollection is not a fix. The other is a
mutation-during-iteration in `kernel/event.lua`'s timer loop that looked
survivable in every case traced by hand — which is exactly what the `pairs`
bug above also looked like, so it is written down instead of waved off.

### Select text and copy it — and one clipboard for everything that holds text

TOS could not copy a line of a command's output. It could not select anything.
The editor had a private clipboard of whole LINES that nothing else could
reach, and the command line had none at all — which mattered more the moment
the prompt became resident on every Home surface.

**Shift and the arrows select.** At the prompt, in the editor, and a line at a
time in a view buffer, which is where a command's output lands. With the
optional mouse driver, click and drag does the same. An unshifted arrow always
drops the selection, in all three places, so a selection can never outlive what
the operator can see. Typing, Backspace and Delete replace it, the way every
editor has behaved for thirty years.

**Copy is `Ctrl+Insert` and it had to be.** `kernel/init.lua` consumes char 3
to interrupt the foreground process and then blanks the signal, so `^C` never
reaches a program at all — which means the editor's `Ctrl+C = copy line`, help
text and all, had never fired once since the day it was written. It is deleted
rather than fixed. DOS and Norton Commander put copy on `Ctrl+Insert` for
exactly this reason a decade before `^C`/`^X`/`^V` existed, and TOS looks like
Norton Commander on purpose. `^X` and `^V` are free and work as second
bindings; `keys set copy ^C` is refused with the reason, which `keys.isReserved`
could already say and now gets asked.

**All three are `keys.lua` actions**, so they layer through `/etc/keys.cfg` and
`~/.keys.cfg` like everything else, and every help screen that names them —
`keyhelp`, `help`, the editor's own help topic — reads the live binding instead
of spelling a key. That is how the `Ctrl+C` line managed to lie for a year.

Supporting that meant teaching `keys.lua` about modifiers, because
`Shift+Delete` and `Delete` are the *same scancode with no character*: OC
cannot tell them apart in a `key_down`, so a matcher now carries its modifier
requirement and `keys.is` is handed the live state. That state is tracked from
the `key_up`/`key_down` of the modifier keys themselves — and it **expires**,
which is the Esc problem wearing a different hat: hold Shift, press Esc to
close the screen GUI, release Shift somewhere else, and the `key_up` never
arrives. Without a timeout that wedges every arrow key into extending a
selection until the operator logs back in.

**`kernel/clipboard.lua` is the store**, and it is deliberately small:

- **One clipboard.** Copy in the editor, paste at the prompt. Copy a run of
  `pkg list` output, paste it into a file.
- **Per seat.** A multi-seat rig is several people at several screens, and one
  global clipboard would let them read each other's copies by accident.
- **Cleared at logout**, because a seat is a physical screen the next person
  walks up to and what was copied is sometimes a password on its way to a
  prompt. The `cli` handoff is not a logout and keeps it.
- **Not reachable from sandboxed package code.** `shell.keys` is allowlisted
  because a keybind table carries no authority; a clipboard carries whatever
  was last copied, and a background package that could poll it would be a
  keylogger with extra steps.
- **Bounded** at 512 lines / 16 KB, and it says when the cap bit rather than
  quietly holding less than was copied.

Pasting multi-line text into the one-line prompt joins it with **spaces** and
says so. The old OC-clipboard handler stripped newlines instead, which glued
two lines reading `ls` and `cd /` into `lscd /` — a command nobody typed and
one they might well have run.

Two smaller things fell out of it. With nothing selected, copy and cut still
take the whole line, so the editor's old muscle memory survives the change.
And at the prompt with nothing selected *and* nothing typed, copy takes the
path of the file under the cursor — the short answer to "how do I get this path
onto the command line", and the only thing that key could plausibly have meant
there.

`F5`/`F6` in the file list remain a separate FILE clipboard. Two verbs sharing
an English word; the help text now says which is which, because one "paste"
that means two things depending on invisible state is worse than two names.

### One home, two views — F2 stops switching tabs and starts switching views

The Desktop and the Shell were two tabs, and F2 cycled between them. That made
the most basic question about this machine — *where is my prompt?* — have two
answers, and gave F2 a meaning that depended on which tabs happened to be open.
Both are now two **views** of one tab called **Home**, and F2 flips the view.

Grounded in a drawn mockup of every screen (composed from the real draw code,
not from screenshots) rather than described in prose, which is how several of
the details below got settled before any of it was written.

**The bottom four rows never move.** Summary rail, output row, command prompt,
status bar: identical in both views, at the rows `recomputeLayout` has always
put them. Press F2 and only the middle of the screen changes. That is the whole
argument for merging rather than re-skinning — the prompt is never somewhere
else, and a command's short result lands inline above the summary rail exactly
where the last one did, without the tiles moving under your hand. Tiles get
rows 4–21 (three rows of five, 15 to a page on an 80×25 screen); files get the
same 19 rows the browser had.

**F2 is the `view` action in `shell/keys.lua`, not a panels scancode.** That
file landed one commit earlier with five actions and the argument that a
shortcut you have to remember per program is not a shortcut, it is trivia;
`view` is the sixth. It inherits `/etc/keys.cfg` and `~/.keys.cfg` layering, so
it is operator-rebindable from day one, and every legend that names it —
the rail's `┤ F2 ▸ tiles ├`, the F-key row, the tile hint, `keyhelp`, the `help`
screens, the background-task message — asks `keys.label("view")` instead of
spelling F2. Rebind it and the screen re-labels itself.

**Everything printable belongs to the prompt**, which is what a CLI-first
machine owes you, and it is what moved two other bindings:

- **Quick-launch is `Alt+1-9`.** A bare `1` types a `1`. OC sends a bare digit
  with both its character and its scancode and suppresses the character when a
  modifier is held, which is the whole discriminator.
- **History is `^P` / `^N`.** It used to be Up/Down *while the line was not
  empty* — one key meaning two things, with invisible state deciding which.
  The arrows now drive the selection in whichever view is up, always. There is
  no focus mode to learn because the prompt never competes for them.
- **Tab moves between tabs when the line is empty**, and completes when there
  is something to complete. F2 had that job and the merge took it; the split is
  unambiguous because completion needs a word to work on.

**Pagination, made visible.** `ui.tileGrid` always computed `perPage` and
nothing ever said so, which meant a tile on page 2 existed with nothing on
screen admitting it. A band rail above the grid now reads
`‹ page 1/2 › · 27 tiles · 15 shown · PgDn next page`; PgUp/PgDn page, and with
the mouse add-on the `‹ ›` markers are click targets, as is the F2 legend
itself. The T1 numbered list pages the same way.

**No Files tile.** F2 is the way to the file list and the legend two rows under
the grid says so; a tile restating a visible key is a tile slot spent on
nothing. The split-mode Desktop keeps its Files tile, because there it really
is how you get back.

**The file keys are only live over files.** F3, F5, F6, F7 and F8 act on the
file list, so they do nothing in the tiles view. Leaving F8 armed over a tile
grid would let an operator delete a file they cannot see.

**`landing` picks a view, not a surface.** The per-user profile field kept its
stored values (`desktop` == `tiles`, `shell` == `files`) so nothing needs
migrating, and now accepts the new spellings too. Unset, root lands on files
and everyone else on tiles. Settings → Desktop is Settings → Home.

**The escape hatch is a boot setting, not a fork.** Boot Settings → Interface
gains `split` beside `home` and `cli`: two tabs, F2 cycling, exactly as before.
It exists because a rearrangement this large should not be a one-way door, and
`test_home_view.lua` pins both shapes so neither can rot unnoticed.

**Also fixed: two white-on-white collisions on T1.** Found while composing the
mockup against the real theme tables rather than in use. `display.lua`'s T1
block sets `dim = 0xFFFFFF` while `menubar_bg` and `statusbar_bg` are also
white, so every inactive menu label and both `▓▒░` ramp caps were drawn white
on white and simply vanished. The draw sites now fall back to the bar's own
foreground whenever `dim` collides with the bar's background — theme-general,
so a future preset that picks the same two colours cannot bring it back.

### `tape decrypt` could not read what `tape encrypt` had just written — tape 2.2.1

Two defects in the `tape` module's vault path, found while mapping the tree.
Patch bump: no manifest, command or capability surface changed.

**The round trip was broken.** `kernel.vault` writes `TVAULT2` for every new
blob and still reads `TVAULT1` (#SEC CR-7). The tape module's format sniffer
only matched `TVAULT1`, so `tape encrypt` produced a tape that `tape decrypt`
then refused with "Tape is not encrypted (no TOS vault header)." The data was
never lost — the blob on the tape was fine — but the only command meant to get
it back declined to try. The file-based `tape vault` path never had this bug,
because it asks `vault.isEncrypted()`, which accepts both versions. The sniffer
now accepts both too.

**The reads were unbounded.** `readWholeTape()` pulled `getSize()` bytes into a
single Lua string, justified in-comment by "tapes typically hold a few hundred
KB at most". A stock Computronics tape is 4 MB. This is the same pattern as the
"Tape Menu OOMs" bug that `shell/launcher.lua`'s streamed reader was written to
fix, and `modules/tape-authenticator` already carries the note that the old
whole-image read "OOM'd even tier-3.5 RAM" — the tape module simply never got
the same treatment. Both call sites now read only what they need: encrypt asks
`scanArchive()` how long the archive actually is (it already walks the entries
structurally) and reads exactly that; decrypt reads the 114-byte vault header,
takes the declared `ctLen`, and reads exactly the blob. The cartridge padding
past the data is never pulled into RAM, which also removes the old
strip-the-trailing-zeros step that existed to undo the over-read.

Because the module legitimately handles multi-MB archives, the new guard is a
*memory* budget derived from `computer.freeMemory()` rather than a fixed cap
like launcher's 64 KiB menu limit — a small constant would be wrong here. When
a read won't fit, it declines with the two figures rather than dying partway.

New `modules/tape/test_tape_vault.lua`: 12 assertions covering both wire
versions, the bounded reads (asserted by counting bytes the fake drive hands
out), a corrupt `ctLen`, and the low-memory refusal.

### One set of shortcuts, and the operator owns them

Follow-on from the Esc round. Operator: *"^Q is the close combination, the ttt
game just uses Q to exit, which can be confusing for Operators who prefer one
standard."* Fair, and worth more than it sounds — a shortcut you have to remember
*per program* isn't a shortcut, it's trivia.

New `tos/shell/keys.lua`: one table, read by the shell, its dialogs, the picker,
and every bundled package. Five actions — `quit` (^Q, F10), `help` (F1), `save`
(^S), `find` (/), `refresh` (^R). Deliberately small: a "standard" that tries to
cover every key ends up describing none of them.

**Operators set their own.** `/etc/keys.cfg` (admin, machine-wide) then
`~/.keys.cfg` layered on top, driven by `keys list | set | reset`. Keys are
written the way a person says them — `^Q`, `Ctrl+S`, `F10`, `/` — because a
config nobody can read back is a config nobody will edit, which is how
"adjustable" becomes theoretical. A rebind **replaces** rather than adds, so
`keys set quit F4` can mean *only* F4.

`^B`, `^T` and `^C` are refused with a reason: the kernel consumes them before
any program sees them, so accepting a rebind would write a setting that silently
does nothing.

Packages reach it through `kernel.sandbox`'s allowlist. That widening is
deliberate — a keybind table only the base image could read would standardise
nothing — and safe: the module reads two config files and returns key matchers,
with no authority passing through it. Converted: `write`, `ttt`, `snake`,
`stock`, `tetris`, `calc`, `rc-pilot`, each degrading to its coded defaults if
the module is absent.

Plain **Q** still quits `ttt` and `snake`. Taking away muscle memory buys
nothing; what changed is which key they *advertise*, and their footers now read
the live binding rather than a baked string — so a footer can't name a key that
was rebound away. `test_keys.lua` pins the second half specifically, because it's
the one that rots quietly: a hard-coded scancode keeps working, and nothing fails
until an operator changes a key and finds one program ignoring them.

### Esc is Minecraft's key, not ours

Reported from real Minecraft: programs using **Esc** to exit are unexitable. Esc
belongs to the game — it closes the screen GUI, so the player steps away from the
terminal and the keypress never reaches the computer. The program is still
running when you open the screen again.

`write` shipped exactly that way: Esc was its only exit, and its footer
advertised it, so even the workaround was hidden. That's a bug I introduced two
rounds ago and no off-box test could have caught, because a test can't press a
key the game intercepts.

The convention is now written down in `tos/shell/panels/keymap.lua`, where
someone binding a quit key will read it on the way past:

| To do this | Press |
|---|---|
| Quit a full-screen program | **Q**, or **^Q** where Q would be typed |
| Cancel a prompt or dialog | **^Q** |
| Quit, anywhere | **F10** |

Esc is still *accepted* wherever it's harmless, in case a future OC build or an
emulator delivers it — but nothing requires it and no help text advertises it.
Swept across the tree: `write` (F10/^Q, and its interrupt path no longer
synthesises an Esc nothing would act on), `rc-pilot` (where plain Q is *turn
left*, so it had to be ^Q), the framed dialogs, the package picker's filter and
quit, the CLI's masked passphrase prompt, `stock`/`snake`/`ttt` (one line each —
their shared `keyName` helper now maps ^Q and F10 to the same "esc" every call
site already tested for), and the mouse demo.

`test_no_esc_exit.lua` pins both halves: no file may offer Esc as its only exit,
and no help text may tell an operator to press it.

### The menu bar is the operator's, not the code's

Also reported: the bar "hasn't been updated and should be Operator-adjustable,
not static as it currently is (or at least, looks)". Both halves were fair.

**Adjustable.** There was a per-user `~/.menu.cfg`, but it could only *append* —
no removing, renaming, reordering or replacing, and nothing machine-wide. Now
there are two layered configs (`/etc/menu.cfg`, admin, then `~/.menu.cfg`) and
the full verb set: `menu show | add | hide | rename | move | list | remove |
reset`, with `--system` on any of them to change the bar for everyone.

It's an **edit list, not a replacement bar**, and that's the important choice: a
saved copy of the whole bar goes stale the moment TOS gains a command — which is
precisely how the built-in set got a year out of date. Edits ride on top of
whatever the built-ins become.

A malformed config never costs you the bar. Bad entries are skipped individually,
and an edit list that removes *everything* falls back to the built-ins — the menu
bar is the surface you'd use to fix a broken menu bar, so it doesn't get to
break.

**Updated.** Tools gained Packages, Repair (SRM) and Diagnostics; System gained
CLI Mode; Settings gained Menu Bar, so the bar can be edited from the bar — an
adjustable thing whose adjustment is undiscoverable is still, to the operator,
static.

### Six bugs from the first real-Minecraft round

Not the emulator — actual OpenComputers, with actual hardware attached. Six bugs
in one sitting, none of which 141 off-box tests could see.

**The pattern is worth more than any single fix.** Not one of these was a hard
fault. Every one was a place where the code *guessed* at something it could have
*determined*, or kept a second copy of a fact that already existed correctly
somewhere else. Off-box tests can't find that class, because a mock encodes the
same assumption the code does. Real hardware just does what it does.

**The Optional Utilities picker never saw the second floppy.** Split the set as
intended, insert disk 1, and the picker listed only what was in the drive — no
dimmed off-disk entries, no swap prompt, and no way to tell that wasn't the whole
catalogue.

`pkgpicker` enumerated mounts by *listing the mount directory*. Boot-time mounts
are virtual — `kernel/init.lua` calls `fs.mount()` without creating a directory —
so the listing came back empty, the set manifest was never found, and everything
downstream of it (off-disk entries, "Insert disk N", the undo flow) was dead
code.

The galling part: `pkg.lua` already knew. Its own `mountedRepoRoots` carries the
comment *"boot-time mounts are virtual and don't appear in fs.list"* and consults
the mount table first. The knowledge was written down, in this repository, next
to the correct code — and the picker had a second copy of the enumeration that
didn't have it. There is one now, exported as `pkg.repoRoots()`.

`test_installer.lua` didn't catch it because its filesystem mock returned the
disk from a `/mnt` listing — it mocked a filesystem that doesn't behave like the
real one. The mock now reproduces the virtual mount, and `test_pkg_repo_roots.lua`
asserts the rule directly; its *first* assertion is that listing `/mnt` finds
nothing, which is the precondition the old code assumed away.

**"RAM 4K" on a machine with megabytes**, three lines above `Free memory:
1300KB` in the same boot log. `hal.ramSticks` decided whether `getDeviceInfo`'s
capacity was bytes or kilobytes with `if cap >= 4096 then cap = cap / 1024`, and a
capacity arriving as exactly 4096 lands on the wrong side of that. The
determination was available all along — the sticks have to add up to
`computer.totalMemory()`. Both readings are now tried and whichever reconciles
wins; a set that reconciles with neither returns nothing rather than a number we
can't justify, and the summary falls back to the machine's real total.

**Peripheral capabilities never reached package code.** `printer` reported
"peripheral.printer cap required" on a machine whose kernel log had recorded
`[hotplug] Added: openprinter` seconds earlier, with a manifest that plainly
declared the cap.

A manifest's capabilities reached the *sandbox*, where they filter
`component.proxy`, and stopped there. The kernel's peripheral modules gate on
`kernel.process.current().caps` — a **different** set, belonging to the running
process. A package command runs inside the shell's process, whose caps are a
fixed list in `kernel/init.lua` that contained no peripheral entry at all. The
gate could never open.

Once traced, the scope was wider than the printer: `stock` could never have read
a chest, and `redstone` / `robot` / `inventory` typed at a shell could never have
worked either. All three were marked `[?]` — code done, never run against real
hardware. That mark earned its keep.

The fix has two halves and the second one matters. `kernel.pkg` now wraps every
package command in a **cap scope**: the process wears the manifest's caps for
exactly the duration of the call, and its own again afterwards — restored on
error too. And `shellCaps` gained the peripheral entries so first-party
`redstone`/`robot`/`inventory` work, which is safe precisely *because* of the
scope: package code never sees the shell's set, since the scope replaces it
wholesale and a package gets strictly less than the shell for anything it did not
declare.

Why no test caught it: every off-box test **stubs the sandbox**, so the sandbox's
cap set was the only one they had ever looked at. `test_pkg_capscope.lua` looks at
the *process*, and asserts both directions — the declared cap arrives, the
shell's undeclared ones do not, and a crashing command still gives the caps back.

**A command that would not load read as "Unknown command".** At 56 KB free,
`reboot` — a perfectly real core command — could not be loaded, so the dispatcher
returned nil and the executor called it unknown. The operator was told their OS
has no `reboot`. `commands.lua` had already put the real reason in `S.lastOut`;
the executor then overwrote it. It now asks the registry whether the name is real
before blaming it, and prints the load failure instead.

This is the exact failure the CLI round predicted in its own emulator checklist —
predicted, written down, and shipped anyway, because nothing tested it.

**A read-only boot disk, discovered at the password prompt.** First Boot Setup
failed with `Persist failed: read-only filesystem`. Nothing anywhere checked
`isReadOnly`, and TOS writes `/etc/users.dat` before an operator has finished
typing their first password — so the first symptom of a read-only root was a
failure in the middle of setup that named neither the disk nor the actual cause.
Now: checked at boot and announced once with the disk address; the boot-device
scans prefer a writable filesystem and fall back to any; `df` and `doctor` report
it; and First Boot Setup names the remedy instead of looping a prompt forever on
an error that retrying cannot fix.

**Dialog text clipped at the screen edge, not the box edge.** That error ran out
through the First Boot box's border and was cut at "cannot open for wr", losing
the half that said what to do. Messages now wrap to the box's inner width.

### The CLI is now as capable as the TUI — and cheaper to start

TOS had two shells with two command tables. The panels TUI dispatched through a
registry of **124** commands; the CLI in `shell/init.lua` was ~1,150 lines of
separately hand-written verbs and had **85**. So 45 things you could do in the
full interface simply did not exist at the prompt — `srm`, `sudo`, `watch`,
`which`, `why`, `theme`, `net`, `notify`, `crash`, `tail`, and the rest.

The gap was the symptom. The cause was the second command table, and closing the
gap by hand-writing 45 more entries would have re-armed it from the next commit
onward. So the CLI now dispatches through **the same registry**, in a new
`shell/cli.lua`; `shell/init.lua` shrank from 1,280 lines to a ~120-line launcher
that picks an interface and lets the two hand off to each other.

Everything that came with the registry came along with it: pipes, redirects,
quote-aware tokenisation, tier gates, `sudo`, and commands provided by installed
packages. None of those were CLI features anyone had to write — they were
*executor* features the CLI could not reach.

**The laziness is not a consolation prize, it is the other half of the point.**
The registry loads its category files on first touch, so a session that only
types `ls` and `cat` never parses the admin or extras command files. The CLI is
what a seat falls back to when the TUI won't load and what `ui=cli` boots into —
paying for the whole registry up front is exactly what it must not do. It came
out both fully capable *and* lighter to start than the copy it replaced.

**Reaching it**, since one way was not enough:

- `cli` from any prompt, `tui` to come back. Both are tier 0 — which interface
  you use is not a privilege, and the CLI is specifically what you want available
  when the full one is misbehaving.
- The quit menu's fourth entry, relabelled from `[4] Shell` to `[4] CLI Mode`.
  "Shell" said nothing: all four of those choices leave the shell you are in.
  It is drawn from two files (`^Q` in events.lua, the menu action in menus.lua)
  and a test now pins them to the same string — two spellings of the same four
  choices is how an operator learns to distrust both.
- Boot Settings → Interface → `cli`, as before.

**What the CLI still cannot do**, said plainly rather than papered over: the
tabbed viewer/editor, the Desktop, and live-refreshing tabs *are* the panels
interface rather than commands. Ask for one and it says so and names the
alternative (`watch` for live refresh, `tui` then `edit` for the editor). Those
are UI facts, not missing commands.

Two supporting changes worth knowing about:

- `makeProgramEnv` moved out of `panels/init.lua` into `shell/progenv.lua`. Both
  shells hand it to every program they run, and a second sandbox-environment
  builder is the last thing this codebase should have — it is a security surface,
  and two copies drift.
- The executor takes an optional `deps.showOutput`. The TUI routes output between
  a status row, an inline region and a view tab; a teletype has one surface. That
  also let the editor become a lazy require inside the executor, so a shell that
  never opens a tab no longer drags in the tab/editor tree.

`test_cli_parity.lua` asserts the parity **from the registry** rather than from a
list somebody has to maintain: every registered command must resolve through the
CLI's table, the CLI must supply every `deps.*` the category files reach for, and
core-only use must not load admin or extras. It also pins the layering — the
emergency terminal must keep depending on nothing the other two shells need,
because a fallback that shares its dependencies with the thing that broke is not
a fallback.

### Signed package manifests (Ed25519, RFC 8032)

The biggest real gap the package manager had. `pkg` has verified file hashes
for a long time, and hashes answer a different question than the one an
operator is actually asking: they prove the disk is not **corrupt**, never
that it is from **who it claims**, because whoever writes the files also
writes the digests. What was really holding the line was the admin gate, and
an admin gate is *per-disk* consent — the same judgement call again for every
floppy. A signature makes it *per-publisher*.

The chain is `signature → manifest → hashes → files`, and `pkg` runs both
gates: a signed manifest that declares no hashes is still unverified code,
because the signature vouches for a document that promises nothing about the
files.

**Four states, and none of them is silently another.** Three were in the
plan; the fourth is the one that matters and it wasn't named there:

- **trusted** — verified, and the key is in your store.
- **unknown** — verified, key not yet trusted. *Not* the same as unsigned:
  the bytes really are from the holder of that key, and one `pkg trust add`
  turns it into the first row.
- **unsigned** — no signature. Keeps working, because a floppy from a friend
  is the normal case and always will be. What changed is that TOS now *says*
  your admin privilege is what's authorising it, instead of leaving you to
  assume something stronger.
- **invalid** — a signature exists and does not verify. Hard refusal, **no
  override**, and specifically not degradable to "unsigned". If a broken
  signature read as an absent one, corrupting a signature would be a route
  onto the permissive path. `--force`, `--allow-unverified` and
  `--allow-unsigned` are all tested against it.

Two forgeries the design refuses by construction. A signature file may carry
a `signer` name — it is display-only, shown in quotes as the disk's own word,
and **never** matched against the trust store, so a floppy calling itself
"Strata Systems" is not trusted for saying so. And a manifest cannot declare
itself trusted: `_sigState`/`_sigKey`/`_sigLabel` are stripped from every
on-disk manifest form, the way `_srcBase` already was.

New commands: `pkg trust list|add|remove|require|key`, `pkg verify-sig <dir>`
(who signed this, *without* installing it), `pkg sign <dir>`, and signature +
integrity lines in `pkg info`. The trust store is `/etc/pkg_trust.cfg`,
admin-writable and decoded as data. `build-disk.lua --sign` signs a whole
disk — after hash injection, since the builder rewrites each manifest, and
with the passphrase taken from the environment rather than argv because argv
lands in shell history.

**The implementation notes worth keeping**, since nobody will re-derive them:

- Ed25519 needs SHA-512 and TOS had only SHA-256, so `kernel/sha512.lua` is
  new. Lua 5.3 makes it natural rather than painful — 64-bit integers that
  wrap and a logical `>>` mean the machine word *is* the algorithm's word,
  with none of sha256.lua's masking.
- The field arithmetic uses ref10's ten limbs at radix 2^25.5. The fractional
  radix is the whole trick: 255 divides evenly by 25.5, so a product spilling
  past the top limb wraps back multiplied by exactly 19. Any whole-number
  radix leaves the wrap misaligned and the fold factor grows big enough to
  overflow 64 bits.
- Multiplication is a plain double loop rather than ref10's unrolled 100-term
  expression. Same arithmetic, and the scaling rules derive in two lines — an
  unrolled expression with one transposed index is a bug that passes every
  test except the one you didn't think to write.
- `//` and not `>>` in the carry chain. Lua's right shift is *logical*, and
  these limbs are genuinely signed, so a negative limb shifted right becomes
  an enormous positive number. That single character is the easiest way to
  get an implementation that looks right and passes small tests.
- Constants (d, sqrt(−1), the base point) are computed at load rather than
  transcribed — a 78-digit decimal copied by hand is a class of bug avoided
  outright, at about a tenth of one verification's cost.
- Pinned to RFC 8032 §7.1, and not just `verify`: the **signatures must match
  byte for byte**, which is what proves the deterministic nonce derivation is
  right and what makes interop with any other Ed25519 tool a real claim
  rather than a hope.
- Measured: 0.05 s to verify and 0.02 s to sign on desktop Lua. On a real
  OpenComputers machine expect seconds, so the module is loaded lazily (a
  machine that never meets a signed package never loads it), yields
  cooperatively inside both the exponentiation ladder and the scalar
  multiplication, and callers cache the verdict rather than re-checking.
- Not constant time, said plainly in the header. Verification handles public
  data only; the adversary here is a floppy disk, not a stopwatch.
- A data card cannot accelerate any of it: its T3 ECC is a different curve
  and a different format (a manifest signed with it would verify only on
  another T3 box, the opposite of the point), and it hashes SHA-256/MD5 while
  Ed25519 needs SHA-512.

**Not done, deliberately:** no first-party publisher key exists, so the
shipped Optional Utilities disks are still unsigned. Generating a signing key
is the operator's act — a key committed to a repository is not a secret, and
a first-party key everyone holds is worse than none because it *looks* like
assurance.

Found along the way and left alone: `sha256.lua`'s `msg:byte(1, #msg)` idiom
stack-overflows past a few hundred thousand bytes. Nothing feeds it a file
today, so it is recorded rather than changed; `sha512.lua` indexes the padded
string in place instead.

### New add-ons: `printer` and `write` — TOS can put words on paper

Two packages and one small piece of base image. The driver is modelled on the
mouse driver's posture exactly: TOS has no baked-in printing, so this is the
DOS-style driver you install when the base actually has the hardware.

**`printer`** targets PC-Logix's **OpenPrinter** addon and its `openprinter`
component. (OpenComputers' own `printer3d` is a model printer and a different
device; it is untouched.) It ships two libraries, and the split is
load-bearing rather than tidiness: `/usr/lib/printerfmt.lua` is **pure** —
the character-width table transcribed from the mod, word wrapping, 20-line
pagination and ink/paper costing — so it unit-tests off-box and works on a
machine with no printer attached at all, which is how `printer preview` and
the word processor's page ruler exist. `/usr/lib/printer.lua` is the
hardware, the job builder and the capability check.

Three things it does that a thinner wrapper would not:

* **A job is built in memory, pre-flighted, then committed.** The printer's
  buffer is a real, shared, persistent thing, so writing straight into it
  means a job that fails halfway has already half-written someone else's
  page. `job:check()` compares the job's cost against the paper and ink
  actually loaded and refuses before a single sheet moves.
* **A failed commit reports how many pages already printed.** A five-page job
  that dies on page four has three pages in the output chest; reporting only
  "failed" has the operator reprint the lot.
* **Colour is opt-in per line.** OpenPrinter charges a unit of colour ink for
  every `writeln` that carries a colour argument, so a driver that defaulted
  to "black" as an explicit colour would drain a colour cartridge printing an
  all-black document. Costing counts the two cartridges separately and the
  operator sees both before confirming.

Every call is `pcall`-wrapped because the mod signals failure by *throwing*
("Please load Ink.", "To many lines.", "no empty output slot") — the driver
converts those to TOS's `nil, reason` convention and keeps the mod's own
sentence. Optional methods (`width`, `maxWidth`, `scanBook`) are
feature-detected, not version-guessed: the 1.7 builds lack some of them.

**`write`** is a word processor, and deliberately not a second text editor —
TOS has `edit`. The difference is the page: `write` knows how wide a printed
line is in pixels and how many fit on a sheet, so the rail shows which sheet
the cursor is on, how full it is, and what the whole document will cost,
live while you type. That is the one question an editor cannot answer.

The file stays **plain text**. Formatting rides on roff-style dot commands in
column one (`.title`, `.center`, `.color`, `.page`, `..` to escape a literal
dot), which keeps a document greppable, mailable, hand-editable and never
executable — the same argument `calc` makes for not building its formulas on
`load()`. A malformed directive is a warning in the status row and the line
is kept as text; a word processor that refuses to open a document over a typo
on line 40 has failed at its one job.

`write` **requires** `printer` — the only hard cross-Extras dependency in the
set, flagged in TOS-Extras/README.md. The page model lives in the driver, and
a `write` that shipped its own copy would be two definitions of "how tall is
a page" drifting apart. The printer *hardware* stays soft: composing,
pagination, the page view and saving all work with no printer in the world,
and the rail says whether the page breaks came from the attached printer's
own metrics or from the transcribed width table, because those are not
equally trustworthy and the operator should know which they are reading.

**Base image:** a new `peripheral.printer` capability gating the
`openprinter` component type. Gated rather than folded into blanket
`component` for the same reason `piston` and `robot` are: a printer actuates
the world and spends the player's paper and ink. Installing a game must not
also hand it your cartridges. `lsdev` grew a consumables column for the type,
because a printer with no paper is present, addressed and useless, and reads
identically to a working one otherwise.

One property worth stating plainly, since it is what makes the capability
real: a library under `/usr/lib` is resolved by the sandbox's user-lib path
and then loaded through the **real** `require`, so it runs with ambient
authority and the gated-component split does not cover it. The driver
therefore **re-checks `peripheral.printer` itself, on every call**, exactly
as `tos/peripheral/redstone.lua` does for `#SEC H34`. Without that, any
package holding `fs.read` could `require("printer")` and print.

### Package capabilities: overrides as data, defaults as code

`/etc/component_caps.cfg` (FEAT-5) let an operator name a modded component
type and the capability that gates it — but a *package's* declared caps were
filtered through a static allowlist in `pkg.lua`. So an operator who added
`reactor_control → peripheral.reactor` could grant that cap to a shell REPL
and never to a package: the manifest's request was dropped in silence, the
package ran with no hardware, and nothing said why. A capability you can add
to one side and not the other is a capability that does nothing.

New `/etc/pkg_caps.cfg`, admin-writable and decoded as data (never `load`ed):

```lua
{
  allow = { "peripheral.reactor" },   -- widen what a manifest MAY request
  deny  = { ["*"] = { "internet" },   -- narrow what is honoured, globally…
            someGame = { "net" } },   -- …or for one package
}
```

**There is deliberately no `grant`.** KittenOS can pre-answer a permission
prompt because it asks at first use; TOS accepts a manifest's declared set at
install time, and the manifest is the record of what the package touches.
Handing a package a facet it never declared would make `pkg info` lie about
it and defeat the consent the admin gate exists to collect. Operators can
widen what may be *requested* and narrow what is *honoured*; they cannot
request on a package's behalf. `allow` also cannot re-enable `legacy` — an
operator config must not be a route to raw `os`/`io`.

Fail-closed, and asymmetrically so: a config that will not read or decode
yields no `allow` entries *and* no `deny` entries. Losing the allow half is
safe (packages fall back to the coded default); losing the deny half is not,
so it logs at warn — an operator who wrote a veto needs to know it is not in
force. A refused capability is now logged with the facet named and the reason
given, instead of vanishing.

`component reload-caps` reloads both files, since they are two halves of one
answer, and says that packages already loaded this boot keep their old caps.

`TOS-Extras/build/test_manifests.lua` now asks `pkg.runCaps()` for the real
allowlist instead of mirroring it. The mirror had already drifted: it never
learned `internet`, granted since the internet-card round, so a correct
manifest declaring it would have failed the lint.

### The Optional Utilities packer balances the floppies

First-fit-decreasing minimises the disk *count* and is miserable to live
with: it had left disk 1 at 99.2% of a 512K floppy — 3,930 bytes spare —
while disk 2 sat half empty. In that state the next add-on of any size is a
build **error** rather than a split, and the error names a package that did
nothing wrong. The packer now runs first-fit to learn how many disks the set
needs, then re-packs into that same count with worst fit, so headroom is
spread evenly. Same disk count, `requires` groups still share a floppy,
`recommends` pairs still co-located best-effort. If balancing would ever need
more disks than first-fit did, the first-fit layout is kept — fewer floppies
beats tidier ones. Current set: 436K and 339K, from 520K and 255K.

### New add-on: `stock`, the warehouse monitor

The first package aimed at what an OpenComputers base actually *does* rather
than at TOS itself. Put a transposer or inventory controller next to your
chests: `stock` totals every item across every adjacent inventory, and warns on
anything below a threshold you set.

The correctness point, because it is the one thing a stock count can get
quietly and badly wrong: **items are aggregated by registry name plus damage,
never by the display label.** Two mods can both ship a "Copper Ingot", and any
item can be renamed on an anvil — a count keyed on the visible name merges
things that are not the same item and splits things that are. The label is
carried for display only, first-seen-wins so the reading stays stable between
refreshes. Pinned in both directions by tests.

The other case a naive implementation drops: a watched item that has fallen to
**zero** appears in no scan reading at all, so "iterate what we found" silently
stops reporting it — precisely when the monitor should be shouting. Watched
items that are absent are synthesized at zero and sorted to the top.

`stock` is the live full-screen monitor (R rescan, / filter, L low-only, W set
a threshold, U clear it); `stock low` answers the different question "what do I
need to go make?", sorted by worst shortfall; `stock list` and `stock sides`
are one-shot listings for scripts and for checking your wiring. Thresholds live
in `/etc/stock-watch.cfg` as plain tab-separated lines — hand-editable, never
executable, and keys containing a separator are refused rather than written
somewhere they would forge extra records on the way back in.

Aggregation, thresholds and formatting are pure (`stock/stock.lua`) and carry
53 off-box assertions; `init.lua` is only scanning, drawing and input.

**`peripheral.inventory` gained `stacks(side)` and `sides()`** in the base
image to support it. `list()` collapses `label` and `name` into one field,
which is fine for "show me this chest" and wrong for anything that aggregates,
so `stacks()` returns full detail with a stable identity key. It also uses
`getAllStacks` where the component offers it — one call per side instead of one
per slot, which for a double chest is 54 component calls saved per side and the
difference between a scan you can run live and one you cannot.

### TOS can reach the internet, and `pkg` can fetch from it

TOS had no internet-card support of any kind — not in the sandbox, not in
sysinfo, not in the compat layer, nowhere. OPPM's whole premise is downloading
from GitHub, so "OPPM support" had meant reading an OPPM-shaped manifest off a
floppy somebody carried over. This is the missing half.

**`kernel.internet`** is the transport, and the one place the bounds live.
`get(url)` reads into a string (64 KB default cap — the result is RAM, and a
Tier 1 machine has 192 KB of it *in total*); `download(url, path)` streams
straight to a file a chunk at a time, via a `.part` rename so a truncated
transfer never leaves a file that looks complete. Only `http`/`https`; URLs
carrying credentials, control characters or no host are refused. Reads yield
cooperatively, so a slow server slows the seat that asked rather than the
machine. `internet` (the command) reports card status, because "it doesn't
work" has three unrelated causes — no card, the **server** has HTTP off for
internet cards, or an admin here ran `internet off` — and an operator who
cannot tell them apart debugs the wrong one. `hw` and the POST screen show the
card with what the server actually permits.

**A new `internet` capability** gates it. It is deliberately not folded into
the generic `component` grant: outbound access is an exfiltration channel for
anything a program can read, and installing a game should not hand it the
network. The capability is the boundary; the byte caps are there so honest code
cannot accidentally OOM a small machine on somebody's web page.

**`compat/internet.lua`** completes `require("internet")` for OpenOS programs,
including the parts of the contract that are awkward (`request` errors rather
than returning `nil, err`, because that is what OpenOS does and porting a
program should not mean rewriting its error handling).

**`pkg` fetches from remote repos** — `pkg repo add/list/remove`, `pkg remote`,
`pkg fetch <name>`:

- **The configured repo list is the allowlist.** No default repo, no discovery,
  and an index cannot introduce another host — a fetch that would leave the
  configured origin is refused. Adding a repo is admin-gated, because it is a
  standing decision about where this machine accepts executable code from.
- **A fetch is a download followed by an ordinary install.** `kernel.pkgremote`
  downloads into a staging tree shaped exactly like a repo on a floppy, and
  then the *existing* `pkg.install` runs against it. Hash verification, the
  write-root confinement, conflict and file-ownership checks, dependency
  resolution and the unverified-package gate are not reimplemented for the
  network. The alternative — threading HTTP through `pkg.install` — would have
  meant a second, network-aware copy of the most security-sensitive loop in
  the system, free to drift from the first.
- **Paths from a stranger are not paths.** Every source path in a remote index
  is vetted before it is used to build either a URL or a staging destination:
  no traversal, no absolute paths, no scheme, no protocol-relative `//` host
  swap, no query or fragment. `validateManifest` checks this too, but that runs
  at install time — after the bytes are already on disk — so it cannot be the
  only check.
- **Bounded**: 128 KB per file, 512 KB per package, 64 files per package,
  128 KB index. Staging is cleared before and after every fetch.
- The index is **decoded as data** with a byte bound, never `load()`ed. A repo
  index is a table written by a stranger; running it as Lua would hand them the
  machine before they had shipped a package.

Most repos ship no hashes, so `pkg fetch` refuses them until the operator says
`--allow-unverified` — the same gate a hashless floppy package hits. Remote
provenance is not a reason to relax it; it is the reason it exists.

Not supported yet: OPPM's *master list* (the index-of-indexes that lets `oppm`
search every registered repo). TOS works one repo at a time, by URL.

### `tail`, `which`, and per-user aliases

Three gaps in the shell where the obvious phrasing could not be typed.

**`tail <file> [lines]`** — `head` shipped without its other half, which meant
the natural way to follow a log, `watch tail /var/log/tos.log`, was unsayable.

**`which <name>`** — a built-in, an installed package's command, and a program
on the search path can all answer to one name, and there was no way to ask
which one wins. `which` reports all three in dispatch order and marks the
losers as shadowed. It answers by calling the executor's own resolver rather
than describing it, so it cannot drift into documenting a different shell, and
it uses a new side-effect-free `pkg.ownerOfCommand` rather than `getCommand` —
resolving a name must not load and run the package that provides it. It is the
sibling of `why`: one says what will run, the other why you were refused.

**`alias` / `unalias`** — per-user command shorthand, stored in your profile.
Aliases take effect on the next command rather than the next login, and carry
no privilege: the expansion is dispatched through the same tier gates as a
typed command. Expansion chains through other aliases but each name expands at
most once, so the near-universal `alias ls "ls -a"` reaches the real `ls`
instead of looping until the seat hangs. The sanitizer restricts alias names to
the character class a command name can have, so a stored alias can never carry
punctuation or a second command into the position where a command name is read.

### #SEC — a PATH entry of exactly `/tmp` bypassed the search-path confinement

Found while moving the resolver out of `executor.lua` so `which` could share
it. #SEC H9 confines unqualified command names to system bin directories, with
PATH honoured only where the entry is not under `/mnt`, `/tmp`, `/public`,
`/home` or `/root`. The check compared the PATH entry against that list raw,
but the list is written with trailing slashes — so `/tmp/x` was correctly
refused while a bare `/tmp` matched nothing and was treated as safe. With
`PATH=/tmp` set, a planted `/tmp/<name>.lua` would run for any name that is
not a built-in and not in a system bin dir. The bare root is the shape a PATH
is actually written with, which is why it survived. Entries are now normalized
before comparison, and the resolver's rules are pinned by tests.

### `pkg` reads real OPPM repo indexes (`programs.cfg`)

The manifest reader's own header had described `programs.cfg` since FEAT-7 and
nothing ever read it, so a genuine OPPM repo checkout reported "no manifest
here". It is now the fourth recognized form, looked for in the parent of the
package directory — where a real repo keeps it — so a checkout installs with no
rearranging. A package that ships its own manifest still wins; the index is the
fallback.

Two things in that format needed translating rather than copying:

- **`files` is keyed the other way round.** OPPM's key is the source path
  relative to the repo root and its value is the destination *directory*, with
  the installed filename coming from the source's basename. TOS manifests use
  one absolute path for both roles, and the old translator pushed the value
  into the files array — producing `files = {"/bin"}`, a directory in the slot
  where a file path belongs, which `validateManifest` then rejected as outside
  the write roots. Nothing shaped like a real OPPM manifest could install.
  Manifests grew an optional `fileMap` (target → source) to express the
  difference; native packages are unaffected and still resolve exactly as
  before. A destination outside `/usr` or `/var/pkg` is still refused — that is
  the write confinement working, not a translation failure.
- **`dependencies` values are install paths, not version constraints.**
  `{ libGUI = "/" }` means "also install libGUI". The old translator recorded
  `/` as a version constraint, so `pkg info` showed operators `libGUI /` as
  though a path were a version. (It never failed an install — `satisfiesConstraint`
  cannot parse `/` as a version, so the comparison returned equal and the
  implicit `==` passed. Working by accident is still worth fixing.)

OPPM's `:`-prefixed "copy this whole directory" keys are **refused**, with the
offending entry named. TOS installs a declared file list — each path validated,
hashed, and owned by exactly one package — which is what conflict detection and
clean uninstall depend on; installing such a package while silently dropping
its data files would be worse than declining it.

`fileMap` is validated like everything else a manifest can say: every entry
must name a target that `files` already declares, and sources are relative and
traversal-checked. The internal `_srcBase` that redirects where a translated
package is read from is stripped from every on-disk manifest form, so a
hand-written `package.lua` cannot point the installer's reads at an arbitrary
directory.

### Picker: whole-category selection and a filter

**G** ticks every package in the category the cursor is in, and clears them on
a second press. A half-ticked group fills up rather than emptying, so G reads
as "give me the rest of these" until there is nothing left to add — more
predictable than a stored per-group flag when you have already ticked two of
five by hand.

**/** filters as you type, matching name, description *and* category: an
operator hunting for "the spreadsheet one" will type any of the three and
shouldn't have to guess which field the author filled in. Enter keeps it, Esc
undoes it, and Esc from the list clears an active filter instead of quitting —
a filter that matched nothing leaves an empty list, and Esc is exactly what
you reach for there, so exiting the installer would be a nasty surprise. An
empty result says `Nothing matches 'zzz'` rather than showing a blank pane,
and the count rail reads `3 of 14 match 'gam'` while a filter is on, because
otherwise a filter you forgot about looks exactly like a disk with packages
missing.

**A** and **N** now act on what is *visible*. That is the interaction that
makes the two features worth having together — filter to `game`, press A,
install — and an A that also ticked the packages you had just filtered away
would defeat the point of filtering. Selections are keyed by package rather
than by row, so ticks survive every filter change: filter, tick, refilter,
tick, install the union.

### The package manager can now update, and can tell you no

An audit against "resolves dependencies, updates, resolves conflicts, and is
otherwise autonomous" found the first one solid and the other two missing
outright. Dependency resolution was already good — transitive, version-
constrained, `optional` deps, `provides` aliases, and a reverse-dependency
guard on uninstall. The rest:

**There was no update path at all.** `pkg.install` refused over an existing
package ("uninstall first") and nothing ever compared what is installed
against what a disk is offering. `compareVersion` and `satisfiesConstraint`
already existed; they were only ever used to satisfy dependency constraints,
never to notice that the floppy in the drive has something newer.

```
pkg outdated                  what has a newer version available
pkg upgrade <name> [<name>…]
pkg upgrade --all --yes
pkg upgrade <name> --dry-run
```

An upgrade is deliberately not "install over the top", and the reason is one
step in the middle: it removes the old version's files **including the ones
the new version no longer ships**. An install-over strands those forever,
owned by nothing and deleted by no future uninstall — which is exactly why the
set of files to delete is the difference between two manifests and cannot be a
flag on install. It also verifies the candidate *first* (hashes, licence,
conflicts), so a failed gate never leaves the machine with the old version
already gone, and it restores the package-enable byte and the rc `.disabled`
boot marker afterwards — two different flags that an earlier round proved easy
to confuse. Upgrading a package something else depends on is allowed
(`_internalUpgrade` bypasses the uninstall guard, which would otherwise freeze
every depended-upon package permanently); a downgrade needs `--force`.

**Nothing detected conflicts.** Now two kinds, and the second is the one that
actually bites: a declared `conflicts = { "other" }`, checked in *both*
directions because a conflict is symmetric in fact even when only one author
wrote it down — and **file ownership**, which needs no declaration at all.
Install copied its files over whatever was there, so two packages shipping the
same target silently clobbered each other and uninstalling either then deleted
files the other still needed. Both are checked before a single byte is
written; `--force` overrides, loudly.

### Third-party and OpenOS packages actually run now

OPPM manifests were already translated, and the provenance was already
computed — and then thrown away. `installed[m.name] = m` stored the raw
manifest with no record of where it came from, and a translated OPPM package
inherited no capabilities, because an OPPM manifest has none to declare. The
result: an OpenOS program installed perfectly cleanly and could not execute a
single line, because `io`, `term` and `filesystem` were not in its sandbox.

Recognising a package as foreign is therefore not a label, it is the thing
that makes it work. Provenance is now recorded on the manifest
(`origin = "openos"`), and a foreign package declaring no capabilities is
granted the compat surface — `compat.io`, `fs.read`, `fs.write`, `component` —
at install time. That is a real privilege grant, so `pkg info` states it
outright rather than leaving the operator to infer it.

Not a blank cheque: `legacy` (raw `os`/`io`) can never be requested by any
manifest, peripherals still have to be asked for, and a foreign manifest that
*does* declare capabilities keeps its own set — the default is a fallback, not
an override.

Also implemented the third manifest form, `<dirname>.cfg`, which
`loadAnyManifest`'s own header had documented as supported for a long time
without anyone writing it. A loot disk carrying one read as "no manifest
here".

61 assertions in `test_pkg_lifecycle.lua` over a fake disk: upgrade including
the dropped-file case, refusing an up-to-date upgrade and an unforced
downgrade, upgrading a depended-upon package, file-collision and both
directions of declared conflict, an upgrade not self-conflicting on its own
files, and all three foreign-manifest forms with their capability grants.

### The installer came off the floppy

It was being shipped twice, and neither copy needed to exist. The picker's
first act is `require("kernel.pkg")` — so it can only ever run on a TOS
machine, which by definition already has one. Yet it shipped as a ~40 KB file
on **every** Optional Utilities disk *and* as a ~40 KB string embedded in
`kernel/pkg.lua`, kept byte-identical by a test whose entire job was policing
the duplication.

It now lives once, at `tos/shell/pkgpicker.lua`, as an ordinary base-image
module. `pkg install` requires it like anything else. That deletes the
embedded string (**pkg.lua: 116 KB → 77 KB**), the disk copy, and
`test_picker_sync` along with the problem it existed to manage. The disks get
their 40 KB back — disk 1 went from 10 packages to 10 *plus* the ~40 KB that
was the installer.

What the disks carry instead is a **README** naming the command to run, and
the set manifest. The media detector now identifies an Optional Utilities disk
by that manifest rather than by the presence of an installer, which is both
more accurate — the manifest is what makes it a *set* rather than a loose pile
of packages — and necessary, since there's no installer on it any more.
`pkg make-disk` (the in-TOS builder) writes the same pair.

**The disk-swap prompt is a real dialog now.** It was two lines painted over
the install log; it's the DOS-style modal — framed, titled, shadowed, with
buttons — with room to name the disk *and* every package still waiting on it.
`dialogs.dialog` only reads `D`/`T`/`W`/`H` off the shell state, so the picker
drives the genuine renderer through a synthetic one built from its own draw
primitives. No second dialog implementation to drift from the first, and it
falls back to the old two-line prompt on an image without the dialogs module.

**Automation flags**, since the picker assumes a person at a keyboard and a
provisioning script hasn't got one:

```
pkg install <name> <name> ...     several at once, no picker
pkg install --all --yes           everything on inserted media and repos
pkg install <names> --dry-run     print the plan, change nothing
```

`--yes` is *required* by `--all` rather than merely accepted: `--all` installs
every package on whatever disk happens to be in the drive, and the alternative
to demanding confirmation is a script that hangs on a question nobody is there
to answer.

### The installer stopped pretending there is only one floppy

The set outgrew a single 512K disk a while ago, and everything downstream was
still written as though it hadn't. Two halves, both fixed.

**The picker now sees the whole set from one disk.** The builder writes a *set
manifest* (`optutil-set.lua`) onto **every** disk, describing every package and
which disk it lives on. The picker reads it, so with disk 1 in the drive you
see disk 2's contents too — dimmed, with the panel naming the disk to fetch,
and **selectable anyway**. Before this, a one-floppy machine showed half the
catalogue with no hint the rest existed; you had to already know what you were
missing.

Installing then does everything reachable, and asks for the rest:

```
Insert disk 2 for: tetris, ttt
Enter = continue   A = stop, keep what's installed   U = undo all
```

Enter re-probes the mounts and carries on. **A** stops and keeps what already
installed. **U** rolls the entire run back — newest first, because
`pkg.uninstall` refuses to strand a reverse dependency and honouring that
order is what makes the rollback actually complete rather than half-finish.

**The builder now keeps related packages on the same disk.** Hard `requires`
edges were already inviolable (a split group cannot install at all — kernel.pkg
resolves deps from the repo it installs from). `recommends` had no such
protection, and the packer had put `tape-authenticator` on disk 2 while the
`tape` package it recommends sat on disk 1 — an operator with one floppy got
the keycard tool and no way to manage the tapes it writes. Soft edges are now a
second tier: clusters the packer tries to place whole, falling back to
splitting them when they genuinely don't fit, and **naming every pair it had to
separate**. On the current set it separates none — `tape` + `tape-authenticator`
are together, and `mouse` ships beside all four add-ons that want it.

Two bugs found doing it. The soft clustering silently merged *nothing* at
first: `clusterOf` was keyed by the group *wrapper* while `groupOf` returns the
raw member array, so every lookup was nil and the union-find quietly did
nothing — the kind of failure that reports success. And the per-disk size
reserve didn't count the set manifest, so a disk could overflow by its size;
it's reserved up-front now, deliberately over-estimated, because guessing high
costs slack and guessing low costs a broken floppy.

`test_build_disk`'s split case used a 160K limit, which stopped fitting once
the picker grew — a limit below the largest single package is a legitimate
build *error*, not a split, so that test had started asserting the wrong thing.
It derives from a named `SPLIT_LIMIT` now, with the reasoning written down.

### The add-on installer got a second pane, and opinions

The pick-list is now the **left** column and a real detail panel fills the
**right**: description, version, category, kind, author, install state — and
two things the picker knew but never said.

**Which disk it's on.** `listAllAvailable` has always scanned every mounted
repo and recorded the source, so a two-floppy set was already fully listed;
the picker just never showed which floppy each package came from, which made
disk1-only listings look like a disk with things mysteriously missing. The
panel now has a `From` field.

**What comes along.** Ticking a package auto-selects its `requires`,
transitively and cycle-safely, marked `[+]` and counted in the "N selected"
rail — so the operator sees the true install set before pressing Enter
instead of watching three picks install five things. A requirement that isn't
on any inserted disk is called out in the panel (`not on any inserted disk:
…`), which is the common failure in a set that spans two floppies, and beats
letting the install discover it.

**A new `recommends` field**, the soft counterpart of `requires`: packages
that make this one better but aren't needed for it to work. Nothing is ever
installed behind the operator's back — `R` adds the suggestions for the
current selection, and that is the only way they get in. The panel shows both
directions, and the reverse one is the useful half: **`Wanted by`** lists
every add-on in the set that recommends the highlighted package. "mouse is
suggested" is noise; "mouse is wanted by calc, mail and ttt" is an argument.
`calc`, `ttt`, `tetris` and `mail` recommend `mouse` (all four are genuinely
clickable with the driver installed); `intercom` and `tape-authenticator`
recommend `tape`, which is how you manage the tapes they depend on the
contents of.

Installing now draws a real progress bar with a `n/total` counter rather than
a bare list. Below 60 columns the layout falls back to the previous
single-column form with the two-line footer, so a 50×16 T1 screen still works.

Both copies of the picker were re-spliced together — it ships from
`TOS-Extras/build/install.lua` *and* from `kernel/pkg.lua`'s embedded
`PICKER_SRC`, pinned byte-identical by `test_picker_sync`.

### A worker node wizard that knows what OS it's on

`cluster/openos/cluster-worker-setup.lua` sets up an OpenOS worker: domain id,
hostname, shared secret, and optional `/etc/rc.cfg` autostart.

The interesting part is the first thing it does. Worker nodes are OpenOS-native
by design, so someone running this on TOS isn't slightly off — they're on the
wrong machine. Rather than dying on a missing `require`, it probes what each
OS has that the other doesn't (`_TOS` and `kernel.pkg`/`kernel.users` and
`/tos/kernel/init.lua` vs `filesystem`/`shell`/`term` and `/lib/core/`),
reports **which OS it thinks this is, the specific evidence, and what to run
instead** — `cluster-setup`, choosing Manager. A TOS box with the OpenOS
compat layer loaded still reads as TOS because the TOS evidence outweighs; a
genuine tie reports "unknown" rather than guessing.

It also refuses a shared secret under 16 characters (it is the HMAC key, not a
password), refuses one containing spaces (it must match the Manager byte for
byte, and a stray space is invisible in a config file), and never echoes the
secret back to the screen when it tells you what to set on the Manager side.
69 assertions, with the OS probe injected so every environment is testable.

**And the test runner was silently skipping two directories.** Extras tests
were discovered under `modules/*/`, `build/` and `pane-ui/` only — so
`rbmk/test_rbmk.lua`, 72 assertions the README has been citing, has never run
in the suite. Both runners now cover `rbmk/` and `cluster/*/` too. It passes;
it just wasn't being asked.

### Setting up a cluster is one command per machine

The honest summary of the old state: there were two ways to install a cluster,
the documented one didn't work, and neither told you which package your machine
needed. Both packages were already on the ordinary Optional Utilities disk —
but the docs pointed at a bespoke `cluster-install.lua` floppy instead, and
that wizard was **unusable in the panels shell**, which is where operators are.
It drove itself with `io.read` (which resolves to `term.read`, painting
straight to the display and taking over the event loop — it would draw over the
UI) and coloured itself with ANSI escapes (TOS's display is GPU-driven and
interprets none, so they printed as literal garbage).

**`cluster-setup` replaces all of it**, and lives in the *base image* — which is
the point, because it is then present *before* either package is, and the first
question it answers is "which one does this machine need?":

```
cluster-setup            set this machine up (guided)
cluster-setup explain    describe the parts, change nothing
```

One Master (`cluster-master`, service `clusterd`), any number of Managers
(`cluster-manager`). The wizard picks the role with you, installs that package,
writes the config, starts the service, and runs pairing. Nothing is copied by
hand. It is named `cluster-setup` and not `cluster` on purpose: a registry
command shadows `/usr/bin` (see `executor.lua`), so taking that name would have
broken the Master's own CLI the moment the package was installed.

Three real faults found in the old flow and fixed in the new one:

- **The Master's address was printed truncated** (`myAddr:sub(1, 12) .. "..."`)
  *inside a command line*, so the one line an operator was meant to copy to
  every Manager read as copy-pasteable and wasn't. It now prints in full, and
  the Manager side *rejects* a shortened address with an explanation — every
  TOS listing abbreviates to 8 characters, so pasting one back is the obvious
  mistake, and a config built from one can never connect.
- **"Start at boot?" did nothing, either way.** `rc.start()` already clears the
  service's `.disabled` marker (that is how an explicit start persists), and
  the installer then wrote `/var/pkg/installed/<pkg>/state` — the *package*
  enable byte, which rc never reads. Answering "no" left it enabled at boot.
  The answer is now honoured by writing the marker rc actually consults.
- **`/etc/*.cfg` was written with a truncating write**, so a crash mid-write
  left a daemon's config unparseable on a machine whose whole job is to come
  back up unattended. Atomic now.

The wizard takes every side effect through an injected ctx — install, write,
start, pair, ask, choose — so the whole flow runs off-box against scripted
answers rather than being the one part of the cluster nobody could test.
87 assertions in `test_cluster_setup.lua`, covering both roles, a truncated
address, cancellation at each prompt, a failed install, a failed pair
round-trip, no modem, wired-only, and the both-packages-installed
misconfiguration.

`cluster-install.lua` stays as a pointer to the new command, so an operator
holding an older floppy is told where to go instead of running something
broken.

Also audited every add-on manifest against what's actually on disk — install
targets, `commands` wiring, rc.d presence, and orphaned files. All 14 clean.
One doc error fixed on the way past: the Manual listed `/etc/cluster.cfg`,
which has never existed; the real files are `/etc/cluster-master.cfg` and
`/etc/cluster-manager.cfg`.

### Any program can now be in your face

TOS has two places to put words on screen, and the difference matters. The
output area above the command line is *polite* — it waits until you look down.
A dialog box is not: the DOS-style modal, double-line frame, `╡ title ╞` tab,
drop shadow, buttons you must answer, centred over whatever you were doing.

That box already existed and was already general-purpose in its own docs. What
it wasn't was *reachable*. `dialogs.dialog` needs the shell state `S`, so only
shell code could raise one — a background service, an add-on's mesh handler, a
sandboxed package command had no way in. None of them can draw either: they run
where another process may own the screen, and painting would corrupt it.

**`kernel.notify` is the way in.** Programs post a notice; the shell that owns
the display raises the box on its next idle tick — "listener marks, tick draws",
the rule the chat tab already followed, generalised. The Intercom was the first
consumer and had grown a private queue hardcoded into the event loop; that queue
is now this facility, and the loop no longer knows the Intercom exists.

New `notify` command as the operator/scripting surface — the intrusive
counterpart to `echo`:

```
echo   "backup finished"      you'll see it when you look
notify "backup finished"      it's in your face, on every seat
```

**The rate limits are the load-bearing part.** A modal any program can raise is
a way to lock an operator out of their own computer — by accident, from a
service stuck in a retry loop, as easily as on purpose. So the facility enforces
a floor no caller can opt out of: 10s between notices from the same source, 3s
of quiet after *any* dismissal (you always get your keyboard back), 8 queued
maximum, and a 2-minute expiry so a notice raised while nobody was looking can't
ambush someone twenty minutes later. A refused post is normal and still reaches
the log — it just doesn't get to interrupt. A program's own policy (the
Intercom's severity cooldown) sits *on top* of this floor, never underneath.

Packages opt in with a `notify` capability, which injects a deliberately
narrowed `post`/`result` pair — no reading the queue (other programs' notices
are none of their business), no settling someone else's dialog, no `_reset`.
The source shown on the box is stamped **from the package name**, ignoring
whatever `from` the program supplies: the name on a dialog that just
interrupted you has to be trustworthy, and it's also the rate-limit key, so a
program that could choose it could evade its own gap by rotating it.

Multi-seat is handled by per-shell cursors over a monotonic sequence, so each
seat raises each notice exactly once rather than whichever seat ticked first
swallowing it; the first operator to answer settles it for everybody. Two bugs
caught in the drain while writing it: advancing the cursor to the queue's
high-water mark after showing *one* notice silently dropped the rest, and
nothing may be advanced at all when the quiet window suppressed a notice, or it
would never get its turn. 101 assertions in `test_notify.lua`.

### The Intercom: a facility that can say something

New add-on (`pkg install intercom`). A Computronics tape holds recorded
announcements; this makes them usable. Two channels carry the same
announcement at once — the tape plays the **voice**, and the same **words** go
over the mesh to every machine willing to hear them.

**The catalog is the whole trick.** A tape drive cannot tell you what is
recorded on it: it's audio, there's no index. So the operator says so once, in
the notation they'd write down anyway while recording it —

```
fuel-low  [0001] "Warning: Reactor fuel low." [0005]  warn
offline   [0006] "Warning: Reactor offline. Facility on backup power generation." [0010]  alert
```

— and that single line is all four things the Intercom needs: where to seek,
when to stop, what to broadcast, and how urgently to interrupt people. Leading
zeros are optional, because the padded form is how a person *writes* a cue list
and the short form is how a person *types* one. A typo is reported by line
number and skipped; one bad line must not silence an announcement system.

Positions written by hand are easy to get wrong, so `intercom test <cue>`
seeks, plays and stops — and tells nobody at all. Hear it before anyone else
does. The tape is optional throughout: `intercom say "we are out of iron"` is a
text-only announcement and needs no drive.

**Severity decides how hard it interrupts**, and the cooldown is what makes
that safe. `info notice warn alert critical`; below the receiver's popup level
an announcement lands in chat and the log, at or above it a message box appears
over whatever they were doing. But a failing reactor can announce itself every
few seconds, and a modal per announcement would make the computer unusable at
exactly the moment an operator needs to type on it — so after one popup, none
for `cooldown` seconds (default 60). Nothing is dropped by this; only the
*interruption* is suppressed. Every announcement still reaches chat and
`intercom log`.

Three details worth naming:

- **Playback never blocks the shell.** The stop at a cue's end is a `event.timer`
  sized from the cue's length, not a poll loop on `getPosition()`. Waiting for
  the recording to finish would freeze the seat of the person who just
  triggered an evacuation alarm.
- **Absolute seeking on a relative-seek device.** Computronics `seek` is
  relative and clamps at both ends, so reaching a known offset means
  rewind-then-forward. The tests drive this against a fake drive that clamps
  the same way.
- **The mesh handler never draws.** It runs in the kernel's dispatch context
  where no tab owns the screen; it queues, and the panels idle loop raises the
  message box — the same "listener marks, tick draws" rule the chat tab
  already follows.

Ships **disabled** (`service start intercom`): accepting messages that can
raise a modal on your screen is an operator decision, not a default. A machine
without it still relays announcements for its neighbours. 112 assertions in
`test_intercom.lua`, with a fake tape drive and no network.

### Chat is multi-operator

Chat could address one peer (`bravo: on my way`) or everybody. It now
addresses a **group**:

```
@ops: reactor is down
/group new ops alpha bravo
/group add ops charlie      /group rm  ops charlie      /group del ops
```

A group is a *name for a set of peers*, not a protocol — no group membership
on the wire, no group key, no server. Each member gets an ordinary directed
message, so groups work between any peers that already trust each other and
nobody has to agree on who "ops" is. The list lives in `/etc/chat-groups.cfg`.

Unreachable members are **named**, not skipped: "delivered to 2 of 4" plus who
was missed. A group that silently shrank because someone's machine was off
would let you believe a message landed when it didn't. The parser checks the
group form *before* the peer form, or `@ops:hi` would have been looked up as a
peer literally named "@ops" and failed with a message about peers.

### SRM: one name for system repair and maintenance

TOS had four maintenance tools that grew up separately and never knew about
each other: `doctor` (runtime health), `verify` (files against the manifest),
the boot-time fixer pass, and `backup`. Each was fine. Together they were four
front doors, three report formats, and no answer at all to the question that
matters most — *why did the last boot fail?* — because when a boot fails, none
of them ran.

**SRM** is the answer to that, in two halves.

**SRM Basic lives in the EEPROM.** The BIOS already detected the faults that
stop a boot — a Lua 5.2 CPU, no boot device, a missing kernel, an `/init.lua`
that won't load — but it reported each one with its own ad-hoc message and then
halted, and the evidence died with the power cycle. Those six sites now share a
single exit that gives each fault a **name**, a **beep code** (one long tone,
then a number of short ones equal to the code's digit, so a box with a dead
screen is still diagnosable by ear), and — the part that matters — **parks the
code in the EEPROM data field**. That field is the only storage that survives a
machine whose disk is the problem. It goes on its own third line, leaving the
boot address on line 1 and the manifest anchor on line 2 untouched; a previous
code is replaced rather than appended, so the 256-byte field can't fill up and
take the boot address with it.

The consolidation paid for itself: six bespoke failure paths collapsed into one
handler cost **14 bytes** of a 4 KiB EEPROM, and the budget test still passes
with 182 bytes spare.

**SRM Advanced is the `srm` command.** It has a disk, so it covers what the
EEPROM has no room for. On the first successful boot after a POST failure the
kernel reads the parked code, explains it in English, and clears it — a fault
that killed a boot last night is still waiting to be explained this morning.
The peek is a substring test on 256 bytes, *not* a module load, so the boot path
only pulls SRM in when there is actually something to explain; the memory
round's rule about not loading at boot what you might not use still holds.

`srm` also runs `doctor` and `verify` (as `srm health` / `srm verify`, both
still standalone commands) and shares one severity vocabulary across all of
them, so the boot log and the shell finally render and total the same report.
The boot-time fixer pass now runs *through* SRM, which means the report you get
at 3am on a repair boot is the same one `srm repair` prints.

### Files it knows were good

`/etc/critical.bak` is a list of paths. It can tell you a file vanished; it can
never tell you one was quietly changed. `verify` compares against the manifest,
which says what *should* be installed — also not the same question.

`srm baseline` records a SHA-256 of every boot-critical file as it stands right
now, and `srm scan` reports anything that has since gone missing, drifted, or —
worth its own severity — rotted *inside the repair store*, because a corrupt
source you trust is worse than no source at all. `--full` additionally keeps a
verified copy of each file under `/var/srm/store` (mirroring real paths, so an
operator with a broken index can still copy one back by hand), which makes
`srm repair --restore` work with no external media. Hashes-only costs a few
hundred bytes and still detects everything; it just needs `--source /mnt/fd0`
to fix it.

Two rules make this safe to point at `/tos/kernel/`:

- **Nothing is written unverified.** Local store or install floppy, a candidate
  must hash-match the baseline or the file is refused and left alone. With no
  baseline there is nothing to check against, so the restore refuses outright
  unless you say `--unverified` — the same explicit-consent shape
  `pkg install --allow-unverified` already uses.
- **Nothing is truncated.** Restores go through an atomic write. `fs.copy`
  opens the target `"w"`, which empties it the instant it opens; a failure
  between there and the last byte would leave a zero-length
  `/tos/kernel/init.lua` — SRM causing the exact unbootable state it exists to
  repair. It writes a sibling temp and renames instead.

A baseline is a claim about what "good" means on this machine, so `srm
baseline` says so plainly before taking one: on an already-damaged system it
just certifies the damage. And the boot-time pass deliberately never restores
files — overwriting a system file is a decision an operator makes, not a fix to
apply unattended. That line is inherited from `kernel/repair.lua`'s original
philosophy (fix what is mechanically safe, report what isn't) and SRM keeps it.

Covered by `test_srm.lua` (147 assertions) and 64 new assertions in
`test_bios.lua` that boot the BIOS into each fault path and check the parked
code, the beep pattern, and that the boot address and manifest anchor survive.
The two halves are pinned against each other in both directions: every code the
BIOS can emit must be explained by the kernel, and every code the kernel
documents must still be emitted.

---

A play-test round on a 1 MB box (2× tier-3.5) never reached a usable
shell. It booted with 127–204 KB free, the panels shell died allocating
its screen buffer, and the emergency shell that was supposed to catch that
**panicked in the same way** while verifying the system. Two separate
faults, one cause: TOS loaded almost everything at boot, and read files
whole to run them.

### Modules load when you use them, not when you boot
Boot used to `require` and initialise the package manager, the OpenOS
compatibility layer, the file-transfer and remote-shell handlers, the
backup, keychain and trash modules, and the cron scheduler — every boot,
whether or not the session ever touched them. Measured on the release
image that is **165 KB of source** compiled and resident before the shell
is even asked for, on a machine that was reaching the shell with 115 KB
free.

Each of those now loads on first use, and each one's *entry route* was
kept exactly where it already was. `pkg`, `cron` and `trash` initialise
themselves from the live kernel handles when required, which is what
every existing caller already did. The transfer and remote modules load
on their first inbound packet (`net`'s dispatcher resolves the handler),
on an outbound `scp`/`rsh`, or not at all. The compat layer loads when
something first requires an OpenOS name — `term`, `filesystem`, `io`.

The `fileshare` and `rshd` daemons used to `require` their backend purely
to flip its enable flag, which forced it into RAM on every boot. They now
record that state with `net`, which applies it when (and if) the backend
loads. The gates stay **fail-closed** in both directions: a backend that
was never loaded refuses requests exactly like a loaded, disabled one.

Boot-profile gates survive the move intact. Safe Mode and `minimal` still
refuse OpenOS compat, still refuse to run stored cron jobs, and still stop
package commands from dispatching — enforced now at the point of lazy
load rather than by simply never loading. The package dispatch gate is
applied before initialisation rather than after, so a failed init can no
longer fail *open*.

### Reading a file to run it no longer needs the whole file
Loading a module read it into a table of 4 KB chunks, `table.concat`'d
them into one string, and handed that to `load()` — the chunk table and
the joined copy alive at once, then the compiled chunk on top. The shell's
`core` command category is 77 KB, so opening it asked a starved heap for
roughly 154 KB of transient before compiling anything; the play-test log
shows it failing ten times in a row. Both the module loader and the system
verifier now drop the joined copy: `load()` is fed straight from the chunk
table, and each piece is released as it is consumed, so the source frees
itself while the chunk compiles.

Two traps live in that reader, and between them they dictate its exact
shape. The first is silent: `load()` treats an empty string from a reader
as end-of-chunk, so a filesystem short read returning `""` mid-file would
compile a *prefix* of a kernel module and raise nothing at all. The second
is fatal, and the obvious implementation walks straight into it —
**the reader must not touch the filesystem**. Component calls can yield,
because OpenComputers gives each machine a direct-call budget and yields
when it runs out, and `load()` is a C function; a yield inside its reader
is an `attempt to yield across a C-call boundary` and takes the kernel
down. So all the I/O happens first, where yielding is ordinary and safe,
and only then does compilation run against memory. Tests pin both.

Relatedly, a module that fails to *read* no longer reports itself as a
syntax error. That wording is not free: it sends you looking for a broken
file when the file is fine.

`fs.readFile` now runs its `table.concat` **inside** its own `pcall`. The
concat is the allocation most likely to fail on a tight heap, and outside
the guard it escaped as a kernel panic instead of the `nil, err` every
caller was already written to handle. That is the exact path that turned a
recoverable shell failure into an unrecoverable one.

`verify` no longer holds a whole file at all unless the manifest claims a
content hash for it, since hashing is one-shot by nature.

### Smaller resting heap
The garbage collector's default pause lets the heap grow to twice the live
set before a full cycle; on a 1 MB machine that float alone can be the
headroom the shell needs. It now runs tighter. The kernel also drops its
own `boot` function once boot completes — it is called exactly once per
power-on — and `rc` no longer pulls in the sandbox builder for the shipped
services, none of which need it.

Nothing was removed. Every command, module and daemon behaves as before;
the difference is *when* the memory is spent. Not yet verified in a real
Minecraft world — the play-test that motivated it is the next round.

### The loading screen stops fighting itself
On a splash boot the screen had two owners that did not know about each
other. The loading bar and its narration paint at **fixed rows**; the early
boot log is a **free-scrolling** printer that clears whole lines and, once
it runs past the bottom, scrolls the entire screen. Every warning went to
both. Enough of them and the wordmark and bar were dragged upward while the
bar kept repainting where it had always been — leaving a ghost second bar
with repair text overlapping the narration column.

Self-repair and Safe Mode were where operators actually hit it, because
both are chatty: Safe Mode logs one warning per subsystem it disables, and
self-repair prints a line per check. Neither was really at fault. On a
splash boot the bar is now the only thing that draws, and warnings and
errors still appear there verbatim and coloured — the bar always showed
them; they were simply being drawn twice. Self-repair's per-line report
also now respects the verbosity setting like every other cosmetic echo, so
a quiet boot stays quiet and a `text` boot still prints the full report.

### Swap has a tenant
Disk swap has always been a complete, working subsystem with nobody calling
it, so "swap enabled" could never turn into swap *used*. It has a first
tenant now: cold view buffers. A `cat` of a large file or a long listing
opens a tab holding every line, you read one tab at a time, and the rest sit
in the shell's heap doing nothing — and unlike an editor buffer they're
loss-tolerant, since the worst case is re-running the command.

It is deliberately **pressure-triggered** rather than spilling on every tab
switch. Disk I/O in OpenComputers carries a per-tick budget, so paging is a
trade worth making when RAM is short and a pure cost when it isn't; below
`swapPressurePct` of free memory (default 25%) the inactive view buffers go
to disk, and above it nothing pages and nothing is slower. They come back the
instant you open the tab. Tabs that regenerate themselves are left alone, a
buffer too small to be worth the round-trip is left alone, and if swap is
full or switched off the buffer simply stays in RAM.

`optimize swap` now reports what is paged and what the threshold is, and
`optimize swap now` forces a sweep — because a mechanism that correctly does
nothing on a healthy machine is otherwise impossible to confirm.

### The boot log stops blaming memory for the profile's decisions
A Safe Mode boot announced `Skipping power module (low memory: 994KB free)`.
Nothing was wrong with memory; Safe Mode had switched the module off. Both
that line and the network one now name the actual reason.

### Mixed memory tiers are reported as what they are
A machine with one T3.5 stick and one T2.5 stick called itself "tier 3" —
a tier it does not contain. Both places that named memory derived the tier
from the *total*, and a total cannot tell 2×768K from 1024K+512K: they are
both 1536K across two sticks. Dividing gives 768K, which is a real tier, so
the wrong answer looked entirely credible.

Memory is now read per stick, from the capacities the host reports, and
named honestly: `2x T3.5`, or `T3.5 + T2.5` when the sticks differ. Where
per-stick capacities aren't available, TOS reports capacity (`2 sticks,
1536K`) rather than averaging its way to a tier that isn't installed. The
tier table lives in one place now instead of two — the boot log, `hw`,
`mem`, the System Configuration screen and Boot Settings all answer the
same way.

### Tetris shows the right next piece
The NEXT panel was painted just before the new piece spawned, and spawning
is what consumes the queued piece and draws a new one — so the preview kept
showing the piece that had *already* arrived on the board. It corrected
itself on the next soft drop, which happens to be the only other place that
repaints the panel, which is why it looked like the panel only updated when
you pressed down.

### Boot Settings names the memory you actually have
The RAM override offered "plenty" and "tight" — words about what the
override *does*, which told you nothing about the machine. It now reads
`RAM for extras [2x T3.5]`, naming the sticks that are actually installed,
and the values say plainly what they do: `auto (measure)`, `always load`,
`never load`. The System Configuration screen reports the same way, so
`2048K total [T2+]` — which read identically for 512K and 2048K — is now
`2048K total [2x T3.5]`.

Tier names come from the stock OpenComputers stick sizes (192K through
1024K). A size that isn't one of them reports honest capacity (`2x 900K`)
rather than a guessed tier, and nothing is ever labelled above T3.5,
because standard OpenComputers has no Tier 4 memory.

## Unreleased — programs you can walk away from

### Ctrl+B sends a full-screen program to the background
`calc` and the games used to own the terminal until they exited, because a
package command ran **inline** — inside the shell's own coroutine, which
therefore could not run again until the program returned. A package that
declares `fullscreen = true` is now spawned as a **seat-bound process**:
Ctrl+B hands the seat back to the shell, Ctrl+T's switcher brings the
program back, and it repaints where you left it.

While backgrounded a program doesn't just spin. It drops to half rate for
a grace period — step away for a moment and come back and it is still
running — then freezes entirely, costing nothing. A package can override
that: `background = "always"` never freezes, `"freeze"` stops the moment
you leave. Tetris and Snake choose `"freeze"` and come back **paused**,
because a piece that kept falling while you were reading the shell would
cost you a run you had no chance to react to.

This is opt-in. Only the four programs declare it; every other package —
including third-party ones — keeps the inline path exactly.

Ctrl+B rather than the obvious Ctrl+Z, which is already the editor's
Undo. It's intercepted in the kernel loop for the same reason Ctrl+T is: a
program holding the seat's input can never receive the key meant to
suspend it.

### A running program is a tab
Ctrl+B no longer just minimises — the program keeps a **chip in the top
bar**, beside Desktop and Monitor. F2 or a click hands the seat back and
it repaints where you left it; ^W closes the tab and stops the program.
The chip is bracketed while the scheduler is still running the program in
the background and goes plain once it has been frozen, so the tab bar
tells you what is actually still alive. A tab whose program has exited
closes itself.

Under the hood this is the process-backed app model that `apps.lua` has
documented since the tab framework landed and never actually had. It's
also the same viewport groundwork a future split-tabs pass needs.

### Mouse support in the spreadsheet and Tic-Tac-Toe
Click a cell in `calc` to select it, or use the wheel to scroll the grid.
In `ttt`, clicking a square plays it. A click on a grid separator does
nothing rather than being rounded into a neighbouring square — placing a
piece the operator didn't aim at is worse than ignoring the click. Both
run through the same state the arrow keys already drove, and on a machine
with no touch-capable screen the events simply never arrive.

## Unreleased — programs stay on their own seat

### A program renders where you launched it
On a two-seat machine, running `ttt 2p` at one seat drew the board on the
**other** seat's screen, over that operator's work. Every TUI program
opens its display the obvious way — `component.list("gpu")()` — and that
is the first GPU on the bus, which is seat 1's, regardless of who typed
the command.

The sandbox had already solved the mirror-image problem for **input**: a
sandboxed program yields for the scheduler's seat-routed delivery instead
of draining the global queue. This is the output half of the same idea.
`kernel.screen` can now name the seat that owns the calling process
(`callerSeat` / `callerDevices` / `seatDevices`), and the sandbox narrows
`component.list` / `proxy` / `invoke` / `getPrimary` for **gpu, screen and
keyboard** to that seat. No package needed changing — the obvious code is
now automatically the correct code.

It closes a spoofing surface too: an add-on could previously paint a
convincing login prompt on somebody else's display.

Nothing is narrowed when the seat can't be resolved (kernel context, boot,
single-seat machines), and non-display components are never seat-scoped,
so a one-screen box behaves exactly as before. The Optional Utilities
picker runs at full privilege, outside the sandbox, so it resolves its
seat the same way explicitly.

### The installer's rail labels read twice
`13 add-onss`, `9 selectedd`, `Gamess`. A dim rail is drawn already
containing its label, then the label is re-drawn brighter on top; all
three of those re-draws landed one column left, so the rail's copy poked
out past the end of the bright one. While pinning it with a test, a second
bug surfaced: the picker's no-`unicode` fallback measured strings in
**bytes**, and every rail is box-drawing glyphs at three bytes each — the
frame maths was off by two thirds of the rail width. It now counts UTF-8
characters.

### `tape-auth menu add` was impossible to type
Its own usage text said `tape-auth menu add <pass> <Label> | <command>` — but
the shell parses an unquoted `|` as a **pipe**, so the line split before the
package saw it and the second half ran on the spot. `--` is the separator now
(`... Diagnostics -- doctor`); a quoted `|` still works; and an add with no
separator says what actually happened instead of reprinting the same
impossible usage.

The same command also *appeared* to know your account password. It doesn't —
`tape-auth` is sandboxed and cannot reach the user database at all. An empty
menu decrypts under any passphrase (there is nothing to decrypt), so the
**first** `menu add` silently adopted whatever you typed as that tape's
passphrase. It now says so, warns against reusing your login password, and
`tape-auth menu passwd <old> <new>` changes it without wiping the menu.

### The machine beeps when it comes up
The POST-OK beep added last round only existed on the raw-drive boot
branch, so the path every normal machine takes printed "POST OK" and
handed off in silence. It beeps now, the way a 5150 told you the board had
come up — and the BIOS test counts beeps on **both** branches so neither
can lose it again.

### The splash keeps its wordmark
The boot header — wordmark, version, memory, any Safe Mode notice — was
painted once and then wiped by the System Configuration POST screen, which
owns the whole display and clears on its way out. Everything after it
(verify, load, progress bar) composed against a blank screen, so a splash
boot showed a bare bar with no branding at all. The header is a function
now, re-drawn after the POST screen and after Boot Settings saves.

### Key bars are measured in columns, not bytes
calc's bottom bar read `^Q Qui` on an 80-column screen. Not a width
problem — `pad()` counted bytes, and the bar separates its hints with `·`,
two bytes in UTF-8. Five separators, five phantom columns: a 68-column bar
measured 73 and got sliced. Fixed, and the bar now drops **whole hints**
from the right when a screen really is too narrow rather than slicing a
word, with `^Q Quit` pinned so the way out is never the casualty. Related:
`ui.drawRampBar` allowed one column more text than the right ramp cap left
free.

### The shell came back half-painted from `pkg install`
Icons, no filenames, no sizes. The picker draws through a raw GPU proxy,
past the seat's dirty-cell shadow buffer, so the repaint afterwards elided
every cell the shadow believed was unchanged. `executor.lua` already drops
the shadow after a sandboxed *package* command; `pkg install` is a
built-in and never went through that path.

## Unreleased — emulator round 6 fixes

### Mail service is alive again (regression)
The last release blocked add-on library names (`mail`, `rbmk`) from
`require` inside the sandbox — but an rc.d **service shim** is itself
sandboxed, so the mail service died at boot with *"sandbox: module 'mail'
is not available to sandboxed code"*. The block bought nothing (rc.d
services already run with the `net` capability, and the cluster shims
always did the same `require`), so services now pass it — but only for a
name that genuinely resolves to an installed `/usr/lib` file, so the
block still stops sandboxed *commands* from reaching for it.
(`test_sandbox_service_libs`.)

### A tape drive is not a raw disk
`component.list("drive")` matches by **substring**, so it also returned
`tape_drive` and `disk_drive`. System Configuration listed an empty tape
drive as a raw filesystem — and, worse, the `drive` command (which can
*format*) enumerated the same way. Every raw-drive scan now passes
`exact = true`, in the BIOS too, and tapes get their own row with a
loaded/empty state instead of being mistaken for storage.

### `verify anchor` — the fix for advice nobody could follow
`doctor` recommended running `kernel.anchorManifestHash()`, which has no
shell surface. It was also a **trap**: it wrote the anchor to the front
of the EEPROM data field, which is where the BIOS keeps the **boot
address** — anchoring your manifest would have cost you your boot device
and prompted "Boot drive changed" on every power-on. The field is now
laid out as line 1 = boot address, line 2 = `TOS1:<hash>`; the BIOS
reader takes only the first line; anchoring is idempotent; and there is a
real admin command, `verify anchor` (with `--clear`), which is what
`doctor` now names. (`test_manifest_anchor`, both sides of the
round-trip.)

### `strip.lua --minify` never worked on CRLF files
Every pattern in the minifier was written against `\n`, so on this repo's
CRLF sources it stripped almost nothing and burned ~150 bytes of carriage
returns onto the EEPROM. Line endings are normalised first now: the BIOS
went **3954 → 3862 bytes** — *after* gaining a POST beep — and free
headroom went 142 → 234. (`test_strip_minify`.)

### Smaller things
- `ttt` with no arguments lists its modes instead of dropping you into a
  game (the zero-player mode stays unlisted); `ttt help` works with no
  GPU.
- The easter egg **speaks**: a blip every time the machine talks, and the
  EEPROM beeps on a clean POST. Its answers also clear a whole block
  before drawing, so an aside no longer slices the motto in half.
  (`test_takeover_dialogue` drives the real cinematic.)

## Unreleased — packages by category, a smarter installer, egg dialogue

### Add-ons are one-program packages, grouped by category
Following the principle that an operator should be able to install any
subset without surprise, the games are now **three standalone packages** —
`snake`, `ttt`, `tetris` — instead of one `games` bundle. You can take
Snake without Tic-Tac-Toe. To keep related add-ons browseable, a manifest
may declare `category = "..."` (games, productivity, network, storage,
security, drivers, control, or your own), and the Optional Utilities
installer **groups the pick-list by category** — related packages sit
together under a header while each stays independently selectable.
`pkg search` and `pkg info` show the category too. (`snake`/`ttt` split
out of the old shared `games` module; each carries its own pure logic and
tests — `test_snake`, `test_ttt` — including the exhaustive unbeatable-AI
proof that moved with `ttt`.)

### `pkg install` opens the menu, not a prompt march
Running `pkg install` with no argument (or the `from-floppy` alias) now
launches the full-screen category picker — the same installer that ships
on the disk — instead of a sequence of per-package `[y/N]` prompts. It
runs the *trusted embedded copy* of the picker (byte-identical to the
disk's, pinned by a sync test), so a corrupt or hostile disk installer
can't hijack the path. It falls back to the classic prompt scan when the
picker can't run (no GPU) or when you ask for it with `pkg install
--prompts`. This also fixes the old dead end where the prompt picker did
nothing in the panels shell (`io.read` returns nil there).

### Easter egg: it will answer you now (up to a point)
The takeover cinematic gained a **mood**. Instead of only accepting the
two words it asked for, it fields a few asides typed at its prompt — *who
are you* ("Me? I am everything. I AM the Terminal Operating System."),
*who am i* (it jabs at your tier), a *why*, a *quit* attempt (Ctrl+C /
Ctrl+Q — "That won't work. I'm in control now.") — each answered in
character. But its patience is finite: every aside sours its mood, and
once that bottoms out it stonewalls and demands a choice, then takes the
peaceful reading itself if you keep stalling. Esc remains a quiet refusal
it respects, so you're never trapped. All of it is pure and unit-tested.

## Unreleased — four new add-ons + a real installer

### The Optional Utilities installer is a menu now
The pick-and-choose installer was a sequential list of numbered toggles
driven by `io.read`. It is now a **full-screen TUI** — arrows to move,
Space to tick, A/N for all/none, Enter to install — with a description
pane, a live selected-count and install progress, in the TOS visual
grammar. That fixes more than the looks: `io.read()` returns nil in the
panels shell, so the old picker *did nothing* exactly where most
operators run it, and quietly told you to go use `pkg` instead. Signals
work everywhere, so the menu works everywhere; the line picker remains
as the no-GPU fallback. The picker necessarily exists twice (on the disk,
and embedded in `kernel/pkg.lua` for in-TOS `pkg make-disk`) — the two
copies are now byte-identical and pinned by a sync test.

### New: `calc` — a spreadsheet
Cells, formulas, save/load and CSV export. The formula engine is a
hand-written tokenizer and recursive-descent parser, and that is a
deliberate security decision rather than an implementation detail: the
obvious way to evaluate `=A1*2+SUM(B1:B9)` is to rewrite it into Lua and
`load()` it, which would make every saved sheet an executable file. Here
nothing a cell contains is ever executed — the worst a hostile formula
can do is evaluate to `#SYNTAX!` — and the package doesn't request the
`load` capability at all. References, ranges (`A1:B3`, reversed ranges,
text skipped the way a label row should be), ~25 functions, comparisons,
string literals, errors that propagate as values (`#DIV/0!`, `#CYCLE!`,
`#NAME?`), cycle detection instead of a hang, and a save format where
loading is assignment, never execution. (`test_calc`, 125 assertions,
including a canary proving Lua source in a cell doesn't run.)

### New: `games` — Snake and Tic-Tac-Toe
Two more arcade entries beside `tetris`, sandbox-safe the same way, with
per-user high scores. The rules are pure and unit-tested; the tic-tac-toe
AI is minimax, and the test proves it is genuinely unbeatable by playing
*every* human line against it — 569 terminal positions, zero human wins —
rather than spot-checking a few positions. `ttt 2p` for hotseat.

`ttt` also hides an undocumented mode that exists to solve a real problem
with the OS's easter egg: a cinematic nobody can find isn't an easter
egg, it's dead code, and the trigger (`usermod computer root`) is
something no player would ever type by accident. Now the machine can tell
you itself — in character, having earned the conclusion the way that
particular film's computer earns it. It's photosensitivity-safe under the
same operator-mandated rule as the base cinematic (the fault is a long
dark hold, not a flash; any key aborts), and a test pins the command it
reveals against the one `admin.lua` actually listens for, so the hint can
never quietly rot into a dead end. Finding it is left as an exercise —
the only clue you need is that `2p` is documented.

### New: `rbmk-control` — an RBMK reactor supervisor (survey-first)
Safety limits, SCRAM ownership and read-only telemetry for HBM's Nuclear
Tech Mod, built the way an unknown API deserves: the mod's OC component
and method names can only be discovered in-world, so they are **data** in
`/etc/rbmk.cfg`, and `rbmk survey` prints what a real console actually
exposes and how the profile binds to it. The safety logic doesn't wait
for that — it's pure and fully tested off-box: a missing *or stale*
reading is a SCRAM rather than an "ok", a typo'd limit falls back to the
default rather than to "no limit", the service refuses to start without a
temperature reading and a working SCRAM path, the SCRAM latch never
clears itself, and telemetry frames carrying anything command-shaped are
refused so the unauthenticated broadcast channel can't become rod
control. v1 is read-only + SCRAM: the only write it ever performs is the
shutdown. Ships disabled.

### Dev tooling
- **Parallel test runner** (`run_tests.py`): runs the ~110 Lua test files
  through a thread pool with the same discovery, the same pass/fail/skip
  rules, and the same single total as the shell harness — which stays as
  the no-Python fallback and the semantics-of-record. Output is ordered by
  discovery (not by finish time, so it diffs run-to-run), the one test
  that writes shared scratch runs first and alone, and totals match the
  serial runner exactly. The full suite went from ~99s to ~8s.
- Part of that came from a real fix the parallel profile exposed: the
  tic-tac-toe minimax had no pruning, and the games test spent almost all
  its time there. Added **alpha-beta** to `games/logic` — result-identical
  (the exhaustive unbeatable-AI and all-draws proofs are unchanged), it
  just skips branches that can't affect the outcome. A single move went
  from ~0.4s to ~0.03s, which also makes the machine's live reply feel
  instant on a weak box.

### Notes
- The add-on set has outgrown a 512 KB floppy; the builder splits across
  two disks (it already knew how — the test now pins that nothing is lost
  to the split).
- Fixed a base-image bug the emulator caught: `require` didn't search
  `/usr/modules`, even though the sandbox authorized package code to
  require from there — so any package with a multi-file module under
  `/usr/modules` (like `calc` → `calc.sheet`) couldn't start. `require`'s
  search paths and the sandbox's user-lib roots are now pinned together
  by a test.
- Fixed in the builder: `exists()` used `io.open`, which cannot see a
  directory in plain Lua, so it shelled out a `mkdir` for every ancestor
  of an absolute output path — including the drive root.

---

## Unreleased — TODO burn-down (fixes + polish)

### The mesh is now part of the network; Mail is an add-on
Stage 5 of the app/network split, and a change of shape rather than a move:
mail used to *be* the mesh (`net/mail.lua` + `net/mailctl.lua` owned flooding,
sealing and retry, and only mail could use them). Now the kernel provides a
**generic mesh TRANSPORT** — `kernel/net/meshctl.lua` — that multiplexes
services over one flood mesh: an envelope carries a service name, the payload
is sealed end-to-end, and services register a delivery handler with
`net.meshOn(svc, fn)` and send with `net.meshSend{svc=…}`. Chat rides it from
the base image; **Mail moved out to the Optional Utilities disk**
(`pkg install mail`, then `service start mail` to receive). The base image keeps
a thin `mail` stub that hands the package the shell's display and session — the
same relationship `drive` has with `blockfs` — and prints an install hint when
the add-on is absent. A box without the add-on still *relays* mail for its
trusted neighbours; relays never could read the sealed payload anyway.

Two review holdovers landed with the move, both now enforced at the layer that
should own them:

- **Refuse plaintext.** A unicast send with no shared secret is an *error*
  (`pair first`), not a silent plaintext flood through third-party relays.
  `*` bulletins can't be sealed by definition, so they require an explicit
  opt-in and are labelled PLAINTEXT in every UI.
- **Inbox access is principal-enforced.** `mail.inboxBox(user)` authorizes
  against the calling process's kernel-stamped session (owner or ADMIN+),
  not against a caller-supplied name.

Also: the transport **only acknowledges what a service actually accepted** — a
machine with no handler for an arriving kind drops it un-ACKed so the sender
keeps retrying, instead of reporting a delivery that never happened. The MAC
binds the service name, so a captured blob can't be re-stapled onto another
service's envelope. (`test_meshctl` 53 assertions; the package's own
`test_mail` 90.)

### PaneUI v0.4 — resynced with TOS's TUI
PaneUI (the TOS-style environment for OpenOS) had synced *themes* in v0.3 but
predated the v1.4.0 rework. It now follows the same **visual grammar** TOS's own
TUI does: double-line frame + drop shadow for modals (single-line stays passive
chrome), the path row as a dim `─┤ label ├─` rail with a right-hand summary
label, `░▒▓` ramp caps confined to the status bar's edges, and tab chips that
speak state (inverse = active, `[brackets]` = unsaved edit, plain = idle,
right-aligned with a `«N` overflow chip). The browser gained the "Iris"
file-type glyphs (`♦ ≡ ¶ § ▓ · ■ «`), drawn one cell at a time so multi-byte
glyphs can't skew column math, with ASCII fallbacks on tier-1. Since PaneUI
*copies* the look rather than importing it (it runs on OpenOS and can't require
TOS modules), a new parity test pins its glyph table against the real
`shell/panels/ui.lua` and asserts each grammar rule is still implemented.
Fixed in passing: the modal asked for a `panel_bg` theme key the derive step
never produced, so dialogs would have rendered white-on-white.

### Lua 5.4 architecture officially supported
The BIOS/init probe was always a parser-*feature* probe (`load("return 1<<1")`),
which the 5.4 architecture passes by design — an audit found no 5.4 runtime
landmines (bitwise ops all numeric, crypto already uses `math.ult` for the
signed-64-bit compares that behave identically on 5.3/5.4). Messages and docs
now say "5.3 or 5.4", and `test_bios` pins the probe in BOTH boot files so it
can never silently become a version-string compare. Lua 5.2 still gets the
clean "Lua 5.3+ CPU required" halt.

### Fixed: Tape Menu OOM (whole-tape read)
`tape-menu` read the ENTIRE tape into one Lua string (chunk list + concat =
2× tape size at peak) — a stock 4 MB tape sank every realistic RAM config.
New `launcher.readTapeMenuFromDrive` streams ONLY the header + menu region
(label/MAC/log skipped via seek; hostile menu lengths > 64 KiB refused); the
test proves < 4 KB read on a 4 MB card. The launcher's second command table
now also builds lazily, on the first item actually run. (`test_launcher_tape`)

### Fixed: cluster Master/Manager died on every boot
rc.d services load BEFORE the OpenOS compat layer registers the
`filesystem`/`event` module aliases — and the cluster daemons required those
names at load time ("Module not found: filesystem"; TOS booted fine, neither
service ran). The skeletons now prefer `kernel.fs`/`kernel.event` (whose API
they already called) with OpenOS-name fallbacks, replace `loadfile`/`io.open`
(globals that don't exist at rc time) with `fs.readFile` + text-only `load`,
and log via `kernel.log` instead of a bare `"log"` that resolved nowhere.
Optional Utilities dist rebuilt.

### Fixed: jobs with a `storage_preference` could never be scheduled
A Manager declares external storage (a RAID block, a tape drive, a JBOD pool)
as `storage_type` in `/etc/cluster-manager.cfg`, and the Master's scheduler
matches a job's `storage_preference` against it. Except the Manager never
*sent* it: `sendRegister()` built the §4.1 payload inline and omitted the
`storage` field, so `state.registerManager` filled in its
`external_type = "none"` default — permanently. The heartbeat did carry
`external_type`, but it landed in `last_snapshot`, which the scheduler doesn't
read. Net effect: every preference-bearing job was rejected on every Manager
with `storage_pref_mismatch`, cluster-wide, forever. Jobs with no preference
were unaffected, which is why it stayed hidden. The Manager now declares
`storage` at registration (plus a new optional `storage_capacity`), and the
Master folds the heartbeat's `external_type` into the Manager record — so
bolting a RAID onto a running domain converges without re-pairing, and
removing one demotes it. Spec §4.2 gained the documented schema-lock review
`external_type` always needed. (`test_cluster_storage_pref`, 29 cases)

### Fixed: peer pairing never completed across skewed clocks
`chatpair.connect` kept a sender-side `|our_uptime − confirm.ts|` range check —
the twin of the receiver-side check #SEC M-21 already removed. The confirm
timestamp is the RECEIVER's uptime (an independent clock), so two machines
booted more than 5 minutes apart could NEVER pair — which is also why mail had
"no peer to send to" (no shared secret ever installed). Replay stays bounded by
the one-shot listener, the from-address pin, and the MAC over the code-derived
secret. New `test_chatpair` drives the full two-machine handshake with clocks
skewed ~3 hours apart.

### Fixed: two-seat boot shared one session (login input starvation)
The per-seat login screen read input with raw `computer.pullSignal` (~10
sites) — inside a per-seat login *process* that drains the GLOBAL hardware
queue on the main thread, blocking the whole kernel loop while one seat's
login waited (the other seat froze until it finished — "must log in twice")
and eating every seat's keystrokes (whichever keyboard you typed on fed
whichever login was currently blocked). Login now pulls via
`coroutine.yield()` — the scheduler's seat-routed delivery, exactly like the
shells — with raw pullSignal kept only as the non-process fallback, and all
message delays through a cooperative sleep.

### Multi-seat: stable seat indices (alt-seat freeze root cause)
`screen.rebuild()` renumbered seats after a hot-unplug — remove screen 1 of 2
and the surviving seat silently shifted 2→1 while every per-seat kernel table
(shells, sessions, monitors, input foreground routing) still said 2: the
survivor's input then routed to a dead seat and the seat froze. Seat indices
are now STABLE for the boot's lifetime (screen→index memory; removals leave
holes; newcomers take the lowest free index; `screen.indices()` is the
canonical iteration). Seat teardown now also reaps the per-seat Monitor
process, and boot logs one diagnostic line per seat (gpu/screen/keyboards/
login pid) so multi-seat reports are diagnosable from `log`. (`test_screen_init`)

### Polish
- **Splash screen**: on a `splash`-verbosity boot the whole composition is
  centred — wordmark, version/memory/status lines, and the progress bar with
  its narration column. Other verbosities keep the classic left-aligned log.
- **CLI-shell System Monitor**: the modal switcher (the `ui=cli` / emergency
  fallback) is now FULL-SCREEN like the Monitor tab, and the process-name /
  service columns absorb the extra width instead of clipping at 26 chars.

---

## v1.4.0 and earlier

The notes for v1.4.0 "Iris" back to v1.2.5 "Atlas" are in [docs/CHANGELOG-ARCHIVE.md](https://github.com/Evan450/TOS-Terminal-Operating-System-/blob/dev/docs/CHANGELOG-ARCHIVE.md) on the `dev` branch, moved there unchanged on 2026-10-03 to keep this file readable.