@@ -53,13 +53,16 @@ above; otherwise it is a NOTE.
 - **Instructions.** A change that removes or renames a command, flag or step an agent runs updates
   every prompt that names it — each `CLAUDE.md` and `.claude/agents/*.md` — in the same diff,
   saying what to do instead. Such an instruction is not the prose "Prose is removed, never
-  reviewed" governs: one left naming what is gone is a BLOCKER.
+  reviewed" governs, and `CLAUDE.md`'s "Stale or false prose is deleted" and "an agent edits one
+  only when briefed to" do not bar the implementer updating it: one left naming what is gone is a
+  BLOCKER.
 - **Arrivals.** A host tool outside Rust and QEMU arrives by `Command::new`, `libc::system`,
-  `exec`, `posix_spawn`, a build script or `cc::Build`, a `.github/` package manager or `sh -c`,
-  and is declared in `issues/build/the-build-runs-c-and-cxx-tools-toyos-does-not-yet-run.md` and
-  nowhere else. A BLOCKER each: an undeclared host tool; one, like Go's `gh`, not built from C or
-  C++ source ToyOS can one day build and run; a binary for one host OS alone; a C or C++ tool
-  taken where a Rust tool does the job; new Python, Perl or shell of ToyOS's own.
+  `exec`, `posix_spawn`, a build script or `cc::Build`, a `.github/` `run:` step or package
+  manager, or `sh -c`, and is declared in
+  `issues/build/the-build-runs-host-tools-outside-rust-and-qemu.md` and nowhere else. A BLOCKER
+  each: an undeclared host tool; one, like Go's `gh`, not built from C or C++ source ToyOS can
+  one day build and run; a binary for one host OS alone; a C or C++ tool taken where a Rust tool
+  does the job; new Python, Perl or shell of ToyOS's own.
   A third-party action `main` does not use is refused, and every `uses:` pins a 40-hex commit
   with its tag in a trailing comment or names a local path that resolves.
   A file added to or deleted from `tests/testcases/tinycc/` moves the count
 
@@ -58,7 +58,7 @@ A subdirectory `CLAUDE.md` loads when a file in that subtree is `Read`, and not
 
 ## Dependencies
 
-**Rust** and **QEMU** for development, on any host OS and architecture — the development machine is nothing special. Beside them, where no Rust tool does the job, only C or C++ tools ToyOS can one day build and run (Python, Perl, CMake, Ninja, make), each declared. No binary for one host OS alone: a macOS binary is a hard no, and "only for tests" does not soften it. No Python, Perl or shell of our own; only general and widely used crates — one that does *our* job we write ourselves, and a driver crate never; third-party crates are used as published, and a fork carries a change written to upstream quality and goes when upstream has it. No upstream pull requests are sent for now: ToyOS needs more attention and more contributors before upstream projects take it seriously, and upstreams tend to refuse AI-first projects and their contributions. A third-party source ToyOS cannot build without changing it is carried as an unmodified-source packaging mirror with a byte-identity gate, not as a fork. The north star is **self-hosting**: nothing — build, test, or verification — rests on a host binary. Self-hosting means ToyOS rebuilds itself on ToyOS and reproduces the host's bytes; a bootstrap from source with no binary seed is out of scope.
+**Rust** and **QEMU** for development, on any host OS and architecture — the development machine is nothing special. Beside them, where no Rust tool does the job, only C or C++ tools ToyOS can one day build and run (Python, Perl, CMake, Ninja, make), each declared. No binary for one host OS alone: a macOS binary is a hard no, and "only for tests" does not soften it. ToyOS's own code is Rust; it writes no Python, Perl or shell of its own. Only general and widely used crates — one that does *our* job we write ourselves, and a driver crate never; third-party crates are used as published, and a fork carries a change written to upstream quality and goes when upstream has it. No upstream pull requests are sent for now: ToyOS needs more attention and more contributors before upstream projects take it seriously, and upstreams tend to refuse AI-first projects and their contributions. A third-party source ToyOS cannot build without changing it is carried as an unmodified-source packaging mirror with a byte-identity gate, not as a fork. The north star is **self-hosting**: nothing — build, test, or verification — rests on a host binary. Ask of anything new: could this ever run inside ToyOS? Self-hosting means ToyOS rebuilds itself on ToyOS and reproduces the host's bytes; a bootstrap from source with no binary seed is out of scope.
 
 Vendor firmware a device verifies by its maker's signature may be shipped: pinned by version and hash, redistributable unmodified, recorded in `NOTICE`, and loaded only by that device's own driver through its IOMMU domain; it never executes on the CPU.
 
 
@@ -4,38 +4,43 @@ kind: tooling
 opened: 2026-09-29
 ---
 
-# The build runs C and C++ tools that ToyOS does not yet build and run
+# The build runs host tools outside Rust and QEMU
 
 Every tool `main`'s build, tests, workflows and metal loop run outside Rust and
-QEMU, found by the ways `.claude/agents/reviewer.md`'s Arrivals names, with the
-verdict of `CLAUDE.md`'s Dependencies on each; a refused row is a standing
-failure. A workflow's package manager, `apt-get` or `brew`, is how a row
+QEMU, and every one `diag/flash.sh` and the README's flashing steps run by hand,
+with the verdict of `CLAUDE.md`'s Dependencies on each; a refused row is a
+standing failure. A workflow's package manager, `apt-get` or `brew`, is how a row
 arrives and is not one. M4 and M5 are stages of `issues/build/toyos-builds-itself.md`.
 
 | tool | runs | verdict | exit |
 |---|---|---|---|
 | Python | LLVM's CMake, whenever this host builds an LLVM (`src/llvm.rs`) | admitted: no Rust tool does the job, LLVM's CMake requires one (`find_package(Python3 … REQUIRED)` in `rust/src/llvm-project/llvm/CMakeLists.txt`) | M5 runs it in the guest |
 | CMake | rustc's bootstrap, for LLVM and clang; `src/llvm.rs`, for the LLVM's key | admitted: no Rust tool does the job, LLVM, clang and LLD are described in CMake, and upstream's only other descriptions are a GN overlay it does not support and a Bazel one | M5 runs it in the guest |
-| Ninja | runs the build CMake generates for LLVM | admitted: no Rust tool does the job, bootstrap has CMake generate for Ninja, and no CMake generator targets a Rust tool | M5 runs it in the guest |
-| `git` | every build, which also adds worktrees (`src/worktree.rs`) and updates submodules (`src/lib.rs`, `src/sysroot.rs`); rustc's bootstrap; every workflow's checkout | admitted: no Rust tool does the job, gitoxide 0.85 adds no worktree and updates no submodule | M4 runs it in the guest |
+| Ninja | runs the build CMake generates for LLVM | refused: a Rust tool does it, n2, named `ninja` as its README directs for CMake: CMake's Ninja generator configured `rust/src/llvm-project/llvm` for it and it built `llvm-tblgen`, exit 0 each; named `n2`, CMake refuses its version, exit 1 | rustc's bootstrap builds LLVM under n2 |
+| `git` for worktrees, submodules, checkouts, fixtures and rustc's bootstrap | adds, removes and prunes worktrees (`src/worktree.rs`, `src/sysroot.rs`); updates submodules (`src/lib.rs`, `src/sysroot.rs`, `src/licence.rs`, `src/release.rs`); fetches the fork from the primary's and checks it out (`src/sysroot.rs`); fast-forwards the primary (`src/sync.rs`); makes the tests' fixture repositories; runs inside rustc's bootstrap | admitted: no Rust tool does the job, gitoxide 0.85 adds, removes and prunes no worktree, updates no submodule, stages, merges, resets and pushes nothing, checks out only a fresh clone and fetches a local path by spawning `git`; a fixture must be what `git` makes, and bootstrap runs `git` itself | M4 runs it in the guest |
+| `git` for reads, and for clones and fetches over HTTPS | `rev-parse`, `show-ref`, `for-each-ref`, `rev-list`, `log`, `branch --contains`, `merge-base`, `ls-tree`, `ls-files`, `cat-file`, `config --get-regexp`, `worktree list`, `status`, `diff`, `ls-remote` and `grep`, in the build system and its tests; `src/sync.rs`'s fetch of `origin`; every workflow's checkout | refused: a Rust tool does it, gitoxide 0.85, which reads refs, objects, the index, config, worktrees and status, walks history, diffs, and lists, fetches and clones a remote over HTTPS; `grep` is a search of the files its index names | those are gitoxide's |
 | `cc`, `c++` and `ar` on a Linux host, `build-essential` on the nightly's runners | rustc links every host binary through `cc`; `cc` and `c++` compile LLVM, clang, LLD and `rustc_llvm` (`src/llvm.rs` names both to bootstrap) and `ring`'s C for `tests/https-server-host` and `tests/https-fetch-host`; `ar` archives what `cc::Build` compiles | admitted: no Rust tool compiles C or C++, or takes rustc's host link | M5: no host in the loop |
+| the toolchain's own `clang`, `llvm-ar`, `rust-lld` and `llvm-config`, built from `ToyOSOrg/llvm-project` | rustc links every guest binary with `rust-lld`; `clang` compiles the C corpus and `hello.c` (`tests/common/compile.rs`, `tests/common/clang.rs`) and, with `llvm-ar`, doomgeneric through `cc::Build` (`src/clang.rs`); rustc's bootstrap asks `llvm-config` how to link LLVM | admitted: our fork's C++, which ToyOS can one day build and run; no Rust tool compiles C, `cc::Build` archives with an `ar`, bootstrap reads LLVM through `llvm-config`, and `CLAUDE.md` links everything with `rust-lld` | M5: no host in the loop |
 | `ovmf-generic` | the UEFI firmware of the nightly's guest containers (`src/firmware.rs`), packaged by Debian apart from QEMU | admitted: QEMU's own firmware, and no Rust firmware does its job | the instrument's QEMU carries its own firmware |
 | `ca-certificates` | the trust store `git` and `curl` verify against in the nightly's containers | admitted: data both of them need | goes when neither runs there |
-| `env` | the two portability jobs run `cargo run -- --build-only` under it, with `GITHUB_ACTIONS` and `CI` unset | admitted: no Rust tool on the runner unsets a variable for one command | M5: no host in the loop |
-| `sudo`, `dd`, `wipefs`, `efibootmgr`, `udevadm`, `mount`, `umount`, `reboot`, `visudo`, `install`, `systemd-analyze`, `ip`, `date`, `cat`, `ls`, `test`, `mkdir`, `rm`, `true`, and the login shell each command reaches | `src/metal.rs`, over `ssh`, on the T14's Ubuntu and never on a development host | admitted: no Rust tool does their job on that Ubuntu | Ubuntu leaves the metal loop (`issues/boot-media/the-machine-updates-itself-without-ubuntu.md`) |
-| `sh` running `rust/x`, and Python running `x.py` and `bootstrap.py` | every toolchain build (`src/toolchain.rs`) | refused: a Rust tool does it, upstream's bootstrap binary, which builds with stable cargo, fetches its own stage0 (`rust/src/bootstrap/src/core/download.rs:595`) and needs no Python | `src/toolchain.rs` runs the bootstrap binary |
+| `env` | the two portability jobs run `cargo run -- --build-only` under it, with `GITHUB_ACTIONS` and `CI` unset | refused: a Rust tool does it, the build system, which already runs that build with both removed (`src/release.rs`) | the build system removes both itself |
+| the T14's Ubuntu, 24.04.4 LTS, and every tool `src/metal.rs` runs on it over `ssh` | the metal loop, on the T14 and never on a development host | outside the rule: recovery equipment on a test machine, not the build's host | they leave with Ubuntu (`issues/boot-media/the-machine-updates-itself-without-ubuntu.md`) |
+| `sh` running `rust/x`, and Python running `x.py` and `bootstrap.py` | every toolchain build (`src/toolchain.rs`) | refused: a Rust tool does it, upstream's bootstrap binary, which builds with stable cargo, fetches its own stage0 (`rust/src/bootstrap/src/core/download.rs`) and needs no Python | `src/toolchain.rs` runs the bootstrap binary |
 | `curl` in rustc's bootstrap | fetches the stage0 `rust/src/stage0` pins, for a compiler or LLVM build whose build directory lacks it, whichever bootstrap runs | refused: a Rust tool does it, rustup installs the dated beta the pin names, and bootstrap takes a stage0 through `build.rustc` and `build.cargo`, as `src/sysroot.rs` hands it one | no toolchain build fetches with `curl` |
 | `curl` in `src/release.rs` and `src/sdkversion.rs` | the toolchain release's lookup and download and the crates.io index, on CI runners only | refused: a Rust tool does it, `ureq`, which `userland/doom/build.rs` already fetches with | those fetches are Rust's |
 | `tar` and `zstd` | `src/release.rs` packs and unpacks the toolchain release, on CI runners only | refused: a Rust tool does it, the `tar` crate `userland/doom/build.rs` already unpacks with, and a zstd crate | both are done in Rust, in-process |
 | `gh` | `src/release.rs` asks whether a toolchain release exists, creates it and moves the `sdk-<version>` alias, on the nightly's `build` runner | refused: not C or C++ source, it is Go | `src/release.rs` speaks GitHub's REST API itself |
 | `ssh` | `src/metal.rs` reaches the T14's Ubuntu with it, only in the metal loop | refused: a Rust tool does it, the repository's own russh client `crate::build::ssh_client_host`, which `src/metaltalk.rs` already drives | `src/metal.rs` drives that client, or Ubuntu leaves the loop |
-| `cc`, `c++`, `ar` and `xcrun` on a macOS host, Apple's Command Line Tools | what the Linux row's tools do, and rustc asks `xcrun` for the SDK on every host link that names no `SDKROOT` (`rust/compiler/rustc_codegen_ssa/src/back/apple.rs:230`), as `src/llvm.rs` does for the LLVM's key | refused: one host OS alone | M5: no host in the loop |
+| `cc`, `c++`, `ar` and `xcrun` on a macOS host, Apple's Command Line Tools | what the Linux row's tools do, and rustc asks `xcrun` for the SDK on every host link that names no `SDKROOT` (`rust/compiler/rustc_codegen_ssa/src/back/apple.rs`), as `src/llvm.rs` does for the LLVM's key | refused: one host OS alone | M5: no host in the loop |
 | `newfs_msdos` and `hdiutil` | `toyos-fat32`'s host tests format and mount their fixtures with them (`toyos-fat32/tests/common/mod.rs`), which keeps the `host` job on `macos-latest` | refused: one host OS alone | `issues/filesystem/fat32-suite-needs-macos-binaries.md` |
 | `diag/flash.sh` | the owner's flash of a stick by hand: `bash`, and the `stat`, `seq`, `tr`, `grep`, `cut` and `sync` it strings together | refused: shell of our own | `issues/build/the-owners-flash-script-runs-diskutil.md` |
 | `diskutil` and `plutil` | `diag/flash.sh`, and `diskutil` in the README's flashing steps | refused: one host OS alone | `issues/build/the-owners-flash-script-runs-diskutil.md` |
 | `shasum`, a Perl script on macOS | `diag/flash.sh` hashes the image with it | refused: a Rust tool does it, `sha2`, which `src/release.rs` hashes with | `issues/build/the-owners-flash-script-runs-diskutil.md` |
-| `dd` | `diag/flash.sh` writes the stick with it | refused: a Rust tool does it, the build system can write the image itself | `issues/build/the-owners-flash-script-runs-diskutil.md` |
-| `sudo` | `diag/flash.sh` runs `dd` under it | admitted: no Rust tool raises a process to root on macOS | goes with `diag/flash.sh` |
+| `lsblk` | the README's Linux flashing steps find the stick with it | refused: one host OS alone | `issues/build/the-owners-flash-script-runs-diskutil.md` |
+| `dd` | `diag/flash.sh` and the README's flashing steps write the stick with it | refused: a Rust tool does it, the build system can write the image itself | `issues/build/the-owners-flash-script-runs-diskutil.md` |
+| `sync` | the README's Linux flashing steps flush the stick with it | refused: a Rust tool does it, the build system can flush what it writes | `issues/build/the-owners-flash-script-runs-diskutil.md` |
+| `sudo` on macOS | `diag/flash.sh` and the README's macOS flashing steps run `dd` under it | admitted: no Rust tool raises a process to root on macOS | goes with both flashes by hand |
+| `sudo` on Linux | the README's Linux flashing steps run `dd` under it | refused: a Rust tool does it, sudo-rs | the README's Linux steps run sudo-rs |
 | `sh` running rustup's `rustup-init.sh` | the nightly's three rustup installs, fetched with `curl` | refused: a Rust tool does it, rustup's own `rustup-init` binary | a job installs rustup without it |
 | `nightly.yml`, job `build`, step "disk, QEMU, CMake and Ninja" | `sudo rm -rf` of five preinstalled SDK directories, then `sudo apt-get update` and `install` | refused: shell of our own | each step is one command |
 | `nightly.yml`, step `deps`, which jobs `guest` and `tcg` share | the snapshot archive read out of `debian.sources` with `sed`, checked with `test` and written back with `echo` and `rm`, a three-attempt `apt-get` loop with `sleep` and `cat`, `git config`, and rustup through `curl`, `sh` and `echo` | refused: shell of our own | each step is one command |
 
@@ -0,0 +1,20 @@
+---
+status: open
+kind: tooling
+opened: 2026-09-30
+---
+
+# The fork checkout runs `git submodule` in a linked worktree
+
+`sysroot::fork_checkout` makes a worktree's `rust/` a linked worktree of the
+primary's `rust` (`git worktree add --detach`). When the primary's
+`library/backtrace` lacks the commit the fork pins, it runs
+`git submodule update --init library/backtrace` inside that linked worktree,
+which `.claude/agents/implementer.md` forbids: `git submodule` in a linked
+worktree writes `core.worktree` into shared config and breaks git in the
+primary checkout's `rust/`. The orchestrator measured that for
+`git submodule update rust` in a linked worktree of the monorepo, which set the
+primary's `.git/modules/rust/config` `core.worktree` to a path that does not
+exist; this arm is the same command one level down and is unmeasured.
+
+**Exit**: `fork_checkout` runs no `git submodule` in a linked worktree.
@@ -36,7 +36,7 @@ AArch64 one step behind, on `issues/kernel/toyos-runs-on-arm64.md`'s track.
   the host build of the same commit.
 - **M5 — ToyOS rebuilds its own compilers to a fixed point; the host is no
   longer needed.** The guest's toolchain builds the next toolchain, its LLVM
-  with Python, CMake and Ninja built for ToyOS, and that one builds itself
+  with Python and CMake built for ToyOS, and that one builds itself
   again to the same bytes.
   *Exit*: the fixed point, reached with no host in the loop.