init.lua

-- SPDX-License-Identifier: GPL-3.0-or-later
-- Copyright (C) 2026 Discover! Interactive
-- ╔══════════════════════════════════════╗
-- ║  TOS init.lua - System Bootstrap     ║
-- ║  Terminal Operating System v1.5.0    ║
-- ╚══════════════════════════════════════╝
-- Works with TOS BIOS (receives bootFS as arg)
-- AND with standard Lua BIOS (finds bootFS itself)

-- bootFS may be passed by TOS BIOS, or nil if standard BIOS
local bootFS = ...

-- In OC, component and computer are machine globals.
-- Do NOT use require() here - it doesn't exist yet.
local component = component
local computer = computer

-- ============================================================
-- Lua architecture guard
-- ============================================================
-- Several kernel modules (crypto, net, display, jbod, vault, compress,
-- backup, launcher) use Lua 5.3 bitwise-operator SYNTAX, and the boot
-- chain (BIOS TBFS reader, blockfs) needs string.pack. OC lets players
-- switch a CPU to the Lua 5.2 architecture; there, display.lua — on the
-- mandatory boot path — fails to PARSE, so without this probe the
-- failure mode is a kernel panic showing a raw syntax error from a
-- perfectly healthy disk. Probe the parser itself (this file contains
-- no 5.3 syntax, so it always gets far enough to run) and halt with
-- the actual fix. NOTE: keep this file 5.2-parseable.
-- Lua 5.4 is SUPPORTED on purpose: it parses 5.3 syntax and provides
-- every stdlib feature TOS uses (integers are 64-bit signed in both;
-- code that cares — crypto's unsigned compares — already uses
-- math.ult). A parser-feature probe passes there; keep it that way —
-- never replace this with a version-string or architecture-name
-- compare (test_bios pins the probe in both boot files).
if not load("return 1<<1") then
  local g
  for a in component.list("gpu") do
    local ok, px = pcall(component.proxy, a)
    if ok and px then g = px break end
  end
  local scr
  for a in component.list("screen") do scr = a break end
  if g and scr then
    pcall(g.bind, scr)
    pcall(g.setBackground, 0x000000)
    pcall(g.setForeground, 0xFFFFFF)
    pcall(g.fill, 1, 1, 80, 25, " ")
    pcall(g.set, 2, 2, "TOS requires the Lua 5.3 or 5.4 CPU architecture.")
    pcall(g.set, 2, 3, "This CPU is running an older one (Lua 5.2).")
    pcall(g.set, 2, 5, "Fix: sneak-click (crouch + right-click) the CPU in its")
    pcall(g.set, 2, 6, "computer-case slot to cycle architectures, then reboot.")
    pcall(g.set, 2, 8, "Press any key to power off.")
  end
  pcall(computer.beep, 800, 0.3)
  while true do
    local ev = computer.pullSignal(math.huge)
    if ev == "key_down" then computer.shutdown() end
  end
end

-- ============================================================
-- Stage 0: Find boot filesystem
-- ============================================================
-- TBFS unmanaged boot: the stage-2 bootstrap (blockfs.BOOTSTRAP, run by
-- the TOS BIOS from a raw drive's boot region) already mounted the volume
-- and left the root proxy here. Prefer it — on that path getBootAddress
-- points at a `drive` component, which must NOT be proxied as a
-- filesystem (no exists/open; every fallback below would misfire).
if not bootFS and _G._TOS_UNMANAGED_ROOT then
  bootFS = _G._TOS_UNMANAGED_ROOT
end
-- If TOS BIOS passed it, great. Otherwise find it ourselves.
if not bootFS then
  -- Try computer.getBootAddress (added by standard Lua BIOS or TOS BIOS)
  local getBA = computer.getBootAddress
  if getBA then
    local addr = getBA()
    if addr and addr ~= "" then
      local ok, px = pcall(component.proxy, addr)
      if ok and px then bootFS = px end
    end
  end
end
-- exists() is pcall'd in both scans (#REV review finding #6): a floppy
-- yanked between the proxy and the invoke makes the component call
-- RAISE, which otherwise kills the whole scan instead of skipping the
-- dead device.
local function safeExists(px, path)
  local ok, r = pcall(px.exists, path)
  return ok and r
end
--! #FIX (in-game, 2026-08-11) — TOS needs a WRITABLE root. It writes
--! /etc/users.dat before an operator has even finished the First Boot
--! password prompt, plus /var/log, /home and the whole package tree.
--! Nothing checked, so a read-only device booted "successfully" and the
--! first symptom was `Persist failed: read-only filesystem` in the
--! middle of setting the root password — with no hint of which disk was
--! at fault or that the disk was the fault at all.
--!
--! A component proxy's methods are callable tables (machine.lua), so this asks
--! whether the method is there. It said type(...) == "function", which is true
--! of a test's fake and of nothing real: until 2026-11-01 no real read-only
--! disk got this warning, or the install offer below.
local function safeReadOnly(px)
  if type(px) ~= "table" or not px.isReadOnly then return false end
  local ok, ro = pcall(px.isReadOnly)
  return ok and ro == true
end
--! Both scans below now run TWICE: once accepting only writable
--! filesystems, then once accepting anything. A read-only disk carrying
--! /tos is a fine thing to READ an OS from and a hopeless thing to run
--! one on, so it is the last choice rather than the first one that
--! happens to enumerate — but it is still better than not booting.
local function scanFor(marker)
  for _, requireWritable in ipairs({ true, false }) do
    for addr in component.list("filesystem") do
      local ok, px = pcall(component.proxy, addr)
      if ok and px and px.exists and safeExists(px, marker) then
        if not (requireWritable and safeReadOnly(px)) then return px end
      end
    end
  end
end
if not bootFS then bootFS = scanFor("/tos/kernel/init.lua") end
if not bootFS then bootFS = scanFor("/init.lua") end

if not bootFS then
  error("FATAL: Cannot find boot filesystem!")
end

-- ============================================================
-- Stage 0a: is the root writable?
-- ============================================================
--! Said HERE, at boot, rather than discovered later by whichever write
--! happened to come first. A machine that cannot write its own user
--! database cannot be set up, and the operator needs to know that before
--! they type a password into a prompt that is going to throw it away.
--!
--! Not fatal: a read-only root still boots to a usable read-only system,
--! and being able to look around is exactly what you want when
--! diagnosing this. But it is announced, loudly, once.
_G._TOS_ROOT_READONLY = safeReadOnly(bootFS)
if _G._TOS_ROOT_READONLY then
  local gpuAddr = component.list("gpu")()
  local scrAddr = component.list("screen")()
  if gpuAddr and scrAddr then
    local okG, gpu = pcall(component.proxy, gpuAddr)
    if okG and gpu then
      pcall(gpu.bind, scrAddr)
      pcall(gpu.setBackground, 0x000000)
      pcall(gpu.setForeground, 0xFF5555)
      local okR, w = pcall(gpu.getResolution)
      pcall(gpu.fill, 1, 1, (okR and w) or 80, 6, " ")
      pcall(gpu.set, 2, 2, "WARNING: the boot filesystem is READ-ONLY.")
      pcall(gpu.setForeground, 0xAAAAAA)
      pcall(gpu.set, 2, 3, "Disk " .. tostring(bootFS.address or "?"):sub(1, 8)
        .. "...  Nothing TOS writes will survive, and First Boot Setup")
      pcall(gpu.set, 2, 4, "cannot set a root password at all.")
      pcall(gpu.set, 2, 5, "Install to a writable drive (run install.lua), or unprotect this one.")
      pcall(computer.pullSignal, 5)
    end
  end
end

-- ============================================================
-- Floppy detection: If booting from a small/removable disk
-- while a larger drive exists, offer to install there instead.
-- ============================================================
do
  local bootTotal = bootFS.spaceTotal()
  local FLOPPY_THRESHOLD = 524288  -- 512KB (floppies are ~512KB)
  --! #FIX (loot disk, 2026-09-13) — a READ-ONLY boot disk gets the offer
  --! at any size. OpenComputers mounts a loot disk (the TOS floppy from a
  --! dungeon chest) through ReadOnlyWrapper, whose spaceTotal() returns
  --! spaceUsed() — the size of its contents, ~1.8 MB for TOS (verified in
  --! OC 1.8.10). So the disk that most needed this offer never passed the
  --! size test, and booted into a root that cannot keep a password
  --! (Stage 0a). test_init_readonly_install pins this.
  local bootReadOnly = _G._TOS_ROOT_READONLY
  -- #SEC H1 — a one-time boot (operator chose Shift+Enter at the BIOS for a
  -- changed/fallback drive) explicitly declined to touch boot config. The
  -- migration flow below can re-flash the EEPROM via setBootAddress, so honour
  -- that intent: skip the offer entirely on a one-time boot. The operator can
  -- still migrate deliberately on a normal (EEPROM-committed) boot.
  if _G._BIOS_ONETIME then
    bootTotal = nil
  end
  if bootTotal and (bootTotal <= FLOPPY_THRESHOLD or bootReadOnly) then
    -- Look for a larger disk to install onto
    local largerDisk = nil
    local largerTotal = 0
    for addr in component.list("filesystem") do
      if addr ~= bootFS.address then
        local ok2, px = pcall(component.proxy, addr)
        --! A read-only disk is never a target, however large: a second loot
        --! disk would otherwise beat the hard drive and fail the copy on its
        --! first write.
        if ok2 and px and not safeReadOnly(px) then
          local t2 = px.spaceTotal()
          if t2 and t2 > bootTotal and t2 > largerTotal then
            largerDisk = px
            largerTotal = t2
          end
        end
      end
    end
    if largerDisk then
      -- We're booting from a floppy but a hard drive exists.
      -- Show a choice to the user.
      local g2
      for addr in component.list("gpu") do g2 = component.proxy(addr) break end
      local s2
      for addr in component.list("screen") do s2 = addr break end
      if g2 and s2 then
        pcall(g2.bind, s2)
        g2.setBackground(0x000000)
        g2.setForeground(0xFFFFFF)
        local sw, sh = g2.getResolution()
        g2.fill(1, 1, sw, sh, " ")
        local function gp(y, text, fg)
          g2.setForeground(fg or 0xFFFFFF)
          g2.set(2, y, tostring(text))
        end
        local bKB = math.floor(bootTotal / 1024)
        local dKB = math.floor(largerTotal / 1024)
        -- Every line here fits a Tier 1 screen (50 columns).
        gp(2, (bootReadOnly and "TOS is running from a read-only disk ("
          or "TOS is running from a floppy disk (") .. bKB .. "KB)", 0xFFFF00)
        gp(3, "A larger drive was detected (" .. dKB .. "KB)", 0xFFFF00)
        gp(4, "  source:  " .. (bootFS.address or "?"):sub(1, 12) .. "...", 0xAAAAAA)
        gp(5, "  target:  " .. (largerDisk.address or "?"):sub(1, 12) .. "...", 0xAAAAAA)
        -- #SEC H2 — surface both component addresses so the operator
        -- can confirm what's about to happen before approving an
        -- irreversible disk overwrite + EEPROM reflash.
        gp(7, "1. Install TOS to the hard drive (recommended)", 0x00FF00)
        gp(8, bootReadOnly and "2. Continue read-only (nothing is saved)"
          or "2. Continue booting from floppy (limited space)", 0xAAAAAA)
        --! The answer an overlay adds (kernel/cowfs.lua): run from this disk now,
        --! with what changes kept on the other one, and install later or never.
        local canOverlay = bootReadOnly and bootFS.exists("/tos/kernel/cowfs.lua")
        if canOverlay then gp(9, "3. Run from here, saving to the hard drive", 0xAAAAAA) end
        gp(10, canOverlay and "Press 1, 2 or 3:" or "Press 1 or 2:", 0xFFFFFF)
        -- Wait for keypress
        while true do
          local sig, _, char = computer.pullSignal(60)
          if sig == "key_down" then
            if char == 49 then  -- "1"
              -- Run install.lua if available on the floppy
              if bootFS.exists("/install.lua") then
                -- Load and execute install.lua, passing the floppy's bootFS
                g2.fill(1, 1, sw, sh, " ")
                gp(2, "Starting installer...", 0x00AAFF)
                -- install.lua needs OpenOS require which we don't have
                -- yet. Instead of loading it here (the source is never
                -- actually executed — the old code read ~17 KB into a
                -- buffer and then threw it away), we copy the TOS tree
                -- directly to the target disk and chain-load from there.
                g2.fill(1, 1, sw, sh, " ")
                gp(2, "Copying TOS to hard drive...", 0x00AAFF)
                local y2 = 4
                local copied2 = 0
                -- Recursive copy from floppy to target disk.
                -- #107 — previously this silently ignored write failures,
                -- truncated reads, and partial files. We now surface the
                -- first failure up to the caller so the installer can
                -- refuse to flash the BIOS when the copy didn't complete.
                local copyFailed = nil
                -- Fail FAST on space (#REV review finding #5): sum the
                -- source tree before copying instead of half-copying and
                -- then failing verification.
                local function treeSize(srcFS, dir)
                  local total = 0
                  local iter = srcFS.list(dir)
                  if not iter then return total end
                  for _, name in ipairs(iter) do
                    local p = dir .. name
                    if srcFS.isDirectory(p) then
                      total = total + treeSize(srcFS, p)
                    else
                      total = total + (srcFS.size(p) or 0)
                    end
                  end
                  return total
                end
                local function copyDir(srcFS, dstFS, dir)
                  if copyFailed then return end
                  local iter = srcFS.list(dir)
                  if not iter then return end
                  for _, name in ipairs(iter) do
                    if copyFailed then return end
                    local srcPath = dir .. name
                    if srcFS.isDirectory(srcPath) then
                      dstFS.makeDirectory(srcPath)
                      copyDir(srcFS, dstFS, srcPath)
                    else
                      local fh = srcFS.open(srcPath, "r")
                      if not fh then
                        copyFailed = "open-src " .. srcPath; return
                      end
                      local wh = dstFS.open(srcPath, "w")
                      if not wh then
                        srcFS.close(fh)
                        copyFailed = "open-dst " .. srcPath; return
                      end
                      -- Stream chunk-by-chunk (#REV finding #5): the old
                      -- whole-file write buffered everything in RAM and a
                      -- mid-file out-of-space surfaced only at the end —
                      -- and its `wOk == false` check let a nil-shaped
                      -- write failure through as success. `not wOk`
                      -- catches both failure shapes at the failing chunk.
                      while true do
                        local chunk = srcFS.read(fh, 4096)
                        if not chunk then break end
                        local wOk, wErr = dstFS.write(wh, chunk)
                        if not wOk then
                          copyFailed = "write " .. srcPath .. ": " .. tostring(wErr)
                          break
                        end
                      end
                      srcFS.close(fh)
                      dstFS.close(wh)
                      if copyFailed then return end
                      copied2 = copied2 + 1
                    end
                  end
                end
                -- Space fail-fast: refuse before the first write, not
                -- after a half-copy fails verification. (+8KB slack for
                -- directory/metadata overhead.)
                local needed = treeSize(bootFS, "/") + 8192
                local dstFree = (largerDisk.spaceTotal() or 0)
                  - (largerDisk.spaceUsed() or 0)
                if dstFree < needed then
                  gp(y2, "Target too full: need " .. math.floor(needed / 1024)
                    .. "KB, only " .. math.floor(dstFree / 1024) .. "KB free", 0xFF0000)
                  y2 = y2 + 1
                  gp(y2, "Nothing was written. Free up the disk and retry.", 0xFFAA00)
                  while true do local ev = computer.pullSignal(1e9)
                    if ev == "key_down" then computer.shutdown(true) end
                  end
                end
                -- Create core directories on target
                local coreDirs = {
                  "/tos/", "/tos/kernel/", "/tos/kernel/net/", "/tos/shell/",
                  "/tos/compat/", "/tos/peripheral/",
                  "/etc/", "/etc/rc.d/", "/home/", "/root/", "/public/",
                  "/usr/", "/usr/bin/", "/usr/lib/", "/usr/modules/",
                  "/var/", "/var/log/", "/var/run/", "/tmp/",
                }
                for _, d in ipairs(coreDirs) do
                  largerDisk.makeDirectory(d)
                end
                copyDir(bootFS, largerDisk, "/")
                if copyFailed then
                  gp(y2, "Copy FAILED: " .. copyFailed, 0xFF0000)
                  y2 = y2 + 1
                  gp(y2, "BIOS not updated. Remove disk to try again.", 0xFFAA00)
                  while true do local ev = computer.pullSignal(1e9)
                    if ev == "key_down" then computer.shutdown(true) end
                  end
                end
                gp(y2, "Copied " .. copied2 .. " files", 0x00FF00)
                y2 = y2 + 1
                -- #107 — verify critical boot files before flashing BIOS.
                -- If the copy truncated mid-file, the machine would otherwise
                -- brick on next boot.
                local ok1 = largerDisk.exists("/init.lua")
                local ok2 = largerDisk.exists("/tos/kernel/init.lua")
                local sz1 = ok1 and largerDisk.size("/init.lua") or 0
                local sz2 = ok2 and largerDisk.size("/tos/kernel/init.lua") or 0
                if not (ok1 and ok2 and sz1 > 0 and sz2 > 0) then
                  gp(y2, "Verification FAILED — BIOS not updated", 0xFF0000)
                  y2 = y2 + 1
                  gp(y2, "  init.lua=" .. tostring(sz1) .. " kernel=" .. tostring(sz2), 0xFF6600)
                  while true do local ev = computer.pullSignal(1e9)
                    if ev == "key_down" then computer.shutdown(true) end
                  end
                end
                -- #SEC H2 — require an explicit second confirmation
                -- before re-flashing the EEPROM. Auto-setBootAddress
                -- was the audit's main floppy-bootkit lever: any floppy
                -- left in the drive could silently permanently rebind
                -- the boot device. Operator must type Y now; otherwise
                -- the install stays on disk but the EEPROM still points
                -- at the floppy and the operator can reboot with the
                -- floppy removed to switch drives manually.
                gp(y2, "Files copied. Update EEPROM to boot from hard drive?", 0xFFAA00)
                y2 = y2 + 1
                gp(y2, "  [Y] update EEPROM   [N] leave EEPROM alone", 0xAAAAAA)
                y2 = y2 + 1
                gp(y2, "  Target: " .. (largerDisk.address or "?"):sub(1, 12) .. "...", 0xAAAAAA)
                y2 = y2 + 1
                local doFlash = false
                local t0 = computer.uptime()
                while computer.uptime() - t0 < 30 do
                  local s3, _, ch3 = computer.pullSignal(30)
                  if s3 == "key_down" then
                    if ch3 == 121 or ch3 == 89 then doFlash = true end
                    break
                  end
                end
                if doFlash then
                  gp(y2, "Setting boot drive...", 0x00AAFF)
                  computer.setBootAddress(largerDisk.address)
                  y2 = y2 + 1
                else
                  gp(y2, "EEPROM unchanged — remove floppy and reboot to use HD", 0xFFAA00)
                  y2 = y2 + 1
                end
                gp(y2, "", 0xFFFFFF)
                y2 = y2 + 1
                gp(y2, "TOS installed to hard drive!", 0x00FF00)
                y2 = y2 + 1
                gp(y2, "Rebooting in 3 seconds...", 0xAAAAAA)
                computer.pullSignal(3)
                computer.shutdown(true)
              else
                gp(10, "install.lua not found on floppy!", 0xFF0000)
                gp(11, "Booting from floppy instead...", 0xAAAAAA)
                computer.pullSignal(2)
              end
              break
            elseif char == 50 then  -- "2"
              break  -- Continue booting from floppy
            elseif char == 51 and canOverlay then  -- "3"
              _G._TOS_OVERLAY_DISK = largerDisk.address
              break
            end
          elseif not sig then
            break  -- Timeout: continue booting from floppy
          end
        end
      end
    end
  end
end

-- ============================================================
-- Global TOS state
-- ============================================================
_G._TOS = {
  version    = "1.5.0",
  codename   = "Aletheia",
  -- Which tree this is. The release build (build/strip.lua) rewrites both
  -- placeholders: build = the commit it was built from ("-dirty" if the
  -- source had uncommitted changes), variant = how it was stripped. Run
  -- from source, they stay "source". Must appear exactly once each.
  build      = "source",
  variant    = "source",
  bootFS     = bootFS,
  -- #REV (#8) — the boot filesystem's component address. The
  -- auto-mount gate (kernel.diskmount, #SEC H26) refuses to mount
  -- anything until this is set (fail-closed so an inserted disk can't
  -- shadow the boot FS). It was NEVER set, so EVERY inserted floppy was
  -- silently refused ("inserting a disk does nothing"). Set it here from
  -- the boot proxy so removable-media auto-mount works.
  bootAddr   = bootFS and bootFS.address or nil,
  bootTime   = computer.uptime(),
  startMem   = computer.freeMemory(),
  totalMem   = computer.totalMemory(),
}

-- ============================================================
-- Stage 1: Build require() system
-- ============================================================
local loaded = {}
local loading = {}
-- Which file each module was read from (package.loadedFrom). pkg uses it to
-- forget exactly the modules whose files it removes, and never a name on
-- its own: a built-in such as `computer` has no file here, so no package
-- file can make it be dropped.
local loadedFrom = {}

-- Kernel /tos first so a package can never shadow a kernel module by name;
-- user-installed roots after it, in the order pkg uses them.
--
-- /usr/modules MUST be here: kernel.sandbox's USER_LIB_ROOTS already lists
-- it as a place package code may require from, and its resolver checks the
-- file exists there before handing off to THIS require. Without the entry
-- the two disagreed — the sandbox authorized the require, then the load
-- failed with "Module not found" (emulator round: a package with a
-- multi-file module under /usr/modules, e.g. `calc` requiring calc.sheet,
-- could not start at all). Single-file packages never noticed because pkg
-- loads a command's entry by absolute PATH, not by module name.
-- test_require_roots pins the two lists together.
--! #SEC (pentest, Sep 2026) — /usr/bin is NOT a library root. It held
--! package COMMAND files, which pkg runs by path inside the package's
--! sandbox; on this list the same file was also a module this require
--! loads into the kernel's own _G. The shell pcall-requires add-on names
--! in kernel context (`require("mail")`), so any package shipping a
--! command called mail.lua ran it unsandboxed at the next `mail`. The
--! sandbox's USER_LIB_ROOTS never listed /usr/bin, so nothing sandboxed
--! lost anything. test_pkg_protected_targets pins this.
--! /lib is NOT searched. TOS installs nothing there; on a disk that ran
--! OpenOS it holds OpenOS's libraries, and searched AHEAD of /usr/lib they
--! answered names in the kernel's own _G: an add-on library of the same
--! name was shadowed, and in Safe Mode -- compat off, so the shim names
--! fall through to this list -- `require("term")` loaded OpenOS's real
--! /lib/term.lua, the code Safe Mode exists not to run. Sandboxed programs
--! could never reach /lib (sandbox USER_LIB_ROOTS). (test_require_roots)
local searchPaths = {
  "/tos/?.lua",
  "/tos/?/init.lua",
  "/usr/lib/?.lua",
  "/usr/modules/?.lua",
  "/usr/modules/?/init.lua",
}

-- Package compat: loaded table accessible as package.loaded
-- (needed by compat/init.lua to register OpenOS shims)
_G.package = { loaded = nil }  -- Set after loaded table creation

local function readFile(path)
  if not bootFS.exists(path) then return nil end
  local h = bootFS.open(path, "r")
  if not h then return nil end

  local parts = {}
  while true do
    local chunk = bootFS.read(h, 4096)
    if not chunk then break end
    parts[#parts + 1] = chunk
  end
  bootFS.close(h)
  return table.concat(parts)
end

-- #MEM — compile a module without ever holding TWO full copies of it.
-- The original path built a table of 4KB chunks, table.concat'd them into
-- one string, and load()ed that: source-in-pieces + joined copy + compiled
-- chunk all live at once (~2x the file plus the chunk). On low-RAM boxes
-- that peak was the "not enough memory for buffer allocation" shell-load
-- crash. We drop the joined copy by feeding load() from the chunk table and
-- releasing each piece as it is consumed.
--
-- #BUG (emulator round, 2026-07-24) — the reader must NOT touch the
-- filesystem. An earlier version read 4KB per reader call, which is the
-- textbook streaming form and would have kept the peak at one chunk; in
-- OpenComputers it panics the kernel outright:
--
--   Syntax error in 'kernel': attempt to yield across a C-call boundary
--
-- Component calls can YIELD — OC gives each machine a direct-call budget
-- and forces a yield when it runs out — and load() is a C function, so a
-- yield inside its reader crosses a C-call boundary and is fatal. It is not
-- RAM-dependent or intermittent: it killed boot on every machine. So do all
-- I/O FIRST (yielding there is fine, it's ordinary Lua), then compile from
-- memory, where the reader can only do table lookups.
--
-- Returns (found, fn, err, mode): found=false → no such file, keep
-- searching; found=true with fn=nil → the file exists but could not be
-- turned into a chunk, with `mode` saying which half failed ("read" or
-- "compile"). The caller words the error from that: reporting a failed
-- READ as a syntax error is how this very bug wasted diagnosis time — the
-- boot panic read "Syntax error in 'kernel'" when the file was fine and
-- the real fault was a yield during loading.
local function loadModuleFile(path)
  if not bootFS.exists(path) then return false end
  local h = bootFS.open(path, "r")
  if not h then return false end
  local chunks, n = {}, 0
  local readOk, readErr = pcall(function()
    while true do
      local chunk = bootFS.read(h, 4096)
      if chunk == nil then break end
      -- Lua treats "" from a reader as end-of-chunk, so a short read must
      -- never reach load() — it would compile a silent PREFIX of the module.
      if #chunk > 0 then n = n + 1; chunks[n] = chunk end
    end
  end)
  bootFS.close(h)
  if not readOk then return true, nil, readErr, "read" end
  -- Force text-only mode ("t"). Bytecode (mode "b" or "bt") is accepted
  -- by load() if bit5.band was ever compiled in, and loading
  -- attacker-crafted bytecode bypasses all Lua validity checks
  -- (arbitrary memory access, type-confusion, etc). Only source
  -- text may enter the kernel boot path.
  local i = 0
  local okL, fn, err = pcall(load, function()
    i = i + 1
    local c = chunks[i]
    chunks[i] = nil   -- release as we go; source frees while compiling
    return c          -- nil past the end ends the chunk
  end, "=" .. path, "t")
  if not okL then return true, nil, fn, "compile" end  -- compile RAISED (e.g. OOM)
  return true, fn, err, "compile"
end

-- The words for a module that exists but could not be made into a chunk.
-- A compile that ran out of memory is not a syntax error, and calling it
-- one sends people hunting for a typo in a file that is fine: on a 1 MB
-- machine `pkg` said "Syntax error in 'kernel.pkg' (...): not enough
-- memory". (test_module_load_errors.lua)
local function loadErrorText(name, path, err, mode)   --[[TEST-EXTRACT]]
  local why = tostring(err)
  if mode == "read" then
    return "Read error in '" .. name .. "' (" .. path .. "): " .. why
  end
  if why:find("not enough memory", 1, true) then
    -- Lua's own words stay on the end: the shell's error explainer and
    -- `why` recognise "not enough memory" (ERR_OUT_OF_MEMORY).
    return "Out of memory loading '" .. name .. "' (" .. path .. "): " .. why
  end
  return "Syntax error in '" .. name .. "' (" .. path .. "): " .. why
end                                                    --[[/TEST-EXTRACT]]

-- OpenOS library names served by the compat layer (tos/compat/init.lua).
-- The layer used to be loaded whole at boot; now it loads on the FIRST
-- require() of one of these names (see the fallback in tosRequireBody).
-- Checked BEFORE the search paths so precedence matches the old behavior,
-- where compat pre-registered these names in the require cache at boot
-- (e.g. a /usr/lib/text.lua add-on must not shadow the OpenOS shim).
--! MUST list every name compat.init registers, or that name's first
--! require falls past this hook into the search path.
--!
--! `internet` was missing. compat.init registers it, but nothing here
--! triggered on it, so require("internet") went to the path search and
--! found OpenOS's /lib/internet.lua -- TOS quietly running OpenOS's
--! library instead of its own shim. Worse, it was ORDER-DEPENDENT: touch
--! any other shim name first and compat is already initialized, so
--! package.loaded has "internet" and it resolves correctly. Touch
--! `internet` first, on a disk with no OpenOS underneath it, and the
--! require fails outright.
--!
--! Two lists that have to agree, with nothing checking. Now checked:
--! test_openos_compat.lua compares them and fails on any divergence.
local OPENOS_SHIMS = {
  sides = true, colors = true, keyboard = true, text = true,
  serialization = true, buffer = true, term = true, filesystem = true,
  event = true, shell = true, io = true, internet = true,
  robot = true, process = true, note = true,
}

local function tosRequireBody(name)
  -- Lazy OpenOS compat: first touch of a shim name loads + initializes the
  -- whole layer (the shims cross-register each other, so per-module lazy
  -- loading isn't meaningful). The kernel sets _TOS.compatDisabled when the
  -- boot profile gates compat off — honor it so Safe Mode still refuses to
  -- run OpenOS code, exactly as when the layer wasn't loaded at boot.
  if OPENOS_SHIMS[name] and not loaded[name] then
    local T = _G._TOS
    if not (T and T.compatDisabled) then
      -- _G.require is tosRequire (assigned right after these definitions);
      -- called through the global because tosRequire's local isn't in
      -- scope yet at this point in the file.
      local okC, compatMod = pcall(_G.require, "compat")
      if okC and compatMod and compatMod.init then
        pcall(compatMod.init, { procSleep = T and T.proc and T.proc.sleep })
      end
      if loaded[name] then return loaded[name] end
    end
  end

  local modName = name:gsub("%.", "/")
  local tried = {}
  for _, pattern in ipairs(searchPaths) do
    local path = pattern:gsub("%?", modName)
    local found, fn, err, mode = loadModuleFile(path)
    if found then
      if not fn then
        error(loadErrorText(name, path, err, mode), 2)
      end
      local ok, result = pcall(fn, name)
      if not ok then
        error("Runtime error in '" .. name .. "': " .. tostring(result), 2)
      end
      if result == nil then result = true end
      loaded[name] = result
      loadedFrom[name] = path
      return result
    end
    tried[#tried + 1] = path
  end
  error("Module not found: " .. name .. "\nSearched:\n  " .. table.concat(tried, "\n  "), 2)
end

local function tosRequire(name)
  if loaded[name] then return loaded[name] end
  if loading[name] then
    error("Circular dependency: " .. name, 2)
  end
  loading[name] = true
  -- #REV (v1.4.0 emulator round) — the body can RAISE from places the
  -- old inline code didn't guard: on a low-RAM box, bootFS.read inside
  -- readFile (or load() itself) propagates "not enough memory" BEFORE
  -- any of the explicit `loading[name] = nil` lines ran. The marker
  -- then stayed set, so the shell's OOM-nudge-GC-and-retry hit a bogus
  -- "Circular dependency: shell.panels.commands.core" — which the
  -- command loader rightly treats as a permanent code error and caches,
  -- walling off every core command for the session. Run the body under
  -- pcall and ALWAYS clear the marker, so a transient failure stays
  -- transient and "Circular dependency" again means only actual cycles.
  local ok, result = pcall(tosRequireBody, name)
  loading[name] = nil
  if not ok then error(result, 0) end
  return result
end

_G.require = tosRequire

-- Pre-register machine globals as modules so require("computer") etc. works
loaded["component"] = component
loaded["computer"] = computer
if unicode then loaded["unicode"] = unicode end

-- Expose loaded table as package.loaded for OpenOS compat
_G.package.loaded = loaded
_G.package.loadedFrom = loadedFrom

-- ============================================================
-- Stage 1a: a copy-on-write root
-- ============================================================
--! Here, before anything below reads or writes the disk, so that every layer
--! above sees one root. A machine with no overlay does one exists(). The loader
--! is the raw disk's until this runs, so cowfs itself never comes from the layer.
if _G._TOS_OVERLAY_DISK or bootFS.exists("/etc/overlay.cfg") then
  local okC, cowfs = pcall(require, "kernel.cowfs")
  local okB, root, state
  if okC then okB, root, state = pcall(cowfs.boot, bootFS, _G._TOS_OVERLAY_DISK, component.proxy) end
  if okB then
    _G._TOS.overlay = state
    if root then
      bootFS, _G._TOS.bootFS = root, root
      _G._TOS_ROOT_READONLY = false
    end
  else
    _G._TOS.overlay = { missing = _G._TOS_OVERLAY_DISK or "?",
                        why = tostring(okC and root or cowfs) }
  end
end

-- ============================================================
-- Stage 1b: Boot configuration (the everything → nothing spectrum)
-- ============================================================
-- Read VERY early and FAIL-SAFE: a missing/corrupt /etc/boot.cfg yields the
-- 'normal' profile so boot always proceeds. Drives the verbosity "muter",
-- the System Configuration POST screen, and the optional-stage gates (#4).
local bootcfgMod, bootCfg, verbosity
do
  local okB, m = pcall(require, "kernel.bootcfg")
  if okB and m then
    bootcfgMod = m
    local ok2, cfg = pcall(m.load, {
      exists   = function(p) return bootFS.exists(p) end,
      readFile = function(p) return readFile(p) end,
    })
    bootCfg = ok2 and cfg or nil
  end
  verbosity = (bootcfgMod and bootCfg) and bootcfgMod.verbosity(bootCfg) or "text"
  _G._TOS.bootcfg    = bootCfg
  _G._TOS.bootcfgMod = bootcfgMod
end
-- Verbosity → log early-echo threshold (DEBUG=0 … FATAL=4). Canonical mapping
-- lives in kernel.bootcfg (single source of truth, unit-tested); fall back to
-- a local copy if bootcfg didn't load.
local earlyMinLevel
if bootcfgMod and bootcfgMod.echoMinLevel then
  earlyMinLevel = bootcfgMod.echoMinLevel(verbosity)
else
  earlyMinLevel = ({ silent = 4, splash = 2, text = 1, verbose = 0 })[verbosity] or 1
end

-- ============================================================
-- Stage 2: GPU + Early Display
-- ============================================================
local gpuAddr
for addr in component.list("gpu") do gpuAddr = addr break end
local screenAddr
for addr in component.list("screen") do screenAddr = addr break end
local gpu

if gpuAddr and screenAddr then
  gpu = component.proxy(gpuAddr)
  -- Skip bind() if TOS BIOS already did it: gpu.bind() resets the GPU buffer
  -- (clears screen) in OC even when re-binding the same screen.
  if not _G._BIOS_CY then
    gpu.bind(screenAddr)
  end
  _G._TOS.gpu = gpu
end

local screenW, screenH = 50, 16
if gpu then
  screenW, screenH = gpu.getResolution()
end

-- Detect GPU color depth for tier-safe rendering
local gpuDepth = _G._BIOS_DEPTH or 1
if gpu then
  local ok, d = pcall(gpu.getDepth)
  if ok and d then gpuDepth = d end
end
local isMonochrome = gpuDepth <= 1

--- Map a color to a tier-safe value (T1 → white only)
local function tc(color)
  if isMonochrome then return 0xFFFFFF end
  return color
end

local cursorY = 1

-- Boot reference time for the verbose timing prefix. _G._TOS.bootTime was
-- captured at the top of this file; fall back to "now" if it's missing.
local bootT0 = (_G._TOS and _G._TOS.bootTime) or computer.uptime()

local function earlyPrint(text, color)
  if not gpu then return end
  text = tostring(text)
  -- "verbose" promises timings (see kernel.bootcfg's VERBOSITY note): on a
  -- verbose boot, stamp every early line with ms-since-boot so verbose is
  -- visibly distinct from text instead of identical to it.
  if verbosity == "verbose" then
    local ms = math.floor((computer.uptime() - bootT0) * 1000)
    text = string.format("[%6dms] %s", ms, text)
  end
  if color then gpu.setForeground(tc(color)) end
  if cursorY > screenH then
    gpu.copy(1, 2, screenW, screenH - 1, 0, -1)
    cursorY = screenH
  end
  -- Clear full line then write text (prevents remnant chars from longer lines)
  gpu.fill(1, cursorY, screenW, 1, " ")
  gpu.set(1, cursorY, text)
  cursorY = cursorY + 1
end

local function earlyClear()
  if not gpu then return end
  gpu.setBackground(0x000000)
  gpu.setForeground(tc(0x00FF00))
  gpu.fill(1, 1, screenW, screenH, " ")
  cursorY = 1
end

-- Splash composition helper: on a "splash" boot the wordmark + status lines
-- + progress bar are CENTRED so the screen reads as a designed splash, not a
-- left-aligned boot log. Pads an ASCII line to the screen centre; the UTF-8
-- wordmark centres via logo.banner's width option instead (#string would
-- over-count its 3-byte block glyphs). Every other verbosity keeps the
-- classic indented log look.
local function splashPad(s)
  if verbosity ~= "splash" then return "  " .. s end
  return string.rep(" ", math.max(0, math.floor((screenW - #s) / 2))) .. s
end

-- ============================================================
-- Stage 3: Boot splash
-- ============================================================
if _G._BIOS_CY then
  cursorY = _G._BIOS_CY
  if gpu then
    gpu.setBackground(0x000000)
    gpu.setForeground(tc(0x00FF00))
  end
else
  earlyClear()
end

local totalKB = math.floor(_G._TOS.totalMem / 1024)
local freeKB  = math.floor(computer.freeMemory() / 1024)

-- The splash banner is "splash"-level output — suppressed only on a fully
-- silent boot. (Warnings below still show regardless.)
--
-- #FIX (emulator round 7) — this is a FUNCTION, not a straight-line block,
-- because the System Configuration POST screen below owns the whole screen
-- and earlyClear()s on the way out. The wordmark used to be painted once,
-- here, and then wiped: a splash boot showed a bare progress bar with no
-- branding at all (the operator: "the System Configuration screen removes
-- the logo"). The header is re-drawn after the POST screen closes so the
-- composition the splash is supposed to be actually survives to the
-- kernel hand-off.
local function drawBootHeader()
if verbosity ~= "silent" then
  -- Branded splash: the shared kernel.logo wordmark. On a "splash" boot the
  -- whole composition (wordmark, status lines, progress bar below) is
  -- CENTRED; every other verbosity keeps the left-aligned boot-log look.
  -- pcall-required with a graceful fallback to the old thin banner so a
  -- logo-load hiccup can never block boot.
  local okLogo, logo = pcall(require, "kernel.logo")
  if okLogo and logo and logo.banner then
    local bopts = { ascii = isMonochrome, compact = screenW < 34 }
    if verbosity == "splash" then bopts.width = screenW
    else bopts.indent = 2 end
    for _, ln in ipairs(logo.banner(bopts)) do
      earlyPrint(ln[1], tc((logo.COLORS and logo.COLORS[ln[2]]) or 0x00AAFF))
    end
  else
    local bar = string.rep(isMonochrome and "=" or "═", math.min(38, screenW))
    earlyPrint(bar, tc(0x00AAFF))
    earlyPrint("  TOS", tc(0x00AAFF))
    earlyPrint(bar, tc(0x00AAFF))
  end
  earlyPrint(splashPad("TOS v" .. _G._TOS.version .. " [" .. _G._TOS.codename .. "]"), tc(0x00AAFF))
  earlyPrint(splashPad("Memory: " .. freeKB .. "K free / " .. totalKB .. "K total"), tc(0xAAAAAA))
end
-- #SEC H1 — visible confirmation that the operator's Shift+Enter one-time
-- boot took effect: this session runs from the fallback drive but the EEPROM
-- was left untouched, and the floppy→HDD migration offer is suppressed.
if _G._BIOS_ONETIME then
  earlyPrint(splashPad("ONE-TIME BOOT: EEPROM unchanged, boot config preserved"), tc(0xFFAA00))
end
-- Safe Mode is LOUD on purpose: the operator must never wonder why their
-- services/packages aren't running. (A one-time safe boot chosen at the
-- POST screen prints its own notice there — this covers the saved profile.)
if bootCfg and bootCfg.profile == "safe" then
  earlyPrint(splashPad("SAFE MODE: services, cron, packages, net, themes are OFF"), tc(0xFFAA00))
  earlyPrint(splashPad("(Boot Settings -> Profile to leave Safe Mode)"), tc(0xAAAAAA))
end
if totalKB < 128 then
  earlyPrint(splashPad("WARNING: Low memory - features limited!"), tc(0xFF0000))
elseif totalKB < 256 then
  earlyPrint(splashPad("NOTE: Limited memory - some features may be skipped"), tc(0xFFFF00))
end
end   -- drawBootHeader

drawBootHeader()

--! THE WAY OUT OF A BOOT LOOP. The EEPROM boots its saved disk without
--! asking, so a disk whose install is broken was booted, refused below,
--! rebooted and booted again -- recoverable only by moving the disk to
--! another machine or reflashing from one. From this screen the operator
--! can pick another bootable disk (the TOS installer floppy, an OpenOS
--! disk) and the EEPROM is pointed at it: the same commit the BIOS's own
--! "Save it? Y" makes, chosen with two deliberate keys at the console.
--! Any other key reboots, as before. The BIOS's own halts (K4 and the
--! like) loop the same way and need the EEPROM's own escape; that is the
--! split-BIOS item, not this. Returns the address chosen, or nil.
--! (test_boot_elsewhere.lua)
local function bootElsewhere(comp, skip, say, pull, setBoot)   --[[TEST-EXTRACT]]
  -- Only a real key: component and network signals would otherwise act
  -- for the operator (#118/#99/#101).
  local function key()
    while true do
      local ev, _, ch = pull()
      if ev == "key_down" then return tonumber(ch) or 0 end
    end
  end
  if type(setBoot) ~= "function" then
    say("Press any key to reboot...")
    key()
    return nil
  end
  -- What the BIOS can boot: a filesystem with an /init.lua, or a raw
  -- drive carrying a TBFS superblock. Never the disk that just failed.
  local function scan()
    local out = {}
    local function add(addr, px)
      local okL, lbl = pcall(px.getLabel)
      out[#out + 1] = { addr = addr, label = (okL and type(lbl) == "string") and lbl or "" }
    end
    for addr in comp.list("filesystem") do
      if not skip[addr] then
        local okP, px = pcall(comp.proxy, addr)
        if okP and px then
          local okE, has = pcall(px.exists, "/init.lua")
          if okE and has then add(addr, px) end
        end
      end
    end
    for addr in comp.list("drive", true) do
      if not skip[addr] then
        local okP, px = pcall(comp.proxy, addr)
        if okP and px and px.readSector then
          local okS, sec = pcall(px.readSector, 1)
          if okS and type(sec) == "string" and sec:sub(1, 4) == "TBFS" then add(addr, px) end
        end
      end
    end
    return out
  end
  say("Any key reboots. B: boot another disk instead.")
  local ch = key()
  while ch == 66 or ch == 98 do                    -- B / b
    local disks = scan()
    if #disks == 0 then
      say("No other bootable disk. Insert one (the TOS")
      say("installer floppy will do), then press B.")
    else
      for i = 1, math.min(#disks, 9) do
        say(" " .. i .. ") " .. disks[i].addr:sub(1, 8) .. " " .. disks[i].label:sub(1, 30))
      end
      say("Its number boots it from now on. B rescans.")
    end
    say("Any other key reboots.")
    ch = key()
    local n = ch - 48
    if n >= 1 and n <= 9 and disks[n] then
      setBoot(disks[n].addr)
      say("Boot disk set to " .. disks[n].addr:sub(1, 8) .. ". Rebooting.")
      return disks[n].addr
    end
  end
  return nil
end                                                              --[[/TEST-EXTRACT]]

--! The way to another disk, as the menu and the failure screen both use it.
--! Whatever is chosen, this ends in a reboot.
local function otherDisk()
  local skip = {}
  if bootFS.address then skip[bootFS.address] = true end
  if _G._TBFS_BOOT_DRIVE then skip[_G._TBFS_BOOT_DRIVE] = true end
  pcall(function() skip[computer.tmpAddress()] = true end)
  pcall(bootElsewhere, component, skip,
    function(t) earlyPrint(t, tc(0xAAAAAA)) end,
    function() return computer.pullSignal(math.huge) end,
    computer.setBootAddress)
  computer.shutdown(true)
end

--! The recovery menu (kernel/recovery.lua). Returns its action, or nil when
--! it could not run, and the caller then does what it did before the menu
--! existed. Nothing in here is allowed to stop a boot.
local function runRecovery(failed, why)
  if not gpu then return nil end
  local okR, rec = pcall(require, "kernel.recovery")
  if not okR or type(rec) ~= "table" then return nil end
  local roles = { title = 0x00FFFF, value = 0xFFFFFF, dim = 0xAAAAAA,
    ok = 0x00FF00, warn = 0xFFAA00 }
  local okM, action = pcall(rec.run, {
    W = screenW, H = screenH, px = bootFS, component = component,
    failed = failed, why = why, otherDisk = otherDisk,
    clear = earlyClear,
    color = function(role) return tc(roles[role] or 0xFFFFFF) end,
    set = function(x, y, text, fg)
      gpu.setForeground(fg or 0xFFFFFF)
      gpu.set(x, y, text)
    end,
    tick = function() computer.pullSignal(0) end,
    readKey = function()
      while true do
        local e, _, ch, code = computer.pullSignal(math.huge)
        if e == "key_down" then return e, ch, code end
      end
    end,
  })
  if not okM then
    earlyClear()
    earlyPrint("Recovery stopped: " .. tostring(action), tc(0xFF6600))
    return nil
  end
  if action == "reboot" then computer.shutdown(true) end
  if action == "off" then computer.shutdown(false) end
  return action
end

-- ── System Configuration POST screen + DEL-to-setup (#3/#5) ──
-- Shown briefly when showConfig is on (default) — the TOS-ified AMIBIOS
-- screen: installed hardware + tiers. Press DEL during the window to enter
-- Boot Settings; any other key skips ahead. Fully guarded so a detection
-- hiccup or setup error never blocks boot.
--
-- showConfig — NOT verbosity — gates this screen. The old code also
-- required verbosity ~= "silent", which meant a silent boot hid the only
-- DEL-to-setup entry point: an operator who set "silent" could no longer
-- reach Boot Settings at all (recoverable only via the shell `bootsettings`
-- command, if they could still log in). verbosity is the boot-LOG muter;
-- showConfig is the master switch for this interactive screen. For a truly
-- silent boot, turn showConfig off as well.
-- showConfig is the master switch for this screen; a "verbose" boot ALSO
-- forces it, since the bootcfg contract lists "the hardware table" as part of
-- verbose (and a diagnostic boot should show diagnostics). Either trigger,
-- plus a GPU, opens it.
if ((bootCfg and bootCfg.showConfig) or verbosity == "verbose") and gpu then
  pcall(function()
    local sysinfo = require("kernel.sysinfo")
    -- Shared palette + GPU draw primitives (raw GPU; pre-kernel).
    local function postColor(role)
      local map = {
        bg = 0x000000, border = tc(0x00AAFF), title = tc(0x00FFFF),
        dim = tc(0xAAAAAA), value = tc(0xFFFFFF), ok = tc(0x00FF00),
        warn = tc(0xFFAA00), section = tc(0x00FFFF),
      }
      return map[role] or tc(0xFFFFFF)
    end
    local function gset(x, y, text, fgc, bgc)
      if bgc then gpu.setBackground(bgc) end
      gpu.setForeground(fgc or 0xFFFFFF)
      gpu.set(x, y, text)
    end

    -- Pass BOTH operator tier overrides so the POST screen honours a manually
    -- set Data Card tier (Boot Settings) instead of reporting "unknown tier".
    local inv = sysinfo.gather(nil,
      { cpuTier = bootCfg.cpuTier, dataTier = bootCfg.dataTier },
      function(msg) earlyPrint("  Standby - " .. msg .. "...", tc(0xAAAAAA)) end)
    earlyClear()
    -- Title line. sysinfo.render lays the screen out as a rigid two-column
    -- config table showing only REAL hardware (no PC-BIOS flavor). Vendor
    -- comes from kernel.logo (one source of truth); render clips to the screen.
    local cfgTitle = "TOS System Configuration"
    if screenW >= 60 then
      local okLogo, logo = pcall(require, "kernel.logo")
      if okLogo and logo and logo.VENDOR then
        cfgTitle = logo.VENDOR .. "  -  System Configuration"
      end
    end
    local after = sysinfo.render(inv, { W = screenW, H = screenH, color = postColor,
      set = gset, title = cfgTitle })
    gset(2, math.min(screenH, (after or screenH) + 1),
      "DEL Boot Settings, S Safe Mode (once), R Recovery...", tc(0xFFAA00))

    -- Wait up to 3s for a key. DEL (code 211) opens setup; S boots Safe
    -- Mode for THIS session only (config untouched — the operator's way
    -- to get a trustworthy shell after installing something that breaks
    -- boot, without editing anything first); R opens the recovery menu;
    -- any other key skips ahead; non-key signals are ignored until the
    -- deadline.
    local enterSetup = false
    local safeOnce = false
    local recover = false
    local deadline = computer.uptime() + 3
    while computer.uptime() < deadline do
      local ev, _, ch, code = computer.pullSignal(deadline - computer.uptime())
      if ev == "key_down" then
        if code == 211 then enterSetup = true
        elseif ch == 115 or ch == 83 then safeOnce = true
        elseif ch == 114 or ch == 82 then recover = true end
        break
      end
    end
    if recover then
      local action = runRecovery(false)
      if action == "safe" then safeOnce = true
      elseif action == "settings" then enterSetup = true end
    end
    earlyClear()
    -- The POST screen owned the whole display; put the branded header back
    -- so the rest of the boot (verify / load / progress bar) composes with
    -- it instead of floating on a blank screen.
    drawBootHeader()
    if safeOnce and bootCfg then
      bootCfg.profile = "safe"          -- in-memory only; NOT saved
      earlyPrint("  SAFE MODE (one-time): services, cron, packages, net, themes OFF",
        tc(0xFFAA00))
      earlyPrint("  Boot config untouched - the next boot is normal.", tc(0xAAAAAA))
    end

    if enterSetup then
      local okBS, bootsettings = pcall(require, "kernel.bootsettings")
      if okBS and bootsettings then
        local ctx = {
          W = screenW, H = screenH, color = postColor, set = gset,
          sysinfo = sysinfo, clear = earlyClear,
          readKey = function()
            while true do
              local e, _, ch, code = computer.pullSignal()
              if e == "key_down" then return e, ch, code end
            end
          end,
        }
        local action, newCfg = bootsettings.run(bootCfg, ctx)
        if action == "save" or action == "reboot" then
          local cfgFS = {
            exists   = function(p) return bootFS.exists(p) end,
            readFile = readFile,
            writeFile = function(p, d)
              if not bootFS.exists("/etc") then pcall(bootFS.makeDirectory, "/etc") end
              local h = bootFS.open(p, "w"); if not h then return false end
              bootFS.write(h, d); bootFS.close(h); return true
            end,
          }
          pcall(function() require("kernel.bootcfg").save(cfgFS, newCfg) end)
          earlyClear()
          if action == "reboot" then
            gset(2, 2, "Saved. Rebooting to apply...", tc(0x00FF00))
            computer.pullSignal(1)
            computer.shutdown(true)
          else
            gset(2, 2, "Saved. Changes apply on next boot. Continuing...", tc(0x00FF00))
            computer.pullSignal(1)
            earlyClear()
            drawBootHeader()   -- Boot Settings owned the screen too
          end
        end
      end
    end
  end)
end

-- ============================================================
-- Stage 4: Verify & load kernel
-- ============================================================
-- Boot-critical file list resolution. Three layers, tried in order:
--
--   1. /var/pkg/installed/tos-core/package.lua
--        Primary source post-migration (commit 3). The kernel pkg
--        manager keeps this in sync with the source tree on every
--        install/uninstall.
--
--   2. /etc/critical.bak
--        Mirror written by pkg.syncCriticalBackup() after every
--        critical-set change. Lives under a different parent so
--        griefing or corruption that takes out /var/pkg/ doesn't
--        also wipe the backup.
--
--   3. /tos/system_manifest.lua  (legacy)
--        The pre-pkg-manager source of truth. Still consulted in
--        commit 1; will be deleted in commit 3 once tos-core is the
--        canonical home.
--
--   4. Hardcoded minimal list
--        Last resort if every on-disk source is missing or corrupt.
--        Just enough files to detect a totally borked install.
--
-- Anything that returns a non-empty list wins; later layers are skipped.

-- Read a file via bootFS into a single string. Used by all three
-- on-disk layers below; bootFS doesn't yet have helpers like
-- fs.readFile, so we inline the open/read/close loop.
local function bootRead(path)
  if not bootFS.exists(path) then return nil end
  local h = bootFS.open(path, "r")
  if not h then return nil end
  local parts = {}
  repeat
    local chunk = bootFS.read(h, 4096)
    if chunk then parts[#parts + 1] = chunk end
  until not chunk
  bootFS.close(h)
  return table.concat(parts)
end

-- Load + run a serialized Lua-table file in text-only mode (no
-- bytecode — see Stage 1 require for the rationale). Returns the
-- table on success, nil on parse/run failure.
local function loadTableFile(path, chunkName)
  local source = bootRead(path)
  if not source then return nil end
  local fn = load(source, "=" .. chunkName, "t")
  if not fn then return nil end
  local ok, result = pcall(fn)
  if not ok or type(result) ~= "table" then return nil end
  return result
end

local criticalFiles = {}
local criticalSource = "(none)"

-- Layer 1: tos-core's package.lua → manifest.critical
do
  local mf = loadTableFile("/var/pkg/installed/tos-core/package.lua", "tos-core/package")
  if mf and type(mf.critical) == "table" then
    for _, p in ipairs(mf.critical) do
      if type(p) == "string" then criticalFiles[#criticalFiles + 1] = p end
    end
    if #criticalFiles > 0 then criticalSource = "tos-core/package.lua" end
  end
end

-- Layer 2: /etc/critical.bak → flat array of paths
if #criticalFiles == 0 then
  local mf = loadTableFile("/etc/critical.bak", "critical.bak")
  if mf then
    for _, p in ipairs(mf) do
      if type(p) == "string" then criticalFiles[#criticalFiles + 1] = p end
    end
    if #criticalFiles > 0 then criticalSource = "critical.bak" end
  end
end

-- Layer 3: /tos/system_manifest.lua → entries with critical=true (legacy)
if #criticalFiles == 0 then
  local mf = loadTableFile("/tos/system_manifest.lua", "system_manifest")
  if mf then
    for _, entry in ipairs(mf) do
      if entry.critical and type(entry.path) == "string" then
        criticalFiles[#criticalFiles + 1] = entry.path
      end
    end
    if #criticalFiles > 0 then criticalSource = "system_manifest.lua" end
  end
end

-- Layer 4: hardcoded minimal list. Just enough to recognize that the
-- kernel itself is intact. If even these are missing the box can't
-- boot anyway, so the goal is a clear error message rather than a
-- precise list.
if #criticalFiles == 0 then
  criticalFiles = {
    "/tos/kernel/init.lua",
    "/tos/kernel/log.lua",
    "/tos/kernel/hal.lua",
    "/tos/kernel/event.lua",
    "/tos/kernel/process.lua",
    "/tos/kernel/fs.lua",
    "/tos/kernel/serialize.lua",
    "/tos/kernel/display.lua",
    "/tos/shell/init.lua",
  }
  criticalSource = "hardcoded fallback"
end
local missingFiles = {}
for _, path in ipairs(criticalFiles) do
  if not bootFS.exists(path) then
    missingFiles[#missingFiles + 1] = path
  end
end


if #missingFiles > 0 then
  earlyPrint("MISSING " .. #missingFiles .. " FILES:", tc(0xFF0000))
  for _, path in ipairs(missingFiles) do
    earlyPrint("  " .. path, tc(0xFF6600))
  end
  computer.beep(400, 0.5)
  -- The menu first: srm may hold a verified copy of what is gone, which the
  -- old screen could only reboot past. Should the menu itself be among the
  -- missing, or fail to load, this is the screen there always was.
  runRecovery(true, #missingFiles .. " system file(s) are missing.")
  otherDisk()
end

if verbosity ~= "silent" then
  earlyPrint(splashPad("Verifying: " .. (#criticalFiles - #missingFiles) .. "/" .. #criticalFiles
    .. " system files OK [" .. criticalSource .. "]"), tc(0x00FF00))
  earlyPrint(splashPad("Loading kernel..."), tc(0x00FF00))
end

-- Splash-mode boot progress bar. In "splash" verbosity the per-stage boot
-- log is muted (log.lua), so without this the screen would just sit on the
-- wordmark / "Loading kernel..." until login. Drive a simple fill bar from
-- the kernel's boot chatter so the operator sees real progress. It's nil in
-- every other mode — the bar only earns its keep when the text log is hidden.
-- (The "text" option still shows the live log for free; this is the visual
-- counterpart the operator asked for.)
local bootProgress = nil
if verbosity == "splash" and gpu then
  -- Centre the bar (and the narration column below it, which shares barX)
  -- under the centred wordmark -- the splash reads as one designed
  -- composition.
  --
  --! RECOMPUTED, never measured once. gpu.bind() above leaves the screen at
  --! its MAXIMUM, and the kernel applies the resolution policy (kernel/
  --! screen.lua, density-based, floored at 80x25) part-way through
  --! kernel.boot() -- while this bar is live, because bootProgress is the
  --! callback driving it. On a Tier 3 GPU with a multi-block screen that is
  --! a real reduction, 160x50 -> 80x25, and geometry measured beforehand
  --! put the bar at column 60 of a screen 80 wide: pushed right, running
  --! off the edge, with the wordmark above it going the same way. Tier 2
  --! (max 80x25) and a single Tier 3 block (max 50x16) never move, which is
  --! why it only ever showed on a resized Tier 3 screen.
  --! (test_splash_resize.lua)
  -- Required BEFORE geom() below, not after: a local declared under a
  -- closure is not an upvalue of it, it is a nil global read -- and geom
  -- would then silently take its fallback branch forever.
  -- pcall so a load hiccup can never block boot; we lose the narration,
  -- not the bar.
  local okSteps, bootsteps = pcall(require, "kernel.bootsteps")
  local headerBottom = cursorY
  local barRow, barW, barX, logRows, narrW
  local LOG_ROWS = 3                            -- rolling high-level narration
  local function geom()
    if okSteps and bootsteps and bootsteps.splashGeometry then
      barRow, barW, barX, logRows = bootsteps.splashGeometry(screenW, screenH, headerBottom)
    else
      barW   = math.max(10, math.min(40, screenW - 6))
      barX   = math.max(1, math.floor((screenW - (barW + 2)) / 2) + 1)
      barRow = math.max(1, math.min(screenH - 1, headerBottom + 1))
    end
    logRows = logRows or math.max(0, math.min(LOG_ROWS, screenH - barRow))
    -- Narration runs to the screen edge, not the bar's width: a warning is
    -- shown verbatim, and at barW + 2 Safe Mode's read "! Package command
    -- dispatch disabled (boot".
    narrW = screenW - barX + 1
    -- Blank the band the bar owns, edge to edge. Where it has to sit on a
    -- header row, the bar's own 42 columns would leave the ends of that row
    -- showing either side of it.
    gpu.setBackground(0x000000)
    pcall(gpu.fill, 1, barRow, screenW, logRows + 1, " ")
  end
  local stagesShown = 0                         -- distinct boot stages reached
  local stageTotal  = 16                        -- denominator (set once bootsteps loads)
  local fillCh   = isMonochrome and "#" or "█"
  local logLines = {}                           -- { {text, color}, ... } last N
  local lastStage = nil
  if okSteps and bootsteps and bootsteps.STAGE_COUNT then stageTotal = bootsteps.STAGE_COUNT end
  local function stageFor(msg)
    if okSteps and bootsteps then return bootsteps.stageFor(msg) end
    return nil
  end

  --! Has the glass changed size under us? Re-read it, and if it moved,
  --! rebuild the whole splash rather than just moving 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 to keep. Cheap enough -- one getResolution per progress
  --! message, a few dozen over a boot, and only on a splash boot.
  local function resync()
    local okR, w, h = pcall(gpu.getResolution)
    if not okR or not w or not h then return false end
    if w == screenW and h == screenH then return false end
    screenW, screenH = w, h
    earlyClear()
    cursorY = 1
    drawBootHeader()
    headerBottom = cursorY
    geom()
    cursorY = math.min(screenH, barRow + logRows + 1)
    return true
  end

  local function redraw()
    resync()
    gpu.setBackground(0x000000)
    local fill = math.floor(barW * math.min(1, stagesShown / stageTotal) + 0.5)
    gpu.setForeground(tc(0x00AAFF))
    gpu.set(barX, barRow, "[" .. string.rep(fillCh, fill)
      .. string.rep(" ", barW - fill) .. "]")
    -- The newest logRows lines, when fewer rows fit than are kept.
    local first = math.max(0, #logLines - logRows)
    for i = 1, logRows do
      local e = logLines[first + i]
      gpu.setForeground((e and e[2]) or tc(0xAAAAAA))
      gpu.set(barX, barRow + i, (((e and e[1]) or "")
        .. string.rep(" ", narrW)):sub(1, narrW))
    end
  end
  local function pushLine(text, color)
    logLines[#logLines + 1] = { text, color }
    while #logLines > LOG_ROWS do table.remove(logLines, 1) end
  end

  geom()
  redraw()
  cursorY = math.min(screenH, barRow + logRows + 1)  -- earlyPrint goes below

  bootProgress = function(msg, level)
    msg = tostring(msg or "")
    -- level: INFO=1, WARN=2, ERROR=3, FATAL=4 (kernel.log numbering).
    if level and level >= 2 then
      -- Never simplify or hide a problem — show it verbatim, coloured, so the
      -- bar can't paper over a warning/error.
      local mark = (level == 2) and "! " or "!! "
      pushLine(mark .. msg, (level == 2) and tc(0xFFAA00) or tc(0xFF4040))
    else
      local stage = stageFor(msg)
      if stage and stage ~= lastStage then
        lastStage = stage
        stagesShown = stagesShown + 1
        pushLine(stage, tc(0xAAAAAA))
      end
    end
    -- Not every boot reaches every stage (a minimal box skips networking,
    -- themes, compat…), so snap to full on the final line rather than relying
    -- on the count — the bar always lands at 100% exactly when boot completes.
    if msg:find("Boot complete", 1, true) then stagesShown = stageTotal end
    redraw()
  end
end

-- ============================================================
-- The stop screen
-- ============================================================
--! A kernel panic draws a full-screen STOP page: solid blue, white text, the
--! error's code in all three spellings (kernel/errors.lua), 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 a red
--! line at the bottom of a black boot log never did.
--!
--! The colours are per tier, and not the obvious values. OC's Tier 2 draws
--! from OC's OWN 16-entry palette, not VGA's, so VGA blue (0x0000AA) would
--! snap somewhere unpredictable; that palette's blue is 0x333399 (checked
--! against the emulator's PackedColor). Tier 1 is monochrome and has no blue
--! at all, so it gets inverse video. Only Tier 3 can draw 0x0000AA.
--!
--! This file must stay Lua 5.2-parseable (the architecture guard at the top
--! has to run on a 5.2 CPU to say so), so nothing here uses 5.3 syntax.
--! test_stop_screen.lua lifts both functions out of this file and runs them.

-- Pure: the page's lines for a W x H screen, each { text, role, prio }. On a
-- short screen the lowest priority goes first -- blank spacers, the hex, the
-- status, the traceback's tail -- and the STOP line and the error's own first
-- line go last of all.
local function stopScreenLines(info, W, H)   --[[TEST-EXTRACT]]
  local lines = {}
  local function put(text, role, prio, indent)
    local pad = string.rep(" ", indent or 2)
    local room = math.max(8, W - #pad - 1)
    text = tostring(text or "")
    if text == "" then lines[#lines + 1] = { "", role, prio }; return end
    for line in (text .. "\n"):gmatch("([^\n]*)\n") do
      repeat
        lines[#lines + 1] = { pad .. line:sub(1, room), role, prio }
        line = line:sub(room + 1)
      until line == ""
    end
  end
  put("", "body", 1)
  put("TOS has stopped to protect your data.", "title", 6)
  put("", "body", 1)
  put("*** STOP: " .. info.code .. "  " .. info.sym, "code", 9)
  put(info.hex, "dim", 2, 6)
  put("", "body", 1)
  local first = true
  for dl in (tostring(info.detail or "") .. "\n"):gmatch("([^\n]*)\n") do
    dl = dl:gsub("\t", "  ")
    if dl:find("%S") then put(dl, "body", first and 8 or 4); first = false end
  end
  put("", "body", 1)
  put("1. Reboot." .. (info.report and (" The crash report is " .. info.report) or ""), "body", 5)
  put("2. After boot: crash reads it, why " .. info.code .. " explains the code,", "body", 5)
  put("   srm repairs. If it repeats, boot another disk and run srm scan.", "body", 5)
  put("", "body", 1)
  put(info.status, "dim", 3)
  put("", "body", 1)
  put("Press any key to reboot.", "title", 7)
  while #lines > H do
    local worst, at = math.huge, nil
    for i = #lines, 1, -1 do                 -- ties: the LAST one goes first
      if lines[i][3] < worst then worst, at = lines[i][3], i end
    end
    table.remove(lines, at)
  end
  return lines
end                                           --[[/TEST-EXTRACT]]

local function drawStopScreen(g, lines, W, H, depth)   --[[TEST-EXTRACT]]
  local bg, fg, dim = 0x0000AA, 0xFFFFFF, 0xAAAAAA          -- Tier 3
  if depth <= 1 then bg, fg, dim = 0xFFFFFF, 0x000000, 0x000000
  elseif depth <= 4 then bg, fg, dim = 0x333399, 0xFFFFFF, 0xCCCCCC end
  pcall(g.setBackground, bg)
  pcall(g.setForeground, fg)
  pcall(g.fill, 1, 1, W, H, " ")
  for i = 1, math.min(#lines, H) do
    pcall(g.setForeground, (lines[i][2] == "dim") and dim or fg)
    pcall(g.set, 1, i, lines[i][1])
  end
end                                                     --[[/TEST-EXTRACT]]

local ok, err = xpcall(function()
  local kernel = require("kernel")
  kernel.boot({
    gpu          = gpu,
    gpuDepth     = gpuDepth,
    screenW      = screenW,
    screenH      = screenH,
    earlyPrint   = earlyPrint,
    bootFS       = bootFS,
    -- Boot-reorg: the spectrum config + verbosity muter (#3/#4).
    bootcfg      = bootCfg,
    bootcfgMod   = bootcfgMod,
    earlyMinLevel = earlyMinLevel,
    bootProgress = bootProgress,   -- splash-mode loading bar (nil otherwise)
  })
end, function(e)
  return tostring(e) .. "\n" .. debug.traceback("", 2)
end)

if not ok then
  local errStr = tostring(err) or "Unknown error"

  -- Which code. The literals cover the case where the registry itself is
  -- what broke; test_stop_screen.lua pins them to kernel/errors.lua.
  local STOP_FALLBACK = {
    ERR_KERNEL_PANIC  = { "E-201", "0x00020001" },
    ERR_OUT_OF_MEMORY = { "E-202", "0x00020002" },
  }
  local sym = errStr:find("not enough memory", 1, true) and "ERR_OUT_OF_MEMORY"
    or "ERR_KERNEL_PANIC"
  local code, hex = STOP_FALLBACK[sym][1], STOP_FALLBACK[sym][2]
  local okE, errors = pcall(require, "kernel.errors")
  local reg = okE and type(errors) == "table" and errors.find(sym)
  if reg then code, hex = errors.code(reg), errors.hex(reg) end
  local reason = "KERNEL PANIC [" .. code .. " " .. sym .. "]"

  -- Flight-recorder: persist the panic so the next boot can surface it and the
  -- operator can read the full trace AFTER rebooting. Prefer the kernel helper
  -- (if boot got far enough to expose it); otherwise write via the boot FS
  -- directly, since the kernel may have died before _G._TOS.kernel existed.
  local report
  pcall(function()
    local K = _G._TOS and _G._TOS.kernel
    if K and K.crashDump then
      -- crashDump falls back to raw invokes on its own. If it still saved
      -- nothing, or raised, the boot-disk write below is the last try.
      local okK, r = pcall(K.crashDump, reason, errStr)
      if okK and r then report = r; return end
    end
    if bootFS and bootFS.open then
      pcall(bootFS.makeDirectory, "/var/crash")
      local h = bootFS.open("/var/crash/crash-panic.txt", "w")
      if h then
        bootFS.write(h, "=== TOS " .. reason .. " ===\n" .. errStr
          .. "\nFree RAM: " .. math.floor(computer.freeMemory() / 1024) .. "KB\n")
        bootFS.close(h)
        report = "/var/crash/crash-panic.txt"
      end
      local hm = bootFS.open("/var/crash/NEW", "w")
      if hm then bootFS.write(hm, reason); bootFS.close(hm) end
    end
  end)

  -- The stop page. The ACTIVE buffer is reset first: a panic that lands
  -- mid-frame leaves the GPU drawing into an off-screen page, and the whole
  -- screen would then be painted where nobody can see it. The resolution is
  -- asked again because the kernel may have changed it since boot measured.
  local W, H = screenW, screenH
  if gpu then
    pcall(gpu.setActiveBuffer, 0)
    local okR, rw, rh = pcall(gpu.getResolution)
    if okR and rw and rh then W, H = rw, rh end
    local T = _G._TOS or {}
    drawStopScreen(gpu, stopScreenLines({
      code = code, sym = sym, hex = hex, detail = errStr, report = report,
      status = string.format("uptime %ds | %d KB free | TOS %s",
        math.floor(computer.uptime()), math.floor(computer.freeMemory() / 1024),
        tostring(T.version or "?")),
    }, W, H), W, H, gpuDepth)
  end
  -- Kernel panic beep code: three low beeps
  computer.beep(400, 0.15)
  computer.pullSignal(0.05)
  computer.beep(400, 0.15)
  computer.pullSignal(0.05)
  computer.beep(400, 0.15)
  -- Wait for a real key press so stray signals don't auto-reboot the
  -- operator past the panic message (#118/#99/#101).
  while true do
    local ev = computer.pullSignal(math.huge)
    if ev == "key_down" then break end
  end
  computer.shutdown(true)
end