docs+code: drop misleading fs.base notation for the thread pointer

The "fs.base" spelling read like a field/submodule access, but no such
identifier exists — it meant the x86_64 FS segment base (the IA32_FS_BASE
MSR). Two problems fixed:

- Arch-neutrality: in generic docs, the runtime, and the plan, the mechanism
  is now named by its arch-neutral concept — the "thread pointer" — matching
  the already-renamed `thread_pointer` Task field, `set_thread_pointer`
  syscall, and `architecture.setThreadPointer` fn. x86-specific spots keep
  the precise names: `IA32_FS_BASE` (the MSR), `%fs:8`/`%fs:0`, variant-II.

- Stale identifiers: the M10 section in threading-plan.md still referenced
  `fs_base` on Task and `architecture.setFsBase` — both renamed away in the
  arch-neutral pass. Corrected to `thread_pointer` / `setThreadPointer`.

The x86-only `thread-tls` test (which really does write `%fs:8`) now says
"FS base" (no dot) consistently, matching the established form already in
tests.zig. The matched serial markers ("thread-tls: ok" / "thread-tls:
FAIL") are unchanged; only a non-load-bearing FAIL parenthetical was
reworded.

Verified: zig build clean, thread-tls passes.

.zig-version

@@ -1 +0,0 @@
-0.16.0

README.md

@@ -1,8 +1,8 @@
 # DanOS
-Codename: Shodan
-Version: 1
 
-A small resilient operating system, written from scratch in Zig.
+**Codename: Shodan**
+
+A very small resilient operating system.
 
 ## Zen of DanOS:
 
@@ -18,12 +18,12 @@ A small resilient operating system, written from scratch in Zig.
     - Useful during driver development.
     - Drivers can claim MMIO / ports
     - Driver resources (e.g. IRQ/Port/MMIO) claims are automatically cleaned up if the driver dies or is killed
-    - Drivers can also hook into the process lifecyle to clean up or reset hardware
+    - Drivers can also hook into the process lifecycle to clean up or reset hardware
 - No legacy to deal with
     - Zig code uses a clean coding style (Zen of Zig)
     - Favor reading code over writing code.
     - No magic numbers.
-    - No shortend names unless its for ABI compatibility or acronyms
+    - No shortened names unless its for ABI compatibility or acronyms
 - Inter-Process Communication (IPC)
   - Publish and subscribe to Asynchronous Messages
   - Talk to services and processes synchronously
@@ -54,6 +54,17 @@ the UEFI bootloader at `zig-out/EFI/BOOT/BOOTX64.efi`, the kernel at
 `zig-out/system/kernel`, init at `zig-out/system/services/init`, drivers under
 `zig-out/system/drivers/`, and the initial-ramdisk at `zig-out/boot/`.
 
+## Release media
+
+```sh
+zig build release-x86-64
+```
+
+Produces `zig-out/danos-x86-64.iso`, a hybrid ISO that boots flashed raw to a
+USB stick (balenaEtcher, dd) or burned to optical media — see
+[docs/release-iso.md](docs/release-iso.md). `zig build check-iso-image`
+validates it without booting.
+
 ## Run
 
 Boot it in QEMU with OVMF (opens a display window):

build.zig

@@ -69,6 +69,36 @@ fn addUserBinary(
     acpi_ids_module: *std.Build.Module,
     name: []const u8,
     root: []const u8,
+) *std.Build.Step.Compile {
+    return addUserBinaryImpl(b, target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, name, root, false);
+}
+
+/// As `addUserBinary`, but built multi-threaded (`single_threaded = false`) so real
+/// atomics/TLS work — required before a binary may call `runtime.Thread.spawn`
+/// (docs/threading.md). Threads are a deliberate per-binary opt-in.
+fn addThreadedUserBinary(
+    b: *std.Build,
+    target: std.Build.ResolvedTarget,
+    runtime_module: *std.Build.Module,
+    mmio_module: *std.Build.Module,
+    xkeyboard_config_module: *std.Build.Module,
+    acpi_ids_module: *std.Build.Module,
+    name: []const u8,
+    root: []const u8,
+) *std.Build.Step.Compile {
+    return addUserBinaryImpl(b, target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, name, root, true);
+}
+
+fn addUserBinaryImpl(
+    b: *std.Build,
+    target: std.Build.ResolvedTarget,
+    runtime_module: *std.Build.Module,
+    mmio_module: *std.Build.Module,
+    xkeyboard_config_module: *std.Build.Module,
+    acpi_ids_module: *std.Build.Module,
+    name: []const u8,
+    root: []const u8,
+    threaded: bool,
 ) *std.Build.Step.Compile {
     // Settings (target, optimize, code model, ...) live on the root module only;
     // the program and runtime modules leave theirs null and inherit them.
@@ -93,7 +123,7 @@ fn addUserBinary(
             .target = target,
             .optimize = .ReleaseSmall,
             .code_model = .large,
-            .single_threaded = true,
+            .single_threaded = !threaded, // a threaded binary needs real atomics/TLS
             .sanitize_c = .off,
             .stack_check = false,
             .stack_protector = false,
@@ -194,8 +224,9 @@ fn addKernel(
 /// Assemble the bootable FAT32 image (the in-repo Python builder) holding what
 /// the firmware and loader need off the ESP: the EFI stub, `kernel`, `init`, and
 /// the initial-ramdisk. Factored so the serial-enabled `run-x86-64` variant can
-/// bundle its own kernel while sharing the (serial-independent) loader, init, and
-/// ramdisk. Returns the image's LazyPath.
+/// bundle its own serial kernel while sharing the loader, init, and ramdisk — all
+/// built once per invocation (the loader's boot breadcrumbs and init's heartbeat
+/// both follow the top-level -Dserial). Returns the image's LazyPath.
 fn addBootImage(
     b: *std.Build,
     kernel_bin: std.Build.LazyPath,
@@ -463,6 +494,14 @@ pub fn build(b: *std.Build) void {
     // linked into the kernel's user region against the `runtime` runtime library, and
     // started in ring 3 by the kernel's user-ELF loader.
     const init_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "init", "system/services/init/init.zig");
+    // init reads the same `serial` flag the kernel does: its liveness heartbeat is a
+    // serial/test-build diagnostic (the QEMU harness's init tests assert on it, and
+    // -Dserial images emit it), so a flashable image runs a purely event-driven PID 1
+    // that wakes only for real work. The test harness builds with -Dserial=true, so
+    // the heartbeat stays present under test.
+    const init_options = b.addOptions();
+    init_options.addOption(bool, "serial", serial);
+    programModule(init_exe).addImport("build_options", init_options.createModule());
     const init_install = b.addInstallArtifact(init_exe, .{ .dest_dir = .{ .override = .{ .custom = "system/services" } } });
     b.getInstallStep().dependOn(&init_install.step);
 
@@ -539,6 +578,9 @@ pub fn build(b: *std.Build) void {
     const args_echo_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "args-echo", "system/services/args-echo/args-echo.zig");
     const process_test_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "process-test", "system/services/process-test/process-test.zig");
     const log_flush_exe = addUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "log-flush", "system/services/log-flush/log-flush.zig");
+    // The first multi-threaded binary: exercises runtime.Thread over the thread ABI
+    // (docs/threading.md). Built threaded so its shared-memory poll is real.
+    const thread_test_exe = addThreadedUserBinary(b, kernel_target, runtime_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "thread-test", "system/services/thread-test/thread-test.zig");
 
     // Pack the user binaries into the initial_ramdisk image with the host-side Python tool
     // (the container format is trivial, and Python sidesteps std API churn). Args:
@@ -582,6 +624,8 @@ pub fn build(b: *std.Build) void {
     mk_run.addFileArg(pci_bus_exe.getEmittedBin());
     mk_run.addArg("crash-test");
     mk_run.addFileArg(crash_test_exe.getEmittedBin());
+    mk_run.addArg("thread-test");
+    mk_run.addFileArg(thread_test_exe.getEmittedBin());
     mk_run.addArg("device-list");
     mk_run.addFileArg(device_list_exe.getEmittedBin());
     mk_run.addArg("discovery");
@@ -684,6 +728,31 @@ pub fn build(b: *std.Build) void {
     const check_fat_step = b.step("check-fat-image", "Verify the FAT32 USB image is valid and bootable");
     check_fat_step.dependOn(&check_fat.step);
 
+    // --- release-x86-64: danos-x86-64.iso, the flashable release image ---
+    // Wrap the FAT32 boot volume in a hybrid ISO (the in-repo Python builder
+    // again, no xorriso/isohybrid): an ISO9660 whose El Torito EFI boot entry
+    // and MBR ESP partition entry both point at the embedded FAT image. One
+    // file then boots every way release media is consumed — flashed raw to a
+    // USB stick with Etcher or dd, or burned to optical media — while
+    // danos-usb.img stays the raw superfloppy QEMU and the test harness boot.
+    const mk_iso = b.addSystemCommand(&.{"python3"});
+    mk_iso.addFileArg(b.path("tools/make-iso-image.py"));
+    const iso_image = mk_iso.addOutputFileArg("danos-x86-64.iso");
+    mk_iso.addFileArg(fat_image);
+    const iso_install = b.addInstallFile(iso_image, "danos-x86-64.iso");
+    const release_step = b.step("release-x86-64", "Build the flashable x86-64 release ISO (zig-out/danos-x86-64.iso; flash with Etcher or dd)");
+    release_step.dependOn(&iso_install.step);
+
+    // `zig build check-iso-image` — the ISO builder's own --verify (mirroring
+    // check-fat-image): the MBR partition, the El Torito catalog, and the
+    // embedded FAT32 image must all agree.
+    const check_iso = b.addSystemCommand(&.{"python3"});
+    check_iso.addFileArg(b.path("tools/make-iso-image.py"));
+    check_iso.addArg("--verify");
+    check_iso.addFileArg(iso_image);
+    const check_iso_step = b.step("check-iso-image", "Verify the release ISO is a valid hybrid (MBR ESP partition + El Torito EFI entry)");
+    check_iso_step.dependOn(&check_iso.step);
+
     // --- run-x86-64: boot the x86-64 kernel in QEMU via UEFI/OVMF ---
     // Firmware lives in different places per OS/distro, so probe the known
     // layouts (Architecture, Debian/Ubuntu, Fedora, macOS Homebrew) and use the first
@@ -857,6 +926,22 @@ pub fn build(b: *std.Build) void {
     });
     test_step.dependOn(&b.addRunArtifact(time_tests).step);
 
+    // runtime.Thread's lock/condvar state machines (Mutex/Condition/RwLock/WaitGroup). Its
+    // Futex seam falls back to std.Thread.Futex off the danos target, so the tests exercise
+    // them with real host threads (docs/threading-plan.md M11). Like time.zig it pulls in
+    // system.zig (syscall wrappers), which needs the `abi` module.
+    const thread_tests = b.addTest(.{
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("library/runtime/thread.zig"),
+            .target = target,
+            .optimize = optimize,
+            .imports = &.{
+                .{ .name = "abi", .module = abi_module },
+            },
+        }),
+    });
+    test_step.dependOn(&b.addRunArtifact(thread_tests).step);
+
     // Convenience: `zig build gen-xkeyboard-config` regenerates the layout tables from the
     // vendored data (offline). `fetch` (the network step) stays a manual script run.
     const gen_xkb = b.addSystemCommand(&.{ "python3", "tools/make-xkeyboard-config.py", "generate" });

docs/README.md

@@ -39,37 +39,42 @@ rather than restate it. Roughly in the order things happen at runtime:
     endpoints — the backbone the microkernel's isolated servers talk over.
 12. **[syscall.md](syscall.md) — system calls.** How ring 3 asks the kernel for
     something: the `syscall`/`sysret` fast path, the trap frame, and why the table is
-    deliberately tiny.
-13. **[drivers.md](drivers.md) — writing a driver.** The payoff: a driver is an
+    deliberately tiny. The numbers are a **private** ABI — [vdso.md](vdso.md) designs
+    the public boundary that will hide them.
+13. **[vfs-protocol.md](vfs-protocol.md) — the VFS wire protocol.** The language-neutral
+    byte-level spec of the file protocol spoken over IPC: request/reply headers,
+    the operation table, mount routing, and the append-only evolution rules — the
+    first IPC protocol documented as public ABI.
+14. **[drivers.md](drivers.md) — writing a driver.** The payoff: a driver is an
     ordinary ring-3 process that claims a device, maps its registers, and **sleeps
     until its hardware interrupts it**. The claim is the capability; `irq_ack` is the
     unmask.
-14. **[driver-model.md](driver-model.md) — buses, classes and host controllers.** How
+15. **[driver-model.md](driver-model.md) — buses, classes and host controllers.** How
     real driver stacks factor into three shapes and how families share code. The
     three primitives it proposed are long since built (M13 capability passing,
     M14 DMA + barriers, M15 MSI), and the driver *contract* on top of them —
     hello, supervision, restart — is built too (device-manager.md, M18).
-15. **[process-management.md](process-management.md) — process management.** The
+16. **[process-management.md](process-management.md) — process management.** The
     microkernel's `ps`/`kill`/SIGCHLD: enumerate as a table snapshot, the
     supervision link as the kill authority, and child-exit notifications over the
     same endpoints IRQs arrive on.
-16. **[process-lifecycle.md](process-lifecycle.md) — the process lifecycle.** Built
+17. **[process-lifecycle.md](process-lifecycle.md) — the process lifecycle.** Built
     (M17): signals over IPC as the one lifecycle vocabulary every process speaks — the
     POSIX.1-1990 words with message delivery instead of stack hijack, the stable
     `runtime.process` interface, exit reasons, published exit events any stateful
     service can subscribe to (the VFS releasing dead clients' handles), and the two
     iron rules (cleanup is the kernel's job; kill is not a signal).
-17. **[device-manager.md](device-manager.md) — the device manager.** Built (M18,
+18. **[device-manager.md](device-manager.md) — the device manager.** Built (M18,
     through the app surface): the
     tree, the matcher, and the supervisor. Tree structure lives in the manager,
     authority stays in the kernel; bus drivers report what they see; drivers are
     restarted through the lifecycle vocabulary — the plan that turns
     [resilience.md](resilience.md)'s restart goal into increments.
-18. **[input.md](input.md) — the input module.** Broadcasting input events (keyboard,
+19. **[input.md](input.md) — the input module.** Broadcasting input events (keyboard,
     mouse, joystick): why a synchronous rendezvous can't fan out to many listeners, the
     asynchronous `ipc_send` primitive built to fix it, and the per-device subscribe/publish
     service layered on top.
-19. **[display.md](display.md) — the display service.** The display half of the GUI
+20. **[display.md](display.md) — the display service.** The display half of the GUI
     track: a user-space compositor that owns the framebuffer, composes a layer stack into
     a double buffer, and presents it. Why GOP and the PCI display device are two views of
     one controller, the device-node + write-combining handoff, and what flicker-free buys
@@ -80,7 +85,7 @@ rather than restate it. Roughly in the order things happen at runtime:
     further out, two research snapshots survey what a *native* driver for real GPU silicon
     would take as another `.scanout` backend: [nvidia-gpus.md](nvidia-gpus.md) (RTX 3060 /
     Ampere) and [intel-igpu.md](intel-igpu.md) (Intel iGPU).
-20. **[halting.md](halting.md) — halting.** Why a kernel can't just "exit", and
+21. **[halting.md](halting.md) — halting.** Why a kernel can't just "exit", and
     how `while (true) hlt` parks the CPU safely once there's nothing left to do.
 
 Start with the north star:
@@ -99,6 +104,19 @@ Start with the north star:
   port to **one seam** (`std.os.danos`), so we build `runtime.os` (→ that seam) plus a
   thin `runtime.fs`, retire the `posix` shim, and follow a phased path to
   `zig build-exe hello.zig` running on danos — **not** Linux-ABI emulation.
+- **[threading.md](threading.md) — threads, the std-shaped way.** **Built** (M1–M6):
+  `runtime.Thread` mirrors `std.Thread`'s API (spawn/join/detach, Mutex/Condition/
+  Semaphore) over a **private** thread ABI — several tasks sharing one address space via
+  a `thread_spawn` syscall, futex-backed blocking, address-space refcounting. Why it's the
+  native type and not literal `std.Thread` (the [private ABI](syscall.md)), and why
+  threads stay a narrow opt-in against the [resilience](resilience.md) default. Build
+  plan + gates: [threading-plan.md](threading-plan.md).
+- **[vdso.md](vdso.md) — the vDSO, the public system-call boundary.** A design note
+  (not built yet) on keeping `abi.zig` genuinely private: a kernel-supplied, C-ABI
+  entry blob mapped into every process as the *only* way into the kernel — so the
+  syscall numbers can be renumbered or randomised at will, and Rust/C binaries get a
+  stable boundary without danos growing a dynamic linker. danos's public ABI = the
+  vDSO + the documented IPC wire protocols ([vfs-protocol.md](vfs-protocol.md) first).
 
 Cutting across all of these:
 
@@ -106,6 +124,11 @@ Cutting across all of these:
   hardware needed to run danos: minimum specs (UEFI x86-64, ACPI, PCIe ECAM,
   xHCI, ~128 MiB RAM) grounded in what the boot path actually assumes, plus a
   plain-language guide matching Intel/AMD CPU generations by name.
+- **[release-iso.md](release-iso.md) — the release ISO.** The flashable boot
+  media: `zig build release-x86-64` wraps the FAT32 boot volume in a hybrid ISO
+  (MBR ESP partition + El Torito EFI entry, one embedded image) that Etcher/dd
+  flash to USB or a burner writes to disc — built by an in-repo pure-Python
+  tool, like the FAT image itself.
 - **[arch.md](arch.md) — the architecture split.** How CPU-specific code is kept
   behind a build-time `arch` module so the generic kernel never names x86_64,
   leaving room for other systems (e.g. an AArch64 Raspberry Pi) later.
@@ -250,5 +273,5 @@ exception in [coding-standards.md](coding-standards.md) applies to that seam.
 | danos-native runtime (`runtime`): syscall wrappers, heap, IPC, device access, the file API (`fs`) — the stable application ABI | `library/runtime/` |
 | System services (init, the VFS server + `protocol`, the device-manager) | `system/services/` |
 | Device drivers, one sub-project each (`pci-bus`, `ps2-bus`, `usb-xhci-bus` bus drivers) | `system/drivers/` |
-| Build + `run-x86-64` (QEMU/OVMF) | `build.zig` |
+| Build + `run-x86-64` (QEMU/OVMF) + `release-x86-64` (the flashable ISO) | `build.zig` |
 | QEMU integration test harness | `test/qemu_test.py` |

docs/display-v2-plan.md

@@ -62,7 +62,7 @@ is the only backend), and `zig build test` stays green.
 - [x] [abi.zig](../system/abi.zig): `shm_create` (34) / `shm_map` (35) syscalls + a
       `shm_test` service id. Handlers in process.zig: `shm_create(len)` allocates contiguous,
       zeroed, **cacheable** frames, wraps them in a refcounted object, installs a capability
-      handle, maps them into the caller's shm arena → returns vaddr + handle; `shm_map(cap)`
+      handle, maps them into the caller's shm arena → returns virtual_address + handle; `shm_map(cap)`
       maps the same physical pages into the receiver. Reclaimed on death (see below).
 - [x] The capability core (ipc-synchronous.zig) is now **kind-tagged**: `scheduler.Task`'s
       handle table holds `HandleObject{kind, ptr}`; `closeHandles` and `shareCapability`

docs/display-v2.md

@@ -77,9 +77,9 @@ deferred (docs/display.md, "What v1 does not do"). v2 builds it: the natural gen
 of M13 capability-passing from *endpoints* to *memory objects* —
 
 ```
-shm_create(len) -> {handle, vaddr}     // a shareable, page-aligned RAM region
+shm_create(len) -> {handle, virtual_address}     // a shareable, page-aligned RAM region
 … pass `handle` as the send_cap on an ipc_call …
-shm_map(cap)    -> vaddr                // the receiver maps the same physical pages
+shm_map(cap)    -> virtual_address                // the receiver maps the same physical pages
 ```
 
 The payoff is leverage: the **same** primitive unlocks **both** native GPU drivers *and*

docs/display.md

@@ -220,8 +220,8 @@ both are clean additions behind the interfaces v1 establishes.
   to render into its *own* buffer and hand the compositor a *reference*, not a stream of
   commands. That needs the missing cross-process shared-memory primitive — best built as
   the natural generalization of the existing M13 [capability passing](driver-model.md)
-  from *endpoints* to *memory objects* (`shm_create(len) → {cap, vaddr}`, pass `cap` on
-  an `ipc_call`, receiver `shm_map(cap) → vaddr`). v1 avoids it because server-owned
+  from *endpoints* to *memory objects* (`shm_create(len) → {cap, virtual_address}`, pass `cap` on
+  an `ipc_call`, receiver `shm_map(cap) → virtual_address`). v1 avoids it because server-owned
   surfaces already prove the whole pipeline.
 
 - **Runtime mode-setting (a native backend).** Detecting the EDID mode list and changing

docs/driver-model.md

@@ -240,8 +240,8 @@ once per page, maps writeback-cached, and never reveals a physical address.
 **The fix.**
 
 ```
-dma_alloc(len, flags) -> vaddr (rax), paddr (rdx)
-dma_free(vaddr, len)  -> 0
+dma_alloc(len, flags) -> virtual_address (rax), physical_address (rdx)
+dma_free(virtual_address, len)  -> 0
 
 flags:  dma_coherent  (1)  uncacheable; the default and the only one that's portable
         dma_wc        (2)  write-combining — needs PAT programmed; for framebuffers

docs/drivers.md

@@ -74,7 +74,7 @@ The driver syscall numbers (`system/abi.zig`) with the device types they carry
 |---|------|---------|
 | 11 | `device_enumerate(buf, max) -> total` | Snapshot the device table |
 | 12 | `device_claim(id) -> ok` | Take **exclusive** ownership |
-| 13 | `mmio_map(id, res_idx) -> vaddr` | Map a claimed device's register window |
+| 13 | `mmio_map(id, res_idx) -> virtual_address` | Map a claimed device's register window |
 | 14 | `irq_bind(id, res_idx, endpoint)` | Deliver that device's IRQ as a notification |
 | 15 | `irq_ack(id, res_idx)` | Re-arm the IRQ after servicing the device |
 | 16 | `device_register(parent_id, desc) -> id` | Publish a child of a device you claimed |

docs/os-developer-guide/README.MD

@@ -0,0 +1,9 @@
+# OS Developer Guide
+
+This document is for those who need to understand the architectural decisions behind the OS.
+
+## Written in Zig?
+
+The os was initially written in zig because it has excellent support for EFI. With zig, we could forgo using a third party bootloader, reducing the time to boot up the kernel. Following the "Zen of Zig", helped to produce the most readable codebase for an operating system ever created. So those, new to OS development could quickly get up to speed.
+
+

docs/release-iso.md

@@ -0,0 +1,70 @@
+# The release ISO — flashable boot media
+
+`zig build release-x86-64` produces **`zig-out/danos-x86-64.iso`**, the file you
+hand to someone who wants to try danos on a real machine: point
+[balenaEtcher](https://etcher.balena.io) (or Raspberry Pi Imager, or plain `dd`)
+at it, flash a USB stick, and boot the stick. The same file also burns to
+optical media. `zig build check-iso-image` validates it without booting.
+
+```
+zig build release-x86-64
+# Etcher: select danos-x86-64.iso → select the stick → Flash
+# or: sudo dd if=zig-out/danos-x86-64.iso of=/dev/rdiskN bs=4m   (macOS; triple-check N)
+```
+
+## Why an ISO when danos-usb.img already boots
+
+`danos-usb.img` is a raw FAT32 **superfloppy** — a filesystem starting at
+sector 0, no partition table. UEFI firmware accepts that from a USB stick (it
+probes whole-disk FAT before giving up), which is why `dd`-ing the .img works
+and why QEMU and the test harness boot it directly. But it is a
+developer-shaped artifact: flashing apps expect an ISO, and a superfloppy
+can't be burned to a CD/DVD or carry a partition table for pickier firmware.
+
+The ISO wraps that same FAT image — bit-identical, built by the same
+`tools/make-fat-image.py` — in a container that boots everywhere release media
+gets consumed. One payload, two images: the .img stays the raw volume the QEMU
+harness mounts and boots, the .iso is what leaves the building.
+
+## How a hybrid ISO boots twice
+
+The trick (the same one Linux distribution ISOs use, usually via `xorriso
+-isohybrid…`) is that ISO9660 reserves its first 32 KiB as a **system area** it
+never touches — exactly where an MBR lives on a disk. So one file can carry two
+tables of contents, both pointing at the same embedded FAT image:
+
+* **Flashed to USB (Etcher, dd):** firmware sees a disk whose sector 0 is an
+  MBR with one partition of type `0xEF` (EFI System Partition) covering the
+  embedded FAT image. It mounts that ESP and runs `\EFI\BOOT\BOOTX64.efi` —
+  the standard removable-media path ([efi.md](efi.md)).
+* **Burned to optical media:** firmware reads the ISO9660 volume descriptors
+  at sector 16 and finds an **El Torito** boot record. Its catalog has one
+  entry, platform ID `0xEF` (EFI), whose start LBA is — again — the embedded
+  FAT image. The firmware exposes that image as a virtual disk and runs the
+  same `BOOTX64.efi` off it.
+
+Neither path involves the legacy BIOS boot-sector machinery: danos is
+UEFI-only ([system-requirements.md](system-requirements.md)), so the MBR holds
+no boot code, just the partition entry, and the El Torito entry is EFI-class,
+not floppy emulation.
+
+One El Torito wrinkle: the catalog's sector-count field is 16-bit (units of
+512 bytes), so it can name at most 32 MiB — less than the 64 MiB FAT image.
+That is fine in practice: firmware sizes the FAT filesystem from its own BPB,
+and the boot files sit in the first few MiB of the image (clusters are
+allocated from the front) either way. The USB path has no such cap.
+
+## The builder
+
+`tools/make-iso-image.py` follows the house rule of
+[make-fat-image.py](../tools/make-fat-image.py): pure Python 3 standard
+library, no external tools (no xorriso, mkisofs, or isohybrid), with a
+`--verify` mode the `check-iso-image` step runs — it checks that the MBR
+partition and the El Torito catalog agree on where the FAT image lives and
+that a FAT32 boot sector is actually there. Every timestamp field in the ISO
+is zeroed, so the build is reproducible byte-for-byte.
+
+The ISO9660 filesystem around the boot machinery is minimal but real: a root
+directory listing `BOOT.CAT` (the catalog) and `EFI.IMG` (the FAT image), so
+`file`, mount tools, and archive browsers can open the ISO and see what's in
+it.

docs/threading-plan.md

@@ -0,0 +1,469 @@
+# Threading — build plan (`runtime.Thread` over a private thread ABI)
+
+The ordered, checkpointable build-out for [threading.md](threading.md). Each milestone
+lands on its own and ends in a **verifiable gate** — shaped for a `/loop` run, like
+[display-v2-plan.md](display-v2-plan.md). Read threading.md first for the *why*.
+
+## Locked decisions (do not relitigate)
+
+- **`runtime.Thread` mirrors `std.Thread`'s API; the implementation is danos-native.**
+  Not literal `std.Thread` — that would break the [private ABI](syscall.md).
+- **Threads are a narrow, per-binary opt-in.** Default concurrency stays process + IPC
+  ([resilience.md](resilience.md)); only a service that asks is built
+  `single_threaded = false`.
+- **Blocking is futex-backed, never spin-backed** — waiters park in the kernel so an
+  idle core still halts ([halting.md](halting.md)).
+- **New syscalls are private**: extend [abi.zig](../system/abi.zig) `SystemCall` after
+  `shm_physical = 36` (`thread_spawn = 37`, `thread_exit = 38`, `current_core = 39`,
+  `futex_wait = 40`, `futex_wake = 41`) + a `library/runtime` wrapper; user code never names a number.
+- **Restart granularity stays the process** — a faulting thread kills its process; the
+  supervisor restarts the process, which respawns its threads.
+
+## Conventions
+
+Follow [coding-standards.md](coding-standards.md): spell out non-acronym abbreviations,
+kebab-case file names, no `Co-Authored-By` trailers. New user binaries go through
+`addUserBinary` (with the new `threaded` flag where a binary spawns threads) and get
+packed into the initial-ramdisk; new syscalls extend [abi.zig](../system/abi.zig)
+`SystemCall` + a `library/runtime` wrapper; test services live beside the code they
+exercise and register a `ServiceId` if they must be looked up.
+
+## How to verify along the way
+
+**Every gate is serial-checkable — no screenshots** (this plan runs unattended). A
+thread proves it ran by writing to **shared memory** the parent reads back, and proves
+parallelism by stamping the **core index** it ran on (like the `smp`/`affinity` cases).
+
+- `zig build test` — host unit tests (closure packing, mutex state machine, futex
+  wrapper encodings).
+- `python3 test/qemu_test.py <case>` — boots the kernel in QEMU; asserts on serial
+  markers. Thread cases set `smp: true` (real parallelism) and bump `mem` (they boot
+  the process/scheduler stack); each milestone **adds its case to `CASES`** so its gate
+  is runnable.
+- **Guardrail every milestone:** the concurrency-sensitive existing cases stay green —
+  `smoke`, `sched`, `priority`, `smp`, `affinity`, `process`, `process-kill`,
+  `supervision`, `fault-recovery`, `vfs-client-death`, `ipc`/`ipc-cap`,
+  `display-service`. A threading change that regresses those is rejected.
+
+## Unattended execution (the loop contract)
+
+This plan runs to completion **without human input**. Every design choice is already
+fixed in *Locked decisions*; the checkboxes are the only state. A loop iteration must:
+
+1. **Resume** at the first milestone that still has an unchecked `- [ ]`. (All earlier
+   milestones are done — do not revisit them.)
+2. **Work on a branch.** On the first iteration, branch off the current `main` into a new
+   branch (e.g. `threading-phase2` — Phase 1's `threading` is already merged); never
+   commit to `main` directly. Push that **branch** to `origin` after each milestone (step
+   5) so progress is backed up remotely; **do not push `main`** — merging Phase 2 into
+   `main` stays a human step.
+3. **Implement** every unchecked item in that milestone, including adding its
+   `-Dtest-case` to `CASES` in [test/qemu_test.py](../test/qemu_test.py) (with
+   `smp: true` / a `mem` bump where noted) so the gate is runnable.
+4. **Run the gate**: `python3 test/qemu_test.py <case>`, then the full **guardrail
+   set**, then `zig build` (clean) and `zig build test` (green).
+5. **Decide, do not ask:**
+   - **Green** = the milestone's case prints its stated marker(s) and reports `PASS`,
+     the whole guardrail set passes, `zig build` is clean, and host tests are green.
+     → tick this milestone's boxes **and** its `**Gate:**`-referenced case, `git commit`
+     (`threads(M<n>): <summary>`, no `Co-Authored-By` trailer per
+     [coding-standards.md](coding-standards.md)), then **`git push` the working branch to
+     `origin`** (use `-u` on the first push to set upstream). Continue to the next
+     milestone in the same iteration if budget remains; otherwise let the loop re-fire.
+   - **Red** = anything above fails. Diagnose from the captured serial log
+     (`zig-out/qemu-test/<case>-failed-serial.log`) and fix in place, then re-run — up to
+     **3 fix attempts** for that gate. A concurrency case that fails then passes on a
+     bare re-run is **flaky, not green**: re-run it **twice more** and treat green only
+     if it passes all; otherwise fix the race (a real threading bug), don't paper over
+     it.
+6. **A genuinely ambiguous fork is not a stop.** Pick the option most consistent with
+   [threading.md](threading.md)'s *Locked decisions*, note the choice in the commit
+   message, and continue. Do not pause for confirmation on in-scope, reversible work —
+   this plan is that authorization.
+
+**The only stop conditions:**
+
+- **Done** — every milestone box **in this plan** is checked (M1 through M11), `zig build`
+  clean, the whole `thread-*` suite + guardrail green. Phase 1 (M1–M6) is *already*
+  checked, so do **not** read that as Done: the loop's real work is the first plan section
+  that still has unchecked boxes — Phase 2 (M7–M11). Only stop when M7–M11 are all checked
+  too. Update threading.md's status line, push the final branch state to `origin`, and
+  stop. The branch is on `origin` for review; **merging Phase 2 into `main` is the user's
+  step**, not the loop's.
+- **Blocked** — a gate is still red after 3 fix attempts, or a step needs something
+  outside the repo (a toolchain change, new hardware, a decision no locked decision
+  covers). Append `> **BLOCKED (M<n>):** <what failed, what was tried, the serial
+  marker missing>` under that milestone, commit **and push** the WIP on the branch, and
+  stop. Do not thrash further and do not silently skip the milestone.
+
+Nothing else warrants stopping — not "should I proceed?", not "is this right?". The
+checkboxes + git history are the resumable record; the next iteration picks up from the
+first unchecked box.
+
+---
+
+## M1 — Address-space refcount (kernel foundation, no API, no behaviour change) ✅
+
+The one invariant change threads require, landed and proven **before** anything shares
+an address space. Today address space is 1:1 with a task and teardown destroys it on any user
+task's exit; make destruction happen on the **last** exit.
+
+- [x] A refcount keyed by the address-space root, held in `scheduler.zig`
+      (`address_space_refs`): `retainAddressSpace` takes a reference in `spawnUserLocked` (on the
+      success path, after the slot + stack are secured), all under the big kernel lock.
+- [x] Both task-teardown paths ([scheduler.zig](../system/kernel/scheduler.zig):
+      `exitUserLocked` and `destroyTaskLocked`) call `releaseAspace`, which decrements
+      and only `destroyAddressSpace`s at **zero**; an unretained space (hand-built test
+      spaces) is destroyed directly, preserving prior behaviour.
+- [x] `-Dtest-case=address-space-refcount`: spawn and reap several ring-3 processes in sequence
+      and assert (via test-observable `liveAddressSpaceCount`/`addressSpaceDestroyCount`) that the
+      live-space count returns to **baseline** and destructions advance by exactly that
+      many — each space destroyed exactly once, no leak, no double-free. (Refcount
+      observables, not raw frame counts, since kernel stacks are still leaked on exit.)
+
+**Gate (met):** `python3 test/qemu_test.py address-space-refcount` passes
+(`address-space-refcount: spaces released to baseline ok` → `DANOS-TEST-RESULT: PASS`), and the
+full guardrail set passes unchanged — 13/13 (`smoke`, `sched`, `priority`, `smp`,
+`affinity`, `process`, `process-kill`, `supervision`, `fault-recovery`,
+`vfs-client-death`, `ipc`, `ipc-cap`, `display-service`); default `zig build` clean,
+`zig build test` green. The reframing is invisible until an address space is actually shared.
+
+## M2 — `thread_spawn` + `thread_exit`: a thread runs in the shared address space ✅
+
+Spawn only — no join yet. Prove a second task executes in the **caller's** address
+space and exits cleanly.
+
+- [x] [abi.zig](../system/abi.zig): `thread_spawn = 37`, `thread_exit = 38`. Handlers in
+      process.zig; `thread_spawn` calls `scheduler.spawnThread` (shares the caller's
+      address space, `retainAddressSpace`); `thread_exit` ends the task like a process `exit(0)`
+      (`terminateCurrent` → `releaseAspace`). The closure pointer is delivered in the new
+      thread's **rdi** via a new `jump_to_user_arg` asm path (`t.user_arg`, 0 for a
+      process) — no naked runtime asm.
+- [x] `library/runtime/thread.zig` (barrel-exported as `runtime.Thread`): `spawn` maps a
+      stack (`mmap`), heap-allocates the `{args}` closure, and calls
+      `thread_spawn(&Closure.entry, stack_top, closure)`; `Closure.entry` (a plain C-ABI
+      Zig fn, closure in rdi) runs the function and calls `thread_exit`. Stack top is
+      16-aligned-minus-8 for the C entry.
+- [x] A `threaded` flag on the user-binary recipe (`addThreadedUserBinary` →
+      `single_threaded = false`); `thread-test` is the first opt-in binary.
+- [x] `-Dtest-case=thread-spawn`: `thread-test` spawns a worker that writes a sentinel to
+      a **shared** global and release-stores `done`; the main thread acquire-polls `done`
+      and asserts the shared global holds the sentinel — proof the worker ran in the same
+      address space.
+
+**Gate (met):** `python3 test/qemu_test.py thread-spawn` passes
+(`thread-test: child ran in shared address space ok` → `DANOS-TEST-RESULT: PASS`); guardrail set
+16/16 green (incl. `args`/`init`/`process`, which exercise the new `jump_to_user_arg`
+process path with arg 0) plus `address-space-refcount`; `zig build` clean, `zig build test`
+green.
+
+> **Note (deferred to M3+):** the mmap arena is per-*task* (`heap_next`), so two threads
+> in one address space that both `mmap` would collide. Fine for M2 (only the parent maps, for the
+> child's stack); make the arena per-address-space and the runtime heap thread-safe alongside the
+> `Mutex` work (M5).
+
+## M3 — `join` + `detach` + real parallelism ✅
+
+- [x] `join` over the existing exit-notification path
+      ([process-lifecycle.md](process-lifecycle.md)): `thread_spawn` gained a 4th arg, an
+      `exit_endpoint` handle (resolved + refcounted like `spawnProcessSupervised`, via
+      `spawnThreadSupervised`); `join` blocks in `ipc_reply_wait` on that endpoint until
+      the child-exit notice for its `tid`, then `munmap`s the stack. `detach` relinquishes
+      the join right (its stack is reclaimed at process exit — kernel-reaper reclaim for
+      detached threads is deferred; see note).
+- [x] `runtime.Thread.join` / `detach`, plus `Thread.currentCore()` (a new `current_core`
+      = 39 syscall) for the parallelism proof. `getCurrentId` deferred to M6 (TLS), where
+      a lighter self-id fits. The closure now rides the **thread's own stack** (not the
+      heap) — private per thread, so spawn/join touch no shared heap.
+- [x] `-Dtest-case=thread-join` (`smp: 4`): `thread-test` join mode spawns N=4 workers
+      that each do K=100k `@atomicRmw`-increments on a shared counter and stamp the core
+      they ran on; the main thread joins all N and asserts `counter == N*K` **and**
+      `@popCount(cores_seen) > 1` (genuine cross-core parallelism), then a detached worker
+      proves `detach` runs without a join.
+
+**Gate (met):** `python3 test/qemu_test.py thread-join` passes (`thread-test: join ok` →
+`DANOS-TEST-RESULT: PASS`), robust across 4 runs; guardrail 17/17 green (incl. `smp`,
+`affinity`, `process-kill`, and `args`/`init`/`process` on the exit-endpoint spawn path)
+plus `address-space-refcount`/`thread-spawn`; `zig build` clean, `zig build test` green.
+
+> **Note (deferred):** a detached thread's stack is freed only at process exit (not by the
+> reaper on thread exit) — kernel user-stack tracking + reclaim is a later refinement. And
+> the runtime heap is still not thread-safe: threads that both allocate concurrently would
+> race (the thread *machinery* avoids the heap, but worker code sharing an allocator does
+> not). Both fold into the M5 `Mutex`/allocator work.
+
+## M4 — Futex: the one blocking primitive ✅
+
+- [x] [abi.zig](../system/abi.zig): `futex_wait = 40`, `futex_wake = 41`. A waiter is a
+      `.blocked` task tagged with `Task.futex_addr` (no queue linkage);
+      `futex_wait(addr, expected, timeout_ns)` reads the user word under the big lock,
+      parks iff `*addr == expected`, and returns on wake or timeout; `futex_wake(addr,
+      count)` scans the task table and readies up to `count` matching waiters (same
+      address space). No spinning — a parked waiter leaves its core free to `hlt`. A
+      timed wait also sets `wake_at`, so the timer's `wakeExpired` wakes it; `futex_addr`
+      staying non-zero (only `futex_wake` clears it) is how the waiter tells timeout from
+      a real wake.
+- [x] `runtime.Thread.Futex` (`wait` / `timedWait` / `wake`) over the syscall wrappers.
+- [x] `-Dtest-case=thread-futex` (`smp: 4`): a waiter thread prints `waiting` and
+      `futex_wait`s on a word; the main thread publishes it, prints `waking`, and
+      `futex_wake`s; the waiter prints `woke`. Then a `timedWait` on an unwoken word
+      reports `error.Timeout`.
+
+**Gate (met):** `python3 test/qemu_test.py thread-futex` passes, robust across 3 runs —
+the case's **ordered** regex asserts `waiting → waking → woke → PASS` on the serial
+stream (the handoff proof), and `thread-futex: timeout ok` confirms the timeout.
+Guardrail 18/18 green (incl. `sleep`/`event`/`ipc` blocking paths) + `address-space-refcount`,
+`thread-spawn`, `thread-join`; `zig build` clean, `zig build test` green.
+
+> **Note:** the kernel test checks only the freshest verdict marker via `bufferHas` (the
+> in-memory log ring buffer evicts older lines); ordering is asserted against the full
+> serial stream by the qemu regex instead.
+
+## M5 — `Mutex` + `Condition` + `Semaphore` ✅
+
+- [x] `runtime.Thread.Mutex` (three-state futex mutex: CAS fast path, `futex_wait`/`wake`
+      slow path), `Condition` (`wait`/`timedWait`/`signal`/`broadcast`, a futex sequence
+      counter), `Semaphore` (permits over `Mutex`+`Condition`) — the same state machines
+      `std.Thread` uses, ported onto our `Futex`.
+- [x] `-Dtest-case=thread-mutex` (`smp: 4`): a bounded producer/consumer — 2 producers +
+      2 consumers over one `Mutex` and two `Condition`s move N=2000 unique items through
+      an 8-slot ring; the consumed checksum and tally match exactly (no lost/duplicated
+      item, no overrun) under real cross-core contention. The small ring forces producers
+      to block on full and consumers on empty, exercising `Condition.wait`.
+
+**Gate (met):** `python3 test/qemu_test.py thread-mutex` passes (`thread-mutex: ok` →
+`DANOS-TEST-RESULT: PASS`), robust across 3 runs; guardrail 17/17 green (incl.
+`sleep`/`event`/`ipc`) + all M1–M4 thread cases; `zig build` clean, `zig build test`
+green.
+
+> **Deferred (with rationale):**
+> - **`join` → futex completion word** — the exit-endpoint join (M3) is correct and
+>   tested. A futex-completion join needs the *kernel* to clear+wake a word after the
+>   thread is fully off its stack (a CLONE_CHILD_CLEARTID-style mechanism); doing it in
+>   the thread's own trampoline would let `join` `munmap` the stack while the thread still
+>   runs on it (use-after-free). Left on the exit-endpoint path; the kernel clear-on-exit
+>   is a later, separate refinement.
+> - **Host unit tests for the state machines** — `Mutex`/`Condition` bottom out in the
+>   `futex_*` syscalls, unavailable on the host without a mockable `Futex` seam. The QEMU
+>   `thread-mutex` gate exercises them under real concurrency instead; a host-side mock is
+>   future work.
+
+## M6 — `getCurrentId`, docs, and CI wiring ✅
+
+- [x] `getCurrentId` via a small `thread_self = 42` syscall (`runtime.Thread.getCurrentId`
+      returns the kernel task id). **Per-thread `threadlocal` TLS is deferred** — no
+      consumer needs it, and it would require context-switching the thread pointer per task
+      (real kernel + per-switch cost) for an unused feature; threaded binaries have run fine
+      without it through M2–M5. threading.md's TLS reasoning already scoped it as
+      deferred-unless-needed. When a consumer appears, the shape is: `thread_spawn`
+      allocates a per-thread TLS block, sets the thread pointer, and the context switch saves/
+      restores it.
+- [x] `RwLock` / `WaitGroup` deferred (no consumer yet); they slot onto the same
+      `Futex`/`Mutex`/`Condition` when wanted.
+- [x] All `thread-*` cases wired into [test/qemu_test.py](../test/qemu_test.py)
+      (`thread-spawn`/`-join`/`-futex`/`-mutex`/`-id`); threading.md + docs/README.md
+      status updated to **built**; the worked example is threading.md's win-condition.
+- [x] `-Dtest-case=thread-id` (`smp: 4`): two workers read `getCurrentId`; the main
+      thread confirms all three ids are non-zero and distinct — each thread has its own
+      kernel identity. (Renamed from `thread-tls`, which implied `threadlocal`.)
+
+**Gate (met):** `python3 test/qemu_test.py thread-id` passes; the whole `thread-*` suite
+(`thread-spawn`/`-join`/`-futex`/`-mutex`/`-id`) plus the full guardrail set pass; default
+`zig build` clean, `zig build test` green.
+
+---
+
+## Status
+
+**Phase 1 (M1–M6): built.** danos has `runtime.Thread` — `spawn`/`join`/`detach`,
+cross-core parallelism, futex, and `Mutex`/`Condition`/`Semaphore`, all over a private
+thread ABI behind the runtime.
+
+**Phase 2 (M7–M11): built.** Thread-safe allocation (M7), a task reaper that reclaims dead
+tasks' kernel stacks (M8), endpoint-free `thread_join` (M9), the per-thread thread pointer (M10),
+and `RwLock`/`WaitGroup` + host-testable sync (M11). Two things stay deferred by design
+(no consumer): the Zig `threadlocal` *compiler* layer (M10) and detached-thread user-stack
+reclaim (M9) — both noted in place.
+
+---
+
+## Phase 2 — hardening (M7–M11)
+
+The organising principle, so Phase 2 reinforces danos's goals rather than eroding them:
+
+- **Everything a thread owns is reclaimed on process death.** Thread stacks, TLS blocks,
+  and futex words live in the process's **address space**, and the kernel's per-process
+  state is keyed by the address-space root — so the M1 refcount + `destroyAddressSpace` already
+  free all of it when the last thread exits. A crashed or killed threaded process leaves
+  **nothing** behind. Phase 2 closes the one thing that is *not* address-space-owned — the
+  per-task **kernel** stack (kernel heap) — with a reaper (M8). This is the
+  [resilience](resilience.md) restart guarantee, extended to threads.
+- **Kernel owns mechanism; the runtime owns policy.** The kernel maps pages, saves/
+  restores the thread pointer, and reaps dead tasks; the runtime decides allocation, TLS layout,
+  and lock algorithms. Every new kernel entry stays a private syscall behind the runtime
+  ([syscall.md](syscall.md)) — the ABI stays renumberable.
+- **The process is still the isolation and restart boundary.** Threads share fate within
+  one process; Phase 2 never adds a way for one process to reach into another (the
+  cross-process futex stays explicitly out of scope, below).
+
+### M7 — Thread-safe allocation (the correctness gap) ✅
+
+Today the mmap arena cursor is per-*task* and the runtime heap is unlocked, so two
+threads in one process that both allocate corrupt each other. The thread *machinery*
+avoids this (closure on the stack, stacks mmap'd only by the spawner), but real
+multi-threaded code would hit it. Closed it:
+
+- [x] **Kernel — per-address-space mmap arena.** Grew M1's `address_space_refs` entry into the
+      per-address-space object holding the `mmap`/`mmio` arena cursors (moved off `Task`);
+      `scheduler.addressSpaceMmapNextPtr`/`addressSpaceDeviceMapNextPtr` expose them. `systemMmap`
+      reserves a disjoint range under a *brief* lock, then maps **per page** under a
+      short-held lock — not the whole grant — because the big lock is held with interrupts
+      disabled, so pinning it across a multi-MiB memset+map froze other cores (it timed
+      the `affinity` scenario out mid-bring-up). Freed at refcount zero, so the cursors
+      vanish with the process.
+- [x] **Runtime — thread-safe heap.** The allocator's two free-list mutators
+      (`rawAlloc`/`rawFree`) take a `Thread.Mutex`, gated on
+      `!@import("builtin").single_threaded` so single-threaded binaries compile it out and
+      pay nothing. Uncontended acquisition is a single CAS (no syscall).
+- [x] `-Dtest-case=thread-alloc` (`smp: 4`): 4 threads each do 500 `alloc`/fill/verify/
+      `free` cycles of varied sizes; each block is filled with a per-thread pattern and
+      verified before free, so any overlap between concurrent allocations is caught.
+
+**Gate (met):** `thread-alloc` passes (3× non-flaky); full guardrail 23/23 green,
+`zig build`/`zig build test` clean.
+
+> **Also fixed here:** the `affinity` guardrail's fixed-count busy-loop (`while (spins <
+> 3e9)`) had codegen-dependent wall-time — adding a function to `tests.zig` flipped how
+> the optimiser compiled it, swinging affinity from ~4 s to ~63 s and timing it out.
+> Reworked it (and the settle loop) to wait on the wall clock instead, so its duration is
+> independent of unrelated code changes.
+
+### M8 — The task reaper (cleanup + resilience) ✅
+
+A dead task's **kernel** stack was leaked ("no reaper yet") — every process *and* thread
+death lost one, so a crash loop bled kernel memory. The reaper fixes it and serves the
+[resilience](resilience.md) restart goal directly:
+
+- [x] A dying task cannot free the kernel stack it runs on, so `exit()`/`exitUserLocked`
+      record it in a **per-core `reap_after_switch` slot** and switch away; the task that
+      resumes on that core frees the stack in `switchTo`'s tail (it's on its own stack, the
+      big lock is still held so the slot can't have been reused). A **tick-time drain**
+      (`reapKillPendingLocked`) is the safety net for the case where the next task is
+      *fresh* (enters via the trampoline, bypassing `switchTo`'s tail). A task killed while
+      *not* running is freed immediately in `destroyTaskLocked`. A `live_stack_bytes`
+      counter is the observable. *(Detached-thread user-stack reclaim moves to M9, which
+      adds the joinable/detached flag.)*
+- [x] `-Dtest-case=task-reap` (`smp: 4`): spawn and kill 12 processes; poll the
+      test-observable `scheduler.liveStackBytes()` until it returns to **baseline** (a
+      correct reaper gets there in a few ms; a genuine leak times out) — every kernel
+      stack reclaimed, no leak. Threads exit through the same `exitUserLocked`, so covered.
+
+**Gate (met):** `task-reap` passes (5× isolated + 2× in the full batch); `fault-recovery`,
+`supervision`, `process-kill`, `address-space-refcount`, `smp`, `affinity` all still green (24/24
+full guardrail); `zig build`/`zig build test` clean.
+
+> **Bug found + fixed here (touches every context switch):** the post-`switchContext` reap
+> first read the `pc` **parameter**, but a task that migrated cores carries a *stale* `pc`
+> in its saved `switchTo` frame — so it read the wrong core's slot and freed a live stack
+> (a #GP under SMP). Fixed to re-fetch `thisCpu()` after the switch (the switch only swaps
+> stacks on the current core).
+
+### M9 — Futex-completion join (retire the per-thread endpoint)
+
+With the reaper (M8) able to act *after* a thread is fully off its stack, migrate `join`
+to the std shape and drop M3's per-thread exit endpoint:
+
+- [x] A **`thread_join(tid)` syscall** (not a user futex word): it blocks the caller until
+      the task with id `tid` exits, and the exit paths call `wakeJoinersLocked`. `join`
+      only reclaims the joined thread's **user** stack, which the thread vacates the moment
+      it enters the kernel to exit — so waking at *exit* time (not reap time) is safe, and
+      no reaper/address-space juggling or user-memory write is needed. This is equally
+      std-shaped (like `pthread_join`) and much simpler/safer than the planned
+      reaper-written completion word. `thread_spawn` no longer takes an exit endpoint (the
+      runtime passes `no_cap`); the per-thread IPC endpoint is gone.
+- [x] `thread-join` passes on the new path, and its join mode now runs **40 spawn+join
+      cycles** — under the old per-thread-endpoint scheme those leaked handles would
+      exhaust the 16-slot handle table; here they all succeed, proving join is endpoint-free.
+
+**Gate (met):** `thread-join` passes (3× isolated) on the `thread_join` path; full
+guardrail 26/26 (incl. `process-kill`, `supervision`, `fault-recovery`, `task-reap`);
+`zig build`/`zig build test` clean.
+
+> **Reaper hardened here (fixes an M8 flake).** M8's single per-core reap slot could be
+> *overwritten* by a second death on that core before the first drained (a fresh-task/SMP
+> timing window) — an intermittent one-stack leak (`task-reap` flaked ~20%). Replaced it
+> with a per-core reap **list** plus a `.reaping` task state so a pending slot can't be
+> reused before its stack is freed. `task-reap` now 11/11 isolated + 2× in the batch.
+
+> **Deferred:** detached-thread **user-stack** reclaim (still freed at process exit, as in
+> M3). Doing it in the reaper needs the saved address space + stack range and a
+> translate/unmap in a not-currently-loaded address space — real complexity for a bounded leak.
+> A follow-up when a consumer needs it.
+
+### M10 — Per-thread TLS: the thread-pointer mechanism ✅
+
+Give each thread its own thread pointer and private TLS storage — the foundation
+self-hosting Zig ([zig-self-hosting.md](zig-self-hosting.md)) will build `threadlocal` on.
+
+- [x] **Kernel** stores `thread_pointer` on `Task` and restores it on every context switch
+      **only when it changes** (the same conditional-load discipline as CR3;
+      `architecture.setThreadPointer` → `wrmsr IA32_FS_BASE` on x86_64). A
+      `set_thread_pointer(addr)` = 44 syscall sets the caller's `thread_pointer` and loads it
+      now. The kernel never touches FS, so there is no swapgs complication.
+- [x] **Runtime** lays a small per-thread TLS block at the top of each thread's stack
+      (self-pointer at `%fs:0` + scratch slots) and the thread trampoline calls
+      `set_thread_pointer` before any user code — so every spawned thread has a private,
+      switch-stable thread pointer. Reclaimed with the stack.
+- [x] `-Dtest-case=thread-tls` (`smp: 4`): two threads each write a unique marker to their
+      own `%fs:8` slot and — after both have written — read it back; a shared (non-per-thread)
+      FS base would clobber one and cause cross-talk. Both read their own marker → pass.
+
+**Gate (met):** `thread-tls` passes (3×); full guardrail 25/25 (the switch-time thread-pointer
+restore touches every context switch); `zig build`/`zig build test` clean.
+
+> **Deferred: the Zig `threadlocal` *compiler* layer.** Real `threadlocal` variables need
+> the ELF **variant-II TLS** surface — `.tdata`/`.tbss` sections + a `PT_TLS` program header
+> in `user.ld`, a runtime that copies the template with exact negative-offset layout, and
+> the `.large`-code-model TLS section names — a high-uncertainty lift for a feature with
+> **no consumer today** (threading.md scopes it "only if a consumer needs it"). What lands
+> here is the load-bearing piece — the per-thread thread pointer, context-switched — so adding the
+> compiler layer later is purely runtime+linker work on top, no kernel change. `getCurrentId`
+> stays the `thread_self` syscall (M6) rather than an fs self-slot (which would need the
+> main thread's TLS set up in `_start` too).
+
+**Gate:** `thread-tls` passes; full `thread-*` suite + guardrail green.
+
+### M11 — `RwLock`, `WaitGroup`, and host-testable sync ✅
+
+- [x] `runtime.Thread.RwLock` (reader-preferring: `>0` readers / `-1` writer / `0` free,
+      with `lock`/`tryLock`/`unlock` + `lockShared`/`tryLockShared`/`unlockShared`) and
+      `WaitGroup` (`start`/`finish`/`wait`), both on the existing `Mutex`/`Condition`.
+- [x] A compile-time `Futex` seam gated on `builtin.os.tag == .freestanding`: the futex
+      syscalls on danos, a spin+yield mock off-target (Zig 0.16 has no `std.Thread.Futex`;
+      `wake` is a no-op since the state machines re-check). `thread.zig` is wired into
+      `zig build test`, so `Mutex`/`RwLock`/`WaitGroup` run as **host unit tests** with real
+      `std.Thread` threads (`test` blocks only compile under test).
+- [x] `-Dtest-case=thread-rwlock` (`smp: 4`): 2 writers set both halves of a value under
+      the exclusive lock while 3 readers check the halves match under the shared lock —
+      zero half-write observations across ~150k reads. Host tests cover the Mutex,
+      RwLock, and WaitGroup state machines.
+
+**Gate (met):** `zig build test` covers the sync primitives (host threads); `thread-rwlock`
+passes (3×); full Done gate **26/26** (whole `thread-*` suite + guardrail); `zig build`
+clean.
+
+---
+
+## Deferred (explicitly not in this plan)
+
+- **Cross-process shared-memory futex** — the `(address_space, virtual_address)` key can become a
+  physical-address key so two processes share a futex through an [shm](display-v2.md)
+  region. Not needed for intra-process threads.
+- **Per-thread priorities / affinity distinct from the process** — threads inherit the
+  process priority ([scheduling.md](scheduling.md)); revisit only if it earns its keep.
+- **Per-thread signal delivery** — signals stay process-scoped
+  ([process-lifecycle.md](process-lifecycle.md)).
+- **A `pthread`/POSIX surface** — the API is `std.Thread`-shaped Zig, nothing more.
+- **A real `std.Thread` backend** — arrives with self-hosting
+  ([zig-self-hosting.md](zig-self-hosting.md)); it sits on these same primitives, so it
+  swaps the impl under `runtime.Thread`, not the call sites.

docs/threading.md

@@ -0,0 +1,317 @@
+# Threading: `runtime.Thread`, a std-shaped API over a private thread ABI
+
+A note on danos **threads** — several tasks sharing one address space — provided by a
+`runtime.Thread` type that mirrors the shape of Zig's `std.Thread` while keeping every
+kernel entry behind the [runtime](../library/runtime). **Built** (M1–M11, see
+[threading-plan.md](threading-plan.md)): `spawn`/`join`/`detach`, cross-core parallelism,
+a futex, `Mutex`/`Condition`/`Semaphore`/`RwLock`/`WaitGroup`, `getCurrentId`/`currentCore`,
+per-thread thread-pointer TLS, thread-safe allocation, and a task reaper that reclaims dead
+tasks' kernel stacks. Deferred by design (no consumer yet): the Zig `threadlocal`
+*compiler* layer (the per-thread thread pointer is in place, so it's runtime+linker work on top) and
+detached-thread user-stack reclaim — see the plan's M9/M10 notes. The analysis is against
+**Zig 0.16** (the pinned toolchain); `std.Thread`'s internals move between releases, so
+treat upstream shapes as "0.16.x."
+
+## The win condition
+
+A danos service can write
+
+```zig
+const t = try runtime.Thread.spawn(.{}, worker, .{ctx});
+// ... do other work concurrently ...
+t.join();
+```
+
+and get real parallelism across cores — with `runtime.Thread.Mutex`,
+`runtime.Thread.Condition`, and `runtime.Thread.Semaphore` available for
+coordination — **without any code path reaching the kernel except through the
+runtime**. The call sites read exactly like `std.Thread`, so the day danos becomes a
+real Zig target (see [self-hosting](#the-self-hosting-endgame)) we swap the
+implementation underneath, not the API above.
+
+## Locked decisions (do not relitigate)
+
+- **We build `runtime.Thread`, not literal `std.Thread`.** It mirrors std's *API and
+  features*; the implementation underneath is danos-native. See
+  [Why not literal std.Thread](#why-not-literal-stdthread).
+- **Threads are a narrow, opt-in capability — not the default concurrency tool.** The
+  default for resilience stays **process + IPC** ([resilience.md](resilience.md),
+  [ipc.md](ipc.md)). See [Where threads fit](#where-threads-fit-the-resilience-tension).
+- **Blocking synchronization is futex-backed, never spin-backed.** Waiters sleep in
+  the kernel so an idle core still halts ([halting.md](halting.md)).
+- **Per-binary opt-in to multi-threaded codegen.** Only a service that asks for
+  threads is built `single_threaded = false`; the rest stay lean and single-threaded.
+- **The thread ABI is private.** New syscalls extend [abi.zig](../system/abi.zig)
+  `SystemCall` and are reached only through `library/runtime` wrappers, exactly like
+  every other danos syscall ([syscall.md](syscall.md)) — numbers stay renumberable.
+
+## Why not literal `std.Thread`
+
+danos's ABI invariant is that the **runtime is the sole holder of the syscall ABI**,
+and that ABI is private and renumberable ([syscall.md](syscall.md) — "unstable
+private ABI"). That is a security and evolvability asset: no compiled binary can
+hardcode a syscall number, and the kernel can renumber freely because only the
+runtime — rebuilt in lockstep — knows the mapping.
+
+`std.Thread` is incompatible with that invariant on two counts:
+
+1. **It selects its backend from `builtin.os.tag`, and issues syscalls directly.**
+   danos targets `.os_tag = .freestanding` ([build.zig](../build.zig)), for which
+   `std.Thread` resolves to an unsupported stub that `@compileError`s. Adding a real
+   backend would either bake danos syscall numbers into std (breaking ABI privacy and
+   renumbering) or fork std to route back through the runtime — a permanent rebase
+   cost that buys nothing the native type doesn't.
+2. **Our user binaries are built `single_threaded = true`** ([build.zig](../build.zig)
+   `addUserBinary`), which compiles threading out entirely and makes atomics and TLS
+   single-threaded. Threads need this flipped per binary regardless.
+
+So we take the *shape* of `std.Thread`, not the *type*. The cost of replicating the
+surface (spawn/join/Mutex/Condition) is small; the cost of the std type is the ABI
+invariant.
+
+## Where threads fit: the resilience tension
+
+Threads are in genuine tension with a resilience-first microkernel, and it is worth
+being explicit so we do not reach for them by reflex.
+
+The reason danos pays for a microkernel is **fault isolation**
+([resilience.md](resilience.md)): a component corrupts its own address space, faults,
+and is **restarted** without touching anyone else — because the boundary *is* the
+address space. Threads deliberately remove that boundary *within* a process:
+
+- Threads share one address space, so one thread's stray write corrupts them all —
+  there is no isolation **between** threads.
+- Threads share fate: a fault in any thread, or a "kill the process" decision, takes
+  down **all** of them. Restartability lives at the process level, not the thread
+  level.
+- Shared mutable state reintroduces data races — the failure class the
+  isolate-and-message model was chosen to avoid.
+
+**Therefore:** the default answer to "make X concurrent" stays *another process over
+IPC* (isolated, independently restartable) or a single event loop with several
+message sources. Reach for a thread only inside **one** service that needs genuine
+**shared-memory, low-latency parallelism** and can accept intra-service fate-sharing —
+e.g. a compositor splitting tile compositing across cores, where per-tile IPC would be
+too chatty. "Input on one thread, display on another" is *not* that case; it wants two
+processes. The isolation boundary stays at process granularity.
+
+## The API surface (mirrors `std.Thread`)
+
+Lives in `library/runtime/thread.zig`, re-exported as `runtime.Thread`.
+
+```zig
+pub const Thread = struct {
+    pub const Id = u32;                       // the kernel task id
+    pub const SpawnConfig = struct {
+        stack_size: usize = default_stack_size,
+        allocator: ?std.mem.Allocator = null, // for the closure + stack bookkeeping
+    };
+    pub const SpawnError = error{ OutOfMemory, ThreadQuotaExceeded, SystemResources };
+
+    pub fn spawn(config: SpawnConfig, comptime function: anytype, args: anytype) SpawnError!Thread;
+    pub fn join(self: Thread) void;           // block until the thread ends, reclaim its stack
+    pub fn detach(self: Thread) void;         // give up the right to join; kernel reclaims on exit
+    pub fn getCurrentId() Id;
+    pub fn yield() void;                       // -> existing `yield` syscall
+
+    pub const Mutex     = struct { pub fn lock(*Mutex) void; pub fn tryLock(*Mutex) bool; pub fn unlock(*Mutex) void; };
+    pub const Condition = struct { pub fn wait(*Condition, *Mutex) void; pub fn timedWait(*Condition, *Mutex, u64) error{Timeout}!void; pub fn signal(*Condition) void; pub fn broadcast(*Condition) void; };
+    pub const Semaphore = struct { pub fn wait(*Semaphore) void; pub fn post(*Semaphore) void; };
+    pub const Futex     = struct { pub fn wait(*const atomic.Value(u32), u32) void; pub fn timedWait(...) error{Timeout}!void; pub fn wake(*const atomic.Value(u32), u32) void; };
+    // RwLock / ResetEvent / WaitGroup follow the same pattern, added as needed.
+};
+```
+
+Deviations from `std.Thread`, called out honestly:
+
+- **The thread function's return value is discarded** (as `std.Thread.join` returns
+  `void`). Return data through shared state or a `Semaphore`/`Condition`, not the
+  return.
+- `getCpuCount()` maps to the existing SMP core count ([smp.md](smp.md)); a service
+  rarely needs it.
+
+## Kernel primitives (new private syscalls)
+
+Four new entries extend [abi.zig](../system/abi.zig) `SystemCall` after
+`shm_physical = 36`, each with a `library/runtime` wrapper:
+
+| Syscall | Signature | Purpose |
+|---|---|---|
+| `thread_spawn` | `(entry, stack_top, arg) -> tid` | create a task sharing the **caller's** address space |
+| `thread_exit`  | `(stack_base, stack_len)` | end the calling thread; hand back its stack range for reclaim |
+| `futex_wait`   | `(addr, expected, timeout_ns) -> status` | block if `*addr == expected`, until woken or timeout |
+| `futex_wake`   | `(addr, count) -> woken` | wake up to `count` waiters on `addr` |
+
+Plus one invariant change with no new syscall: **address-space reference counting**.
+
+## Mechanics
+
+### Address-space reference counting
+
+Today an address space is 1:1 with a task: `spawnUserLocked` records `address_space` on the
+Task, and teardown does `destroyAddressSpace(t.address_space)` when **any** user task exits
+([scheduler.zig](../system/kernel/scheduler.zig)). With threads, several tasks share
+one `address_space`, so the first to exit would rip the address space out from under its
+siblings.
+
+Fix: a small refcount keyed by the address-space root (`createAddressSpace` in
+[process.zig](../system/kernel/process.zig) sets it to 1). `thread_spawn` increments
+it; task teardown decrements and only calls `destroyAddressSpace` at **zero**. All of
+this is already under the big kernel lock, so no new locking. This is the one piece
+that must land and be proven before anything shares an address space.
+
+### `thread_spawn` and the trampoline
+
+The scheduler already accepts an arbitrary `address_space` and does **not** smuggle values
+through registers — `startUserTask` reads the entry/stack from the Task and
+`jumpToUser`s ([scheduler.zig](../system/kernel/scheduler.zig)). That makes the thread
+path clean:
+
+1. The runtime's `spawn` `mmap`s a stack (syscall `4`), heap-allocates a closure —
+   `{ fn_ptr, args_tuple, completion }`, the std "Instance" pattern — and writes the
+   closure pointer to the **top word of the new stack**.
+2. It calls `thread_spawn(entry = &threadTrampoline, stack_top, arg = closure_ptr)`.
+   The kernel calls the same `spawnUserLocked` path with the **caller's address space**
+   (refcount++), `entry`, and `user_sp = stack_top`.
+3. `threadTrampoline` (a small runtime shim) reads the closure off its stack, calls
+   the user function, then calls `thread_exit`. No new register ABI — the closure
+   pointer rides the stack the runtime set up, mirroring how `startUserTask` avoids
+   register smuggling.
+
+Unlike a process start, there is **no** System V argc/argv/auxv block
+([sysv.md](sysv.md)) — a thread stack carries only the closure pointer.
+
+### Lifetime: exit, join, detach, stack reclaim
+
+- **`thread_exit`** marks the task dead and hands the kernel the thread's user-stack
+  range. The kernel reaps the task on the scheduler (already running on a *kernel*
+  stack, so it can safely unmap the user stack), decrements the address-space refcount, and
+  frees the task slot.
+- **`join` — Stage 1** reuses the existing exit-notification machinery
+  ([process-lifecycle.md](process-lifecycle.md)): `spawn` passes a per-thread
+  `exit_endpoint`, and `join` blocks in `ipc_reply_wait` until the child-exit
+  notification for that `tid` arrives, then `munmap`s the stack. No futex needed to
+  land spawn/join.
+- **`join` — Stage 2 refinement** migrates to the std shape: a `completion` word in
+  the closure that `thread_exit`'s trampoline `futex_wake`s and `join` `futex_wait`s
+  on — dropping the per-thread endpoint. Kept as a refinement so Stage 1 ships first.
+- **`detach`** relinquishes the join right; the kernel reclaims the stack and slot on
+  `thread_exit` (a detached thread's stack range is unmapped by the reaper, since no
+  joiner will).
+
+### Futex, and the sync primitives on top
+
+`futex_wait`/`futex_wake` are the one blocking primitive; `Mutex`, `Condition`, and
+`Semaphore` are ordinary user-space state machines over an `atomic.Value(u32)` that
+call the futex wrappers on the slow path — the same construction `std.Thread` uses,
+so the algorithms port directly.
+
+Keying: threads share an address space, so a **virtual address within that address space**
+identifies a futex uniquely; the kernel keys its wait queue by `(address_space_root, virtual_address)`.
+Keying by the **physical** address instead (translate `virtual_address -> physical_address` on entry) is a
+deliberate forward door: it lets two *processes* share a futex through an
+[shm](display-v2.md) region later, without changing the API. We start with the
+private-per-address-space key and note the physical-key upgrade.
+
+No spinning: a contended lock parks the task in the kernel and the core is free to run
+other work or `hlt` ([halting.md](halting.md)). This is why futex is a locked
+decision, not a "maybe later."
+
+### TLS and `getCurrentId`
+
+danos sets up no thread-pointer TLS today (fine under `single_threaded`). Two scoped needs:
+
+- **`getCurrentId`** returns the kernel task id — either a trivial syscall or, better,
+  a value the runtime stashes in a per-thread control block.
+- **`threadlocal` variables** need a real per-thread TLS block and the thread pointer set per
+  thread. `thread_spawn` sets the thread pointer to a runtime-allocated per-thread block; full
+  `threadlocal` support is Stage 3, only if a consumer needs it. Nothing in the core
+  spawn/join/mutex path requires `threadlocal`.
+
+### Build: multi-threaded codegen, opt-in
+
+`addUserBinary` gains a `threaded: bool = false` parameter; when set it builds that
+binary `single_threaded = false` so atomics and (later) TLS are real. Threads and
+atomics are unsound in a `single_threaded` image, so a binary must opt in **before**
+it may call `runtime.Thread.spawn`. Everyone else stays single-threaded and lean.
+
+## Interaction with the rest of the kernel
+
+- **Scheduler / SMP** ([scheduling.md](scheduling.md), [smp.md](smp.md)): a thread is
+  just another `Task` with an `address_space` shared with its siblings; the existing
+  per-core ready queues, priorities, and affinity apply unchanged. Threads of one
+  process can run on different cores simultaneously — that is the point.
+- **Halting** ([halting.md](halting.md)): futex-parked waiters keep the "idle core
+  halts" property intact under lock contention — no busy-wait.
+- **Lifecycle** ([process-lifecycle.md](process-lifecycle.md)): killing a process
+  must kill *all* its threads and only then drop the last address-space ref. The kill path
+  already targets a process; it fans out to every task on that address space.
+- **Resilience** ([resilience.md](resilience.md)): a faulting thread kills its whole
+  process (shared fate). The supervisor restarts the **process**, which respawns its
+  threads from a known-good state — restart granularity stays the process.
+
+## Build-out plan (staged, each gate serial-checkable)
+
+The ordered, `/loop`-runnable milestones live in
+**[threading-plan.md](threading-plan.md)** (shaped like
+[display-v2-plan.md](display-v2-plan.md)): every milestone lands on its own and ends in
+a verifiable gate (`python3 test/qemu_test.py <case>`, asserting serial markers;
+`zig build test` for host unit tests). The stages below are the shape it expands.
+
+- **Stage 0 — address-space refcount.** Refcount on the address-space root; teardown destroys
+  at zero. No API yet; nothing shares an address space, so refcount is 1 everywhere.
+  *Gate:* the full QEMU suite stays green (no regression) — proves the reframing is
+  invisible until used.
+- **Stage 1 — spawn / join / detach.** `thread_spawn` + `thread_exit`, the trampoline,
+  stacks via `mmap`, join over the exit-endpoint, the `threaded` build flag.
+  *Gate:* `-Dtest-case=thread-spawn` — a threaded test service spawns N threads that
+  each `@atomicRmw`-increment a shared counter, the parent joins all N, and asserts
+  the total is exactly N × iterations. Runs `smp` (multi-core) to prove real
+  parallelism.
+- **Stage 2 — blocking synchronization.** `futex_wait`/`futex_wake` + `Futex`,
+  `Mutex`, `Condition`, `Semaphore`; optionally migrate join to a futex completion
+  word. *Gate:* `-Dtest-case=thread-mutex` — a bounded producer/consumer over a
+  `Mutex` + `Condition` moves K items with no lost wakeups and no busy-wait (assert
+  the consumer blocked, e.g. via a low idle tick count).
+- **Stage 3 — polish.** Per-thread TLS / thread pointer and `threadlocal` (only if a
+  consumer needs it), `RwLock`/`WaitGroup` as demanded, and this doc's cases wired
+  into [test/qemu_test.py](../test/qemu_test.py).
+
+## Conventions
+
+Follow [coding-standards.md](coding-standards.md): spell out non-acronym
+abbreviations, kebab-case file names, no `Co-Authored-By` trailers. New syscalls
+extend [abi.zig](../system/abi.zig) `SystemCall` + a `library/runtime` wrapper
+([syscall.md](syscall.md)). `runtime.Thread` is a first-class runtime module, the same
+way `runtime.process` ([process-lifecycle.md](process-lifecycle.md)) and `runtime.ipc`
+are — user code never names a syscall.
+
+## Non-goals
+
+- **No preemptive user-space signals delivered to a specific thread.** Signals stay
+  process-scoped ([process-lifecycle.md](process-lifecycle.md)).
+- **No thread priorities distinct from the process.** Threads inherit the process
+  priority; per-thread priority is a later question if it ever earns its keep.
+- **No cross-process shared-memory futex yet** — the physical-address key leaves the
+  door open, but the first cut is private-per-address-space.
+- **No `pthread`/POSIX surface.** The API is `std.Thread`-shaped Zig, nothing more.
+
+## The self-hosting endgame
+
+When danos becomes a real Zig target and we (eventually) add a danos backend to std
+([zig-self-hosting.md](zig-self-hosting.md)), `std.Thread` can sit *on top of* these
+same kernel primitives — the danos `std.Thread.Impl` would call the very
+`thread_spawn`/`futex_*` wrappers `runtime.Thread` already uses. Because
+`runtime.Thread` was built API-compatible from day one, that transition swaps the
+implementation, not a single call site. Designing to the std shape now is what makes
+the later self-hosting lift cheap.
+
+## Further reading
+
+- [scheduling.md](scheduling.md), [smp.md](smp.md) — the task model these threads join.
+- [resilience.md](resilience.md), [vision.md](vision.md) — why isolation is the default
+  and threads are the exception.
+- [syscall.md](syscall.md), [ipc.md](ipc.md) — the private ABI and the messaging model
+  threads sit beside.
+- [halting.md](halting.md) — the idle/halt property futex-backed blocking preserves.
+- [zig-self-hosting.md](zig-self-hosting.md) — the target this bends toward.

docs/vdso.md

@@ -0,0 +1,206 @@
+# The vDSO — the public system-call boundary
+
+> **Status:** design note, not built. The runtime today issues raw `syscall`
+> instructions from `library/runtime/system-call.zig` using the numbers in
+> `system/abi.zig`. This note designs the layer that replaces that arrangement:
+> a **kernel-supplied, C-ABI entry library** mapped into every process — the
+> only supported way into the kernel — so the raw numbers can stay private,
+> be renumbered at will, and eventually be randomised per boot.
+
+## Why: the ABI danos promises, and the one it doesn't
+
+`system/abi.zig` is the **private** kernel ↔ runtime contract. Its header says
+so: the numbers are an implementation detail the runtime hides and may
+renumber, the same split as libSystem over the XNU syscalls on macOS or win32
+over the NT syscalls on Windows. Linux — with its world-visible, frozen
+syscall table — is the outlier, not the norm.
+
+That stance has consequences the moment binaries exist that we don't rebuild
+ourselves:
+
+1. **Third-party binaries** (docs/zig-self-hosting.md) must keep working across
+   kernel updates. If they contain raw `syscall` instructions with today's
+   numbers baked in, every renumbering breaks the world — the ABI would be
+   *de facto* public no matter what the header says. Go on macOS made exactly
+   this mistake: it issued XNU syscalls directly instead of going through
+   libSystem, and macOS updates repeatedly broke every Go binary until Go
+   switched to the library like everyone else.
+2. **Not everything is Zig.** A Rust or C program can't import the `runtime`
+   module. The public boundary has to be expressible in the one calling
+   convention every language speaks: the C ABI.
+3. **Randomised syscall numbers** — a hardening option we want open — only
+   work if no user binary anywhere knows a number at build time. The binding
+   must happen at *load time*, from something the kernel controls.
+
+All three point at the same well-known shape: a **vDSO** (virtual dynamic
+shared object). The kernel carries a small blob of user-mode code, maps it
+into every process at spawn, and that blob — not the application — contains
+the `syscall` instructions. Fuchsia works exactly this way: its vDSO is the
+*only* kernel entry, version-matched by construction because the kernel itself
+injects it. Because the kernel and the blob ship as one artifact, there is
+**no version skew, no loader, no search path, and no shared file on disk** —
+which is what makes this the resilient way to have a private ABI
+(docs/resilience.md), where a conventional `ld.so` + `/lib/libdanos.so`
+arrangement would add a loader to every spawn and a single shared point of
+failure.
+
+The public danos ABI then has exactly two layers, neither of which is
+`abi.zig`:
+
+| Layer | Contract | Spoken by |
+|-------|----------|-----------|
+| **vDSO** | C-ABI functions, this note | every language's thin shim (`runtime.system` for Zig, a `-sys` crate for Rust, a header for C) |
+| **IPC wire protocols** | byte layouts over `ipc_call` ([vfs-protocol.md](vfs-protocol.md) is the first one documented) | any client that can lay out bytes |
+
+Everything above those — the heap, `runtime.fs`, the service harness — is
+per-language convenience, compiled into each binary from source, exactly as
+today. Nothing about the Zig runtime's shape changes; it just stops being the
+*only* door.
+
+## The blob
+
+A single copy of the vDSO code lives in the kernel image (built by
+`build.zig` as a tiny freestanding object, embedded like the AP trampoline).
+At boot the kernel finalises it once — this is where randomised numbers would
+be patched in — and thereafter maps the **same physical pages** read-execute
+into every process's address space. The blob is:
+
+- **Position-independent.** It is mapped at a per-process randomised base, so
+  it must be PIC (rip-relative addressing only — no relocations to process).
+- **Stateless and re-entrant.** No writable data. Anything stateful belongs to
+  the process, not the vDSO.
+- **Architecture-specific.** The x86-64 blob wraps `syscall`; an aarch64 blob
+  wraps `svc #0`. It lives beside the other per-architecture kernel sources
+  (`system/kernel/architecture/<arch>/`), selected the same way the
+  `architecture` module is (docs/arch.md).
+
+### Shape: a function table, not an ELF
+
+A real `.so` with a dynamic symbol table is the conventional vDSO shape, but
+linking against one at load time needs a dynamic linker in every binary —
+machinery danos deliberately doesn't have. Instead the v1 shape is the
+simplest thing that is still a stable contract — a **function-pointer table**
+at the vDSO base:
+
+```
+offset 0   u64  magic        'danosVDS' — a mapped-the-wrong-thing guard
+offset 8   u64  api_level    incremented when the table grows
+offset 16  u64  count        number of table entries that follow
+offset 24  u64  table[count] function pointers into the vDSO's own code
+```
+
+Table *indices* are the public constants (published in a C header,
+`danos.h`), assigned once and append-only — the same discipline the IPC
+protocols use for operation values. The pointers point at stubs inside the
+blob; what those stubs put in `rax` is nobody's business but the kernel's.
+A language shim binds in one step: read the base from the init block, check
+the magic, keep the table pointer. Feature detection for a binary built
+against older headers is `count`/`api_level` — a kernel never removes or
+reorders entries.
+
+(If danos ever grows a real dynamic linker, the same blob can additionally
+present an ELF `dynsym` without breaking the table — Fuchsia's vDSO is
+likewise both a mappable blob and a linkable `.so`. That is a later
+convenience, not a requirement.)
+
+### Delivery: the auxiliary vector
+
+The kernel already builds a System V entry block — argc, argv, envp
+terminator, **auxiliary vector** — on every new process's stack
+(`buildEntryStack`, read by `runtime.start`). The vDSO base rides in a new
+auxv entry, exactly Linux's `AT_SYSINFO_EHDR` move. No new syscall, no magic
+address, and a language shim finds it the same portable way on every
+architecture.
+
+## The function surface
+
+One table entry per kernel call, C ABI (System V AMD64), names prefixed
+`danos_`. The current `SystemCall` set maps directly; integer arguments and
+returns are `u64`, errors return as negative values exactly as today.
+
+The calls that return two values in `rax:rdx` today — `dma_alloc`
+(virtual_address + physical_address), `msi_bind` (address + data), `shm_create` (virtual_address + handle) —
+become functions returning a two-`u64` struct. The System V ABI returns a
+16-byte struct in `rax:rdx`, so the stub is a plain `syscall; ret` — the
+C-ABI spelling of the existing convention, at zero cost.
+
+Grouped as `abi.zig` groups them:
+
+| Group | Functions |
+|-------|-----------|
+| process | `danos_exit`, `danos_yield`, `danos_sleep`, `danos_spawn`, `danos_process_enumerate`, `danos_process_kill`, `danos_process_exit_reason`, `danos_process_subscribe`, `danos_process_signal`, `danos_signal_bind` |
+| memory | `danos_mmap`, `danos_munmap`, `danos_dma_alloc`, `danos_dma_free`, `danos_shm_create`, `danos_shm_map`, `danos_shm_physical` |
+| ipc | `danos_endpoint_create`, `danos_ipc_register`, `danos_ipc_lookup`, `danos_ipc_call`, `danos_ipc_reply_wait`, `danos_ipc_send` |
+| devices | `danos_device_enumerate`, `danos_device_claim`, `danos_device_register`, `danos_mmio_map`, `danos_irq_bind`, `danos_irq_ack`, `danos_msi_bind`, `danos_io_read`, `danos_io_write` |
+| time | `danos_clock`, `danos_wall_clock`, `danos_timer_bind` |
+| diagnostics | `danos_debug_write`, `danos_klog_read` |
+
+The constants that ride alongside the calls — mmap protection bits, DMA
+flags, notification badge bits, `ExitReason`, `Signal`, well-known service
+ids, `page_size`, the IPC message maximum — move to the public header too:
+they are wire values a Rust program needs verbatim. What stays private in
+`abi.zig` is exactly the thing the vDSO exists to hide: the `SystemCall`
+numbers and the trap convention.
+
+## Enforcement, and an honest threat model
+
+Renumbering only has teeth if the kernel **refuses syscalls that don't come
+from the vDSO**. The check is cheap: on kernel entry, the saved user `rip`
+must lie inside the calling process's vDSO mapping; otherwise the process is
+killed with a fault-class exit reason (its supervisor restarts or gives up,
+docs/process-lifecycle.md — a foreign-syscall attempt is a bug or an attack,
+never something to limp past). Fuchsia enforces exactly this.
+
+What this buys, precisely:
+
+- **ABI freedom** — the real prize. The numbers can change per release or per
+  boot and nothing outside the kernel image cares. The private ABI stays
+  actually private, permanently.
+- **A single audited chokepoint** for kernel entry, per process, at a
+  randomised address.
+- **Raised bar for exploits**: shellcode can't issue a hard-coded `syscall`;
+  it must first discover the per-process vDSO base (ASLR) and call through
+  it.
+
+What it does *not* buy: an attacker with arbitrary code execution in a
+process can still *call* the vDSO functions — they are mapped executable in
+that process, and return-oriented chains reach them. Syscall randomisation is
+hardening, not a security boundary; the security boundary remains the
+capability model (what the process's endpoints and device claims let it do).
+It is worth building anyway — for the ABI freedom first and the hardening
+second — but the design should never be sold as more than that.
+
+## Migration
+
+Phased so every step ships alone (the M-milestone discipline):
+
+1. **The blob + the table.** Build the vDSO, map it at spawn, deliver the
+   base via auxv. `runtime.system-call.zig` binds through the table when the
+   auxv entry is present, falls back to raw `syscall` when absent — the whole
+   tree keeps booting during the transition.
+2. **Cut the runtime over.** Delete the raw stubs; `runtime` no longer
+   imports the `SystemCall` numbers at all (`abi.zig`'s enum becomes
+   kernel-internal). The QEMU suite passing proves the table carries the
+   whole system.
+3. **Enforce + randomise.** Add the `rip`-range check, then per-boot number
+   randomisation patched into the blob at kernel init. A test boots with
+   randomisation on and runs the full suite.
+4. **The other languages.** Publish `danos.h`; a Rust `danos-sys` crate wraps
+   the table. This is also the seam `std.os.danos` calls through when the Zig
+   self-hosting fork lands (docs/zig-self-hosting.md) — the vDSO is what
+   makes that seam stable across kernel versions.
+
+## What deliberately stays out
+
+- **No dynamic linker, no `/lib/*.so`.** The vDSO is kernel-injected precisely
+  so danos binaries can stay fully static above it. Sharing *library code*
+  across processes stays what it is today: a service behind IPC, or source
+  compiled into each binary.
+- **No file/device I/O in the vDSO.** The microkernel line doesn't move: the
+  vDSO wraps the same deliberately tiny table (docs/syscall.md); files are
+  still the VFS server's business over IPC.
+- **No fast-path user-mode implementations yet.** Linux's vDSO exists mostly
+  to answer `gettimeofday` without a kernel entry. `danos_clock` could one
+  day read the calibrated TSC in user mode the same way — the blob is where
+  such an optimisation would live — but that is an optimisation, not part of
+  this design's contract.

docs/vfs-protocol.md

@@ -0,0 +1,170 @@
+# The VFS wire protocol
+
+> **Status:** built and spoken today between `runtime.fs` (the client) and the
+> VFS server (`system/services/vfs`), with mounted backends (the FAT server)
+> speaking the same protocol behind the router. The Zig source of truth is
+> `system/services/vfs/protocol.zig` (the `vfs-protocol` module), whose unit
+> tests pin the sizes and values below. This page is the **language-neutral
+> wire specification** of that contract — what a Rust or C client implements
+> ([vdso.md](vdso.md) explains why the IPC protocols, not the syscall
+> numbers, are danos's public ABI).
+
+## Transport
+
+A VFS exchange is one synchronous IPC rendezvous (`ipc_call`,
+docs/ipc.md): the client sends one message and blocks; the server replies
+with one message. The endpoint is found by well-known service id
+(`ipc_lookup`, service id **1** = vfs).
+
+- A message is at most **256 bytes** (`message_maximum`).
+- A request is a fixed 32-byte **Request** header followed by an inline
+  payload of at most **224 bytes** (`maximum_payload`) — a path, or write
+  bytes. There is no multi-message request: paths and single reads/writes
+  must fit, and larger transfers loop (see *read* / *write*).
+- A reply is a fixed 24-byte **Reply** header followed by an inline payload —
+  read bytes, a `FileStatus`, or a `DirectoryEntry`.
+- All integers are **little-endian**; layouts are C layout for x86-64
+  (`extern struct`), offsets given below so nothing need be inferred.
+
+The kernel never parses any of this — it only moves the bytes
+(docs/syscall.md); files are entirely a user-space affair.
+
+## Request header — 32 bytes
+
+| offset | size | field | meaning |
+|-------:|-----:|-------|---------|
+| 0 | 4 | `operation` | an **Operation** value (below) |
+| 4 | 4 | — | padding |
+| 8 | 8 | `node` | the server-side open-node id from a prior `open`; 0 for path-based operations |
+| 16 | 8 | `offset` | byte position for read/write; entry index (cursor) for readdir; else 0 |
+| 24 | 4 | `len` | payload length for path/write operations; requested byte count for read |
+| 28 | 4 | `flags` | open flags (below); else 0 |
+
+## Reply header — 24 bytes
+
+| offset | size | field | meaning |
+|-------:|-----:|-------|---------|
+| 0 | 4 | `status` | **0 = success**, negative = failure (signed) |
+| 4 | 4 | — | padding |
+| 8 | 8 | `node` | the new open-node id (for `open`); else 0 |
+| 16 | 4 | `len` | reply payload length in bytes |
+| 20 | 4 | — | padding |
+
+On failure the router replies `status = -1`; a mounted backend's negative
+status is forwarded to the client verbatim. A richer errno vocabulary is
+future work — clients must treat *any* negative status as failure, not match
+on -1.
+
+## Operations
+
+Values are append-only and never renumbered (the same evolution rule every
+danos protocol follows); an unrecognised operation gets a `status = -1`
+reply.
+
+| value | operation | request payload | reply |
+|------:|-----------|-----------------|-------|
+| 0 | `open` | the path (`len` = its length), `flags` as below | `node` = open-node id |
+| 1 | `close` | — (`node` set) | status only |
+| 2 | `read` | — (`node`, `offset`, `len` = wanted count) | `len` bytes read, payload = the bytes; `len` 0 at end of file |
+| 3 | `write` | the bytes (`node`, `offset`, `len` = count) | `len` = bytes accepted (may be short — loop) |
+| 4 | `status` | — (`node` set) | payload = **FileStatus** (24 bytes) |
+| 5 | `readdir` | — (`node` = a directory, `offset` = cursor) | payload = one **DirectoryEntry** + name; `len` 0 at end |
+| 6 | `mount` | the mount-point path; the backend endpoint rides as the call's **capability** | status only |
+| 7 | `unmount` | the mount-point path | status only |
+| 8 | `mkdir` | the path | status only |
+| 9 | `unlink` | the path | status only |
+| 10 | `rename` | old path, one `0x00`, new path (`len` = total) | status only |
+
+Notes per operation:
+
+- **open** — paths are absolute (`/mnt/usb/notes.txt`) or bare names
+  (`greeting`); bare names resolve in the VFS's flat ramfs, absolute paths
+  route through the mount table (below). The returned `node` is an id in the
+  *router's* open table; clients never see a backend's own ids.
+- **read / write** — a single exchange moves at most 224 bytes
+  (`maximum_payload`); the client loops, advancing `offset` by the returned
+  `len`, until done (read) or the slice is written (write). A `write` reply
+  shorter than requested is progress, not an error; a `len` of 0 means no
+  forward progress — stop rather than spin.
+- **readdir** — `offset` is a **cursor: the entry index**, not a byte
+  position. Each call returns exactly one entry; the client increments the
+  cursor by 1. A reply with `len` 0 is end-of-directory. The directory must
+  have been opened with the `directory` flag.
+- **mount** — the one operation that passes a **capability**: the caller
+  (a filesystem server, e.g. FAT) sends its own request endpoint as the
+  `ipc_call` capability argument, and the router forwards everything under
+  the mount point to it — speaking this same protocol, with paths rewritten
+  relative to the mount. Prefixes match at path boundaries only
+  (`/mnt/usb` never captures `/mnt/usbextra`); the longest matching prefix
+  wins.
+- **rename** — same-directory rename only (the router requires old and new to
+  resolve under one mount).
+
+## Open flags
+
+Bitwise OR in `Request.flags`, meaningful for `open` only:
+
+| bit | name | meaning |
+|----:|------|---------|
+| 1 | `create` | create the file if it does not exist |
+| 2 | `directory` | open a directory node for `readdir` rather than a file |
+| 4 | `truncate` | truncate an existing file to zero length on open (replace, don't overwrite in place) |
+
+## FileStatus — 24 bytes (the `status` reply payload)
+
+| offset | size | field | meaning |
+|-------:|-----:|-------|---------|
+| 0 | 8 | `size` | file size in bytes |
+| 8 | 4 | `kind` | a **NodeKind** value |
+| 12 | 4 | — | padding |
+| 16 | 8 | `mtime` | modification time, Unix epoch seconds UTC; 0 if the backend keeps none |
+
+## DirectoryEntry — 16 bytes + name (the `readdir` reply payload)
+
+| offset | size | field | meaning |
+|-------:|-----:|-------|---------|
+| 0 | 4 | `kind` | a **NodeKind** value |
+| 4 | 4 | `name_len` | length of the name that follows |
+| 8 | 8 | `size` | the entry's size in bytes |
+| 16 | `name_len` | name | the entry's name, not NUL-terminated |
+
+## NodeKind
+
+Aligned to the FSH file-type table
+(docs/danos-file-system-hierarchy-FSH.md):
+
+| value | kind |
+|------:|------|
+| 0 | regular file |
+| 1 | directory |
+| 2 | character device |
+| 3 | block device |
+| 4 | symbolic link |
+| 5 | fifo |
+| 6 | socket |
+
+Clients should map unknown values to *regular* rather than reject — the
+table can grow.
+
+## Lifetimes and trust
+
+Open-node ids live in the server. A client that dies without closing leaks
+nothing permanently: the VFS subscribes to the kernel's published process-exit
+events (docs/process-lifecycle.md) and releases a dead client's handles,
+closing forwarded backend nodes best-effort. Ids are plain integers, not
+capabilities — the VFS trusts its callers with each other's ids today, which
+is acceptable while every client is part of the system image and worth
+revisiting (per-client id namespaces) before third-party binaries arrive.
+
+## Evolution rules
+
+What a non-Zig implementation may rely on, and what it must not:
+
+- Operation values, flag bits, `NodeKind` values, and struct layouts are
+  **append-only and frozen once shipped** — the unit tests in `protocol.zig`
+  pin them exactly so a refactor can't silently move them.
+- The 256-byte message ceiling is a property of the current IPC transport,
+  not a promise; clients should read `maximum_payload`-shaped limits from the
+  reply lengths they actually get (loop-until-done), not hard-code 224.
+- Negative statuses beyond -1 will appear (an errno vocabulary); success is
+  exactly 0.

library/runtime/heap.zig

@@ -9,15 +9,32 @@
 //! — `grow` asks the kernel for pages via `mmap` instead of mapping frames
 //! itself, and the kernel picks the base address.
 //!
-//! Single-threaded and 16-byte maximum alignment, exactly like the kernel heap; a
-//! lock and larger alignments come when user programs gain threads.
+//! 16-byte maximum alignment, exactly like the kernel heap. The free list is guarded by
+//! a `Thread.Mutex` **only in multi-threaded binaries** (`addThreadedUserBinary`): the
+//! guard is gated on `builtin.single_threaded`, so an ordinary single-threaded binary
+//! compiles it out and pays nothing, while a threaded one can allocate safely from
+//! several threads at once (docs/threading-plan.md M7). The lock lives at the two
+//! free-list mutators — `rawAlloc`/`rawFree` — which every entry point funnels through.
 
 const std = @import("std");
+const builtin = @import("builtin");
 const abi = @import("abi");
 const system_calls = @import("system.zig");
+const Mutex = @import("thread.zig").Thread.Mutex;
 
 const page_size = abi.page_size;
 
+/// Guards `free_list`. A no-op in single-threaded builds (compiled out); a real futex
+/// mutex in threaded ones. Uncontended acquisition is a single CAS — no syscall.
+var heap_mutex: Mutex = .{};
+
+inline fn lockHeap() void {
+    if (comptime !builtin.single_threaded) heap_mutex.lock();
+}
+inline fn unlockHeap() void {
+    if (comptime !builtin.single_threaded) heap_mutex.unlock();
+}
+
 /// A block header, at the start of every block; while free it also links the
 /// free list via `next`.
 const Block = extern struct {
@@ -84,8 +101,11 @@ fn insertFree(block: *Block) void {
     }
 }
 
-/// Allocate `len` bytes (16-byte aligned), or null if out of memory.
+/// Allocate `len` bytes (16-byte aligned), or null if out of memory. Holds the heap lock
+/// across the free-list search and any `grow` (which also touches the free list).
 fn rawAlloc(len: usize) ?[*]u8 {
+    lockHeap();
+    defer unlockHeap();
     const need = alignUp(header_size + len, 16);
 
     var attempts: u32 = 0;
@@ -119,6 +139,8 @@ fn rawAlloc(len: usize) ?[*]u8 {
 }
 
 fn rawFree(ptr: [*]u8) void {
+    lockHeap();
+    defer unlockHeap();
     const block: *Block = @ptrFromInt(@intFromPtr(ptr) - header_size);
     insertFree(block);
 }

library/runtime/runtime.zig

@@ -70,6 +70,10 @@ pub const panic = start.panic;
 /// Process entry types: the `Init` handed to `main`, and its `Arguments`.
 pub const process = @import("process.zig");
 
+/// Threads: `runtime.Thread`, std.Thread-shaped, over the private thread ABI
+/// (docs/threading.md). A binary must be built multi-threaded to spawn.
+pub const Thread = @import("thread.zig").Thread;
+
 /// The service harness: one replyWait loop folding requests, signals, and
 /// notifications into callbacks (docs/process-lifecycle.md).
 pub const service = @import("service.zig");

library/runtime/shm.zig

@@ -22,7 +22,7 @@ pub const Region = struct {
 };
 
 /// Grant `len` bytes (rounded up to whole pages) of shareable, zeroed, cacheable RAM.
-/// Returns the region or null on failure. Two return values — vaddr in rax, handle in rdx —
+/// Returns the region or null on failure. Two return values — virtual_address in rax, handle in rdx —
 /// so this is a hand-written stub like `dma.alloc`.
 pub fn create(len: usize) ?Region {
     var rax: usize = undefined;

library/runtime/thread.zig

@@ -0,0 +1,484 @@
+//! `runtime.Thread` — threads for danos, shaped like Zig's `std.Thread` but built on
+//! danos's private thread ABI (docs/threading.md). Several tasks share one address
+//! space; `spawn` starts one, the kernel delivers the closure pointer in the new
+//! thread's rdi, a plain Zig trampoline runs the user function and calls `thread_exit`,
+//! and `join` blocks on the thread's exit notification. See docs/threading.md for why
+//! this mirrors `std.Thread`'s API rather than being the literal type.
+//!
+//! The closure (the function's captured args) lives at the **top of the thread's own
+//! stack**, not the heap — each thread's stack is private, so there is no shared-heap
+//! concurrency in the spawn/join machinery (the runtime heap is not yet thread-safe).
+//! A binary must be built multi-threaded (`addThreadedUserBinary`) before it may spawn.
+
+const std = @import("std");
+const builtin = @import("builtin");
+const abi = @import("abi");
+const sc = @import("system-call.zig");
+const system = @import("system.zig");
+
+/// True in a real danos binary; false when this module is compiled for host unit tests.
+/// The `Futex` seam and the test blocks below branch on it so the lock/condvar state
+/// machines can be exercised on the host against `std.Thread.Futex` (docs/threading-plan.md
+/// M11), while the danos build uses the futex syscalls.
+const on_danos = builtin.os.tag == .freestanding;
+
+/// A thread stack, if the caller does not override it. 64 KiB of mmap'd, zeroed pages.
+pub const default_stack_size: usize = 64 * 1024;
+
+/// Bytes reserved at the top of each thread's stack for its per-thread TLS block (the
+/// self-pointer plus scratch slots reachable via `%fs`). docs/threading-plan.md M10.
+const tls_block_size: usize = 64;
+
+pub const Thread = struct {
+    /// The kernel task id of the spawned thread — what `join` waits on.
+    tid: u32,
+    /// The mmap'd stack, reclaimed by `join` (or at process exit after `detach`).
+    stack_base: usize,
+    stack_size: usize,
+
+    pub const Id = u32;
+
+    pub const SpawnConfig = struct {
+        /// Bytes of stack, rounded up to whole pages by the kernel's mmap.
+        stack_size: usize = default_stack_size,
+    };
+
+    pub const SpawnError = error{
+        /// The kernel refused the thread, the stack mmap failed, or no endpoint was free.
+        SystemResources,
+    };
+
+    /// Start `function(args...)` on a new thread sharing this address space. Mirrors
+    /// `std.Thread.spawn`. The thread's return value is discarded (as in `std.Thread`);
+    /// return data through shared state.
+    pub fn spawn(config: SpawnConfig, comptime function: anytype, args: anytype) SpawnError!Thread {
+        const Args = @TypeOf(args);
+        const Closure = struct {
+            tls_base: usize,
+            args: Args,
+            /// Entered directly by the kernel with `self` in rdi (C ABI). Establishes this
+            /// thread's TLS pointer, runs the user function, then ends the thread.
+            fn entry(self_addr: usize) callconv(.c) noreturn {
+                const self: *@This() = @ptrFromInt(self_addr);
+                setThreadPointer(self.tls_base); // per-thread thread pointer before any user code
+                @call(.auto, function, self.args);
+                exitThread();
+            }
+        };
+
+        const base = system.mmap(config.stack_size, system.PROT_READ | system.PROT_WRITE);
+        if (system.mmapFailed(base)) return error.SystemResources;
+
+        // Top of the thread's own stack, downward: the closure, then a small per-thread TLS
+        // block (the thread pointer points here; slot 0 is the variant-II self-pointer, the rest is
+        // scratch for user TLS), then the stack proper (rsp starts below the TLS block, so
+        // the growing stack never overwrites either).
+        var closure_addr = (base + config.stack_size) - @sizeOf(Closure);
+        closure_addr &= ~@as(usize, @alignOf(Closure) - 1); // align the closure down
+
+        const tls_base = (closure_addr - tls_block_size) & ~@as(usize, 15);
+        const tls: [*]usize = @ptrFromInt(tls_base);
+        tls[0] = tls_base; // self-pointer (fs:0), as the x86_64 TLS ABI expects
+
+        const closure: *Closure = @ptrFromInt(closure_addr);
+        closure.* = .{ .tls_base = tls_base, .args = args };
+
+        var stack_top = tls_base & ~@as(usize, 15); // 16-align below the TLS block
+        stack_top -= 8; // ...then rsp % 16 == 8 at the C entry
+
+        const tid = threadSpawn(@intFromPtr(&Closure.entry), stack_top, closure_addr);
+        if (threadSpawnFailed(tid)) {
+            _ = system.munmap(base, config.stack_size);
+            return error.SystemResources;
+        }
+        return .{ .tid = @intCast(tid), .stack_base = base, .stack_size = config.stack_size };
+    }
+
+    /// Block until this thread finishes, then reclaim its stack. Mirrors
+    /// `std.Thread.join`. The exit endpoint is private to this thread, so the first
+    /// child-exit notification on it is this thread's.
+    pub fn join(self: Thread) void {
+        _ = sc.systemCall1(.thread_join, self.tid); // block until the thread has exited
+        _ = system.munmap(self.stack_base, self.stack_size); // reclaim its (now-vacated) stack
+    }
+
+    /// Relinquish the right to join: never wait for or reclaim this thread. Its stack is
+    /// reclaimed at process exit (docs/threading-plan.md M3 — kernel-reaper stack reclaim
+    /// for detached threads is a later refinement). Mirrors `std.Thread.detach`.
+    pub fn detach(self: Thread) void {
+        _ = self;
+    }
+
+    /// The calling thread's id (its kernel task id). Mirrors `std.Thread.getCurrentId`.
+    pub fn getCurrentId() Id {
+        return @intCast(sc.systemCall0(.thread_self));
+    }
+
+    /// The dense 0-based index of the core the calling thread is running on. A danos
+    /// extension beyond `std.Thread`, used to observe genuine cross-core parallelism.
+    pub fn currentCore() Id {
+        return @intCast(sc.systemCall0(.current_core));
+    }
+
+    /// `std.Thread.Futex`-shaped block/wake on a `u32` atomic — the primitive the
+    /// blocking `Mutex`/`Condition`/`Semaphore` are built on. Waiters park in the
+    /// kernel (no busy-wait), so an idle core still halts (docs/halting.md).
+    pub const Futex = struct {
+        /// Block while `ptr.* == expect`. Returns when woken by `wake`, or promptly if
+        /// the value already differs (safe against spurious returns, as in std): the
+        /// caller re-checks its condition in a loop.
+        pub fn wait(ptr: *const std.atomic.Value(u32), expect: u32) void {
+            if (comptime on_danos) {
+                _ = futexWait(@intFromPtr(ptr), expect, 0);
+            } else {
+                // Host unit-test mock: spin+yield until the value changes (`wake` is a
+                // no-op — the callers re-check their condition in a loop anyway). Correct,
+                // if busy; fine for the state-machine tests.
+                while (ptr.load(.acquire) == expect) std.Thread.yield() catch {};
+            }
+        }
+
+        /// As `wait`, but returns `error.Timeout` if `timeout_ns` elapses first.
+        pub fn timedWait(ptr: *const std.atomic.Value(u32), expect: u32, timeout_ns: u64) error{Timeout}!void {
+            if (comptime on_danos) {
+                if (futexWait(@intFromPtr(ptr), expect, timeout_ns) == abi.futex_timed_out) return error.Timeout;
+            } else {
+                var spins: u64 = 0;
+                const limit = timeout_ns / 1000 + 1;
+                while (ptr.load(.acquire) == expect) : (spins += 1) {
+                    if (spins >= limit) return error.Timeout;
+                    std.Thread.yield() catch {};
+                }
+            }
+        }
+
+        /// Wake up to `max_waiters` threads blocked on `ptr`.
+        pub fn wake(ptr: *const std.atomic.Value(u32), max_waiters: u32) void {
+            if (comptime on_danos) {
+                _ = futexWake(@intFromPtr(ptr), max_waiters);
+            } else {
+                // host mock: spin-waiters re-check their condition, so no wake is needed.
+            }
+        }
+    };
+
+    /// A mutual-exclusion lock, `std.Thread.Mutex`-shaped. The classic three-state
+    /// futex mutex (unlocked / locked / contended): the fast path is a single CAS, and
+    /// only a contended lock ever enters the kernel.
+    pub const Mutex = struct {
+        state: std.atomic.Value(u32) = std.atomic.Value(u32).init(unlocked),
+
+        const unlocked: u32 = 0;
+        const locked: u32 = 1;
+        const contended: u32 = 2;
+
+        /// Try to take the lock without blocking; returns whether it was acquired.
+        pub fn tryLock(m: *Mutex) bool {
+            return m.state.cmpxchgStrong(unlocked, locked, .acquire, .monotonic) == null;
+        }
+
+        /// Acquire the lock, blocking in the kernel while it is contended.
+        pub fn lock(m: *Mutex) void {
+            if (m.state.cmpxchgStrong(unlocked, locked, .acquire, .monotonic) != null) m.lockSlow();
+        }
+
+        fn lockSlow(m: *Mutex) void {
+            @branchHint(.cold);
+            // Mark the lock contended and take it as soon as it falls unlocked; park on
+            // the futex while it stays contended. Marking contended may cause a spurious
+            // wake on unlock (harmless), never a missed one.
+            while (m.state.swap(contended, .acquire) != unlocked) {
+                Futex.wait(&m.state, contended);
+            }
+        }
+
+        /// Release the lock; wake one waiter if the lock was contended.
+        pub fn unlock(m: *Mutex) void {
+            if (m.state.swap(unlocked, .release) == contended) Futex.wake(&m.state, 1);
+        }
+    };
+
+    /// A condition variable, `std.Thread.Condition`-shaped. Spurious wakeups are
+    /// allowed — always wait in a predicate loop with the mutex held. Built on a futex
+    /// sequence counter: a waiter samples the seq, drops the mutex, and parks until the
+    /// seq changes (a signal that races the unlock bumps the seq, so it is not missed).
+    pub const Condition = struct {
+        seq: std.atomic.Value(u32) = std.atomic.Value(u32).init(0),
+
+        /// Atomically release `mutex` and block until signalled, then re-acquire it.
+        pub fn wait(c: *Condition, mutex: *Mutex) void {
+            const seq = c.seq.load(.acquire);
+            mutex.unlock();
+            Futex.wait(&c.seq, seq);
+            mutex.lock();
+        }
+
+        /// As `wait`, but returns `error.Timeout` if `timeout_ns` elapses first. The
+        /// mutex is re-acquired either way.
+        pub fn timedWait(c: *Condition, mutex: *Mutex, timeout_ns: u64) error{Timeout}!void {
+            const seq = c.seq.load(.acquire);
+            mutex.unlock();
+            const timed_out = if (Futex.timedWait(&c.seq, seq, timeout_ns)) |_| false else |_| true;
+            mutex.lock();
+            if (timed_out) return error.Timeout;
+        }
+
+        /// Wake one waiter.
+        pub fn signal(c: *Condition) void {
+            _ = c.seq.fetchAdd(1, .release);
+            Futex.wake(&c.seq, 1);
+        }
+
+        /// Wake all waiters.
+        pub fn broadcast(c: *Condition) void {
+            _ = c.seq.fetchAdd(1, .release);
+            Futex.wake(&c.seq, std.math.maxInt(u32));
+        }
+    };
+
+    /// A counting semaphore, `std.Thread.Semaphore`-shaped: a permit count guarded by a
+    /// `Mutex` + `Condition`.
+    pub const Semaphore = struct {
+        mutex: Mutex = .{},
+        cond: Condition = .{},
+        permits: usize = 0,
+
+        /// Take a permit, blocking until one is available.
+        pub fn wait(s: *Semaphore) void {
+            s.mutex.lock();
+            defer s.mutex.unlock();
+            while (s.permits == 0) s.cond.wait(&s.mutex);
+            s.permits -= 1;
+        }
+
+        /// Return a permit and wake a waiter.
+        pub fn post(s: *Semaphore) void {
+            s.mutex.lock();
+            defer s.mutex.unlock();
+            s.permits += 1;
+            s.cond.signal();
+        }
+    };
+
+    /// A reader/writer lock, `std.Thread.RwLock`-shaped: many concurrent readers OR one
+    /// exclusive writer. Reader-preferring (a steady stream of readers can delay a writer),
+    /// built on `Mutex` + `Condition` over a signed state: `>0` = that many readers hold
+    /// it, `-1` = a writer holds it, `0` = free.
+    pub const RwLock = struct {
+        mutex: Mutex = .{},
+        cond: Condition = .{},
+        state: i64 = 0,
+
+        /// Acquire shared (read) access, blocking while a writer holds the lock.
+        pub fn lockShared(rw: *RwLock) void {
+            rw.mutex.lock();
+            defer rw.mutex.unlock();
+            while (rw.state < 0) rw.cond.wait(&rw.mutex);
+            rw.state += 1;
+        }
+
+        /// Try to acquire shared access without blocking.
+        pub fn tryLockShared(rw: *RwLock) bool {
+            rw.mutex.lock();
+            defer rw.mutex.unlock();
+            if (rw.state < 0) return false;
+            rw.state += 1;
+            return true;
+        }
+
+        /// Release shared access; wake a waiting writer once the last reader leaves.
+        pub fn unlockShared(rw: *RwLock) void {
+            rw.mutex.lock();
+            defer rw.mutex.unlock();
+            rw.state -= 1;
+            if (rw.state == 0) rw.cond.broadcast();
+        }
+
+        /// Acquire exclusive (write) access, blocking until no readers or writer remain.
+        pub fn lock(rw: *RwLock) void {
+            rw.mutex.lock();
+            defer rw.mutex.unlock();
+            while (rw.state != 0) rw.cond.wait(&rw.mutex);
+            rw.state = -1;
+        }
+
+        /// Try to acquire exclusive access without blocking.
+        pub fn tryLock(rw: *RwLock) bool {
+            rw.mutex.lock();
+            defer rw.mutex.unlock();
+            if (rw.state != 0) return false;
+            rw.state = -1;
+            return true;
+        }
+
+        /// Release exclusive access; wake all waiters (they re-check their condition).
+        pub fn unlock(rw: *RwLock) void {
+            rw.mutex.lock();
+            defer rw.mutex.unlock();
+            rw.state = 0;
+            rw.cond.broadcast();
+        }
+    };
+
+    /// A `std.Thread.WaitGroup`-shaped counter: `start` before spawning work, `finish` as
+    /// each unit completes, `wait` blocks until the count returns to zero.
+    pub const WaitGroup = struct {
+        mutex: Mutex = .{},
+        cond: Condition = .{},
+        counter: usize = 0,
+
+        /// Register one pending unit of work.
+        pub fn start(wg: *WaitGroup) void {
+            wg.mutex.lock();
+            defer wg.mutex.unlock();
+            wg.counter += 1;
+        }
+
+        /// Mark one unit done; wake waiters if that was the last.
+        pub fn finish(wg: *WaitGroup) void {
+            wg.mutex.lock();
+            defer wg.mutex.unlock();
+            wg.counter -= 1;
+            if (wg.counter == 0) wg.cond.broadcast();
+        }
+
+        /// Block until every started unit has finished.
+        pub fn wait(wg: *WaitGroup) void {
+            wg.mutex.lock();
+            defer wg.mutex.unlock();
+            while (wg.counter != 0) wg.cond.wait(&wg.mutex);
+        }
+    };
+};
+
+/// thread_spawn(entry, stack_top, arg, exit_endpoint) -> tid, or a wrapped error.
+fn threadSpawn(entry: usize, stack_top: usize, arg: usize) usize {
+    const exit_endpoint: usize = @intCast(abi.no_cap); // join uses thread_join, not an endpoint
+    return sc.systemCall4(.thread_spawn, entry, stack_top, arg, exit_endpoint);
+}
+
+/// The kernel returns a real (small) task id on success and a wrapped `-1` on failure;
+/// no valid task id ever exceeds a u32.
+inline fn threadSpawnFailed(ret: usize) bool {
+    return ret > std.math.maxInt(u32);
+}
+
+/// End the calling thread. Never returns.
+fn exitThread() noreturn {
+    _ = sc.systemCall0(.thread_exit);
+    unreachable;
+}
+
+/// Set the calling thread's FS base (its user TLS thread pointer).
+fn setThreadPointer(addr: usize) void {
+    _ = sc.systemCall1(.set_thread_pointer, addr);
+}
+
+/// futex_wait(addr, expect, timeout_ns) -> status (abi.futex_*).
+fn futexWait(addr: usize, expect: u32, timeout_ns: u64) usize {
+    return sc.systemCall3(.futex_wait, addr, expect, timeout_ns);
+}
+
+/// futex_wake(addr, count) -> number woken.
+fn futexWake(addr: usize, count: u32) usize {
+    return sc.systemCall2(.futex_wake, addr, count);
+}
+
+// --- host unit tests (docs/threading-plan.md M11) ---------------------------
+//
+// These run under `zig build test` on the host: the `Futex` seam above uses
+// `std.Thread.Futex` off-danos, so the lock/condvar state machines can be exercised by
+// real host threads. They are never compiled into a danos binary (test blocks only build
+// under test), so their `std.Thread` use is fine even though `std.Thread` is unavailable
+// on the freestanding target.
+
+test "Mutex serialises concurrent increments across host threads" {
+    var m: Thread.Mutex = .{};
+    var counter: u64 = 0;
+    const workers = 8;
+    const per = 20_000;
+    const Ctx = struct {
+        m: *Thread.Mutex,
+        c: *u64,
+        fn run(ctx: @This()) void {
+            var i: usize = 0;
+            while (i < per) : (i += 1) {
+                ctx.m.lock();
+                ctx.c.* += 1;
+                ctx.m.unlock();
+            }
+        }
+    };
+    var handles: [workers]std.Thread = undefined;
+    for (&handles) |*h| h.* = try std.Thread.spawn(.{}, Ctx.run, .{Ctx{ .m = &m, .c = &counter }});
+    for (handles) |h| h.join();
+    try std.testing.expectEqual(@as(u64, workers * per), counter);
+}
+
+test "RwLock never lets a reader observe a half-written pair" {
+    var rw: Thread.RwLock = .{};
+    var a: u64 = 0;
+    var b: u64 = 0; // invariant while a lock is held: a == b
+    var stop = std.atomic.Value(bool).init(false);
+    var ok = std.atomic.Value(bool).init(true);
+
+    const Writer = struct {
+        rw: *Thread.RwLock,
+        a: *u64,
+        b: *u64,
+        stop: *std.atomic.Value(bool),
+        fn run(w: @This()) void {
+            var v: u64 = 1;
+            while (!w.stop.load(.acquire)) : (v +%= 1) {
+                w.rw.lock();
+                w.a.* = v; // update both halves under the exclusive lock...
+                w.b.* = v;
+                w.rw.unlock();
+            }
+        }
+    };
+    const Reader = struct {
+        rw: *Thread.RwLock,
+        a: *u64,
+        b: *u64,
+        ok: *std.atomic.Value(bool),
+        fn run(r: @This()) void {
+            var i: usize = 0;
+            while (i < 200_000) : (i += 1) {
+                r.rw.lockShared();
+                if (r.a.* != r.b.*) r.ok.store(false, .release); // ...so a reader must never see them differ
+                r.rw.unlockShared();
+            }
+        }
+    };
+
+    var writers: [2]std.Thread = undefined;
+    for (&writers) |*w| w.* = try std.Thread.spawn(.{}, Writer.run, .{Writer{ .rw = &rw, .a = &a, .b = &b, .stop = &stop }});
+    var readers: [4]std.Thread = undefined;
+    for (&readers) |*rd| rd.* = try std.Thread.spawn(.{}, Reader.run, .{Reader{ .rw = &rw, .a = &a, .b = &b, .ok = &ok }});
+    for (readers) |rd| rd.join();
+    stop.store(true, .release);
+    for (writers) |w| w.join();
+    try std.testing.expect(ok.load(.acquire));
+}
+
+test "WaitGroup blocks until every started unit finishes" {
+    var wg: Thread.WaitGroup = .{};
+    var done = std.atomic.Value(u32).init(0);
+    const n = 6;
+    const Ctx = struct {
+        wg: *Thread.WaitGroup,
+        done: *std.atomic.Value(u32),
+        fn run(c: @This()) void {
+            _ = c.done.fetchAdd(1, .monotonic);
+            c.wg.finish();
+        }
+    };
+    var i: usize = 0;
+    while (i < n) : (i += 1) wg.start();
+    var handles: [n]std.Thread = undefined;
+    for (&handles) |*h| h.* = try std.Thread.spawn(.{}, Ctx.run, .{Ctx{ .wg = &wg, .done = &done }});
+    wg.wait(); // must not return until all n finished
+    try std.testing.expectEqual(@as(u32, n), done.load(.acquire));
+    for (handles) |h| h.join();
+}

system/abi.zig

@@ -39,13 +39,13 @@ pub const SystemCall = enum(u64) {
     ipc_reply_wait = 10, // ipc_reply_wait(h, reply, len, receive, cap) -> receive_len (+badge in rdx)
     device_enumerate = 11, // device_enumerate(buffer, maximum) -> count: snapshot the device table
     device_claim = 12, // device_claim(id) -> ok: take exclusive ownership of a device
-    mmio_map = 13, // mmio_map(id, resource_index) -> vaddr: map a claimed device's MMIO into this AS
+    mmio_map = 13, // mmio_map(id, resource_index) -> virtual_address: map a claimed device's MMIO into this address space
     irq_bind = 14, // irq_bind(id, resource_index, endpoint): deliver a device IRQ as an IPC notification
     irq_ack = 15, // irq_ack(id, resource_index): re-arm a bound IRQ after servicing it
     device_register = 16, // device_register(parent_id, descriptor) -> id: publish a child of a device you claimed
     system_spawn = 17, // system_spawn(name_ptr, name_len, arguments_ptr, arguments_len, exit_endpoint) -> child process id: start a named initial-ramdisk binary as a new ring-3 process
-    dma_alloc = 18, // dma_alloc(len, flags) -> vaddr (rax), paddr (rdx): contiguous, pinned, uncacheable DMA memory
-    dma_free = 19, // dma_free(vaddr, len) -> 0: release a prior dma_alloc
+    dma_alloc = 18, // dma_alloc(len, flags) -> virtual_address (rax), physical_address (rdx): contiguous, pinned, uncacheable DMA memory
+    dma_free = 19, // dma_free(virtual_address, len) -> 0: release a prior dma_alloc
     msi_bind = 20, // msi_bind(device_id, endpoint) -> address (rax), data (rdx): a per-device MSI vector for a claimed device
     io_read = 21, // io_read(device_id, resource_index, offset, width) -> value: read a port in a claimed device's io_port resource
     io_write = 22, // io_write(device_id, resource_index, offset, width, value) -> 0: write a port in a claimed device's io_port resource
@@ -60,12 +60,25 @@ pub const SystemCall = enum(u64) {
     timer_bind = 31, // timer_bind(endpoint, ms) -> 0/-errno: one-shot timer — posts a notification when ms elapse
     klog_read = 32, // klog_read(offset, ptr, len) -> bytes copied: copy the kernel RAM log buffer out to a user buffer (for persisting the boot log to disk)
     wall_clock = 33, // wall_clock() -> Unix epoch seconds (UTC): the RTC wall-clock time, for filesystem timestamps (mtime). Monotonic time is `clock`.
-    shm_create = 34, // shm_create(len) -> vaddr (rax), handle (rdx): a shareable, zeroed, cacheable RAM region mapped into this AS; the handle is a capability passed to another process as an ipc_call send_cap (docs/display-v2.md)
-    shm_map = 35, // shm_map(cap) -> vaddr: map the shared region named by a received capability into this AS (the same physical pages the creator sees)
-    shm_physical = 36, // shm_physical(cap) -> paddr: the guest-physical base of a shared region held by capability, so a driver can program it into a device (e.g. virtio-gpu attach_backing); the pages are contiguous (docs/display-v2.md)
+    shm_create = 34, // shm_create(len) -> virtual_address (rax), handle (rdx): a shareable, zeroed, cacheable RAM region mapped into this AS; the handle is a capability passed to another process as an ipc_call send_cap (docs/display-v2.md)
+    shm_map = 35, // shm_map(cap) -> virtual_address: map the shared region named by a received capability into this address space (the same physical pages the creator sees)
+    shm_physical = 36, // shm_physical(cap) -> physical_address: the guest-physical base of a shared region held by capability, so a driver can program it into a device (e.g. virtio-gpu attach_backing); the pages are contiguous (docs/display-v2.md)
+    thread_spawn = 37, // thread_spawn(entry, stack_top, arg, exit_endpoint) -> tid: start a task sharing the caller's address space at `entry` on `stack_top`, `arg` in rdi; exit_endpoint (a handle, or no_cap) is notified when it ends — how join waits (docs/threading.md)
+    thread_exit = 38, // thread_exit(): end the calling thread, dropping one reference to its address space (destroyed on the last)
+    current_core = 39, // current_core() -> index: the dense 0-based index of the core the caller is running on (for parallelism/affinity introspection)
+    futex_wait = 40, // futex_wait(addr, expected, timeout_ns) -> status: if *addr == expected, block until woken or the timeout; returns futex_woken/mismatch/timed_out (docs/threading.md)
+    futex_wake = 41, // futex_wake(addr, count) -> woken: wake up to `count` tasks blocked in futex_wait on `addr` in this address space
+    thread_self = 42, // thread_self() -> tid: the calling thread's kernel task id (runtime.Thread.getCurrentId)
+    thread_join = 43, // thread_join(tid) -> 0: block until the thread with id `tid` has exited (runtime.Thread.join; no per-thread IPC endpoint) (docs/threading.md)
+    set_thread_pointer = 44, // set_thread_pointer(addr) -> 0: set the caller's thread pointer (user-space TLS base; x86_64 IA32_FS_BASE, aarch64 TPIDR_EL0); restored per task across context switches (docs/threading-plan.md M10)
     _,
 };
 
+/// `futex_wait` return codes (in rax).
+pub const futex_woken: u64 = 0; // woken by a futex_wake
+pub const futex_mismatch: u64 = 1; // *addr != expected on entry; the caller did not block
+pub const futex_timed_out: u64 = 2; // the timeout elapsed before a wake
+
 /// How a process ended — recorded by the kernel at death, queried by the
 /// supervisor with `process_exit_reason`, and the input to its restart decision
 /// (docs/process-lifecycle.md): a clean exit meant to stop, a fault wants a

system/drivers/ps2-bus/mouse.zig

@@ -60,7 +60,7 @@ pub fn main(init: runtime.process.Init) void {
         _ = runtime.system.write("/system/drivers/ps2-bus/mouse: out of memory\n");
         return;
     };
-    if (device.findDeviceDescriptorByHid(buffer, hid) == null) {
+    if (ps2.findMouseDescriptor(buffer) == null) {
         writeLine("/system/drivers/ps2-bus/mouse: no device for hid {s}\n", .{hid});
         return;
     }

system/drivers/ps2-bus/ps2-bus.zig

@@ -244,7 +244,7 @@ pub fn main() void {
     // to the *port*, whatever device identify found on it.
     var maybe_auxiliary_interrupt: ?struct { device_id: u64, interrupt_index: u64, gsi: u64 } = null;
     if (port_device_types[@intFromEnum(ps2.Port.two)] != null) {
-        if (device.findDeviceDescriptorByHid(buffer, acpi_ids.HardwareId.ps2_mouse.hid())) |descriptor| {
+        if (ps2.findMouseDescriptor(buffer)) |descriptor| {
             if (findInterruptResourceIndex(descriptor)) |auxiliary_index| {
                 if (device.claim(descriptor.id) and device.irqBind(descriptor.id, auxiliary_index, endpoint)) {
                     maybe_auxiliary_interrupt = .{

system/drivers/ps2-bus/ps2-library.zig

@@ -270,6 +270,22 @@ pub const DeviceType = enum(u32) {
     }
 };
 
+/// The `_HID`s a PS/2 pointing device (the controller's aux channel) can enumerate
+/// under. It is the same 8042 mouse channel whichever id the firmware chose:
+/// QEMU/OVMF report the generic `.ps2_mouse` (PNP0F13), VirtualBox reports
+/// `.microsoft_ps2_mouse` (PNP0F03). Both mean "the mouse on port two".
+pub const mouse_hardware_ids = [_]acpi_ids.HardwareId{ .ps2_mouse, .microsoft_ps2_mouse };
+
+/// Find the aux (mouse) device's ACPI node, whichever of the PS/2-mouse `_HID`s the
+/// firmware used — the bus needs it to bind IRQ12, and the mouse driver to confirm
+/// its device is present. Returns the first match, or null if none is reported.
+pub fn findMouseDescriptor(buffer: []device.DeviceDescriptor) ?device.DeviceDescriptor {
+    for (mouse_hardware_ids) |id| {
+        if (device.findDeviceDescriptorByHid(buffer, id.hid())) |descriptor| return descriptor;
+    }
+    return null;
+}
+
 // --- the bus <-> child-driver forwarding protocol -----------------------------
 //
 // The 8042's ports and IRQ1 live on the PNP0303 node that only the ps2-bus driver

system/kernel/architecture/x86_64/cpu.zig

@@ -304,6 +304,17 @@ pub fn cpuLocal() usize {
     return pcpu.scheduler();
 }
 
+const ia32_fs_base = 0xC000_0100;
+
+/// Set the user-space TLS **thread pointer** — the arch-neutral name the generic scheduler
+/// calls (`architecture.setThreadPointer`). On x86_64 that is the FS-segment base
+/// (`IA32_FS_BASE`); an aarch64 port implements the same call against `TPIDR_EL0`. The
+/// kernel never touches FS, so this only affects the user task that runs next, which the
+/// scheduler restores per task across context switches (docs/threading-plan.md M10).
+pub fn setThreadPointer(base: u64) void {
+    io.wrmsr(ia32_fs_base, base);
+}
+
 // --- SMP: application-processor bring-up ----------------------------------
 
 /// Record the low (<1 MiB) frame reserved for the AP trampoline. Run once at boot.
@@ -687,6 +698,15 @@ pub fn jumpToUser(entry: u64, stack_top: u64) noreturn {
     jump_to_user(entry, stack_top);
 }
 
+/// As `jumpToUser`, but delivers `arg0` in the user's `rdi` — how a fresh thread
+/// receives its closure pointer (docs/threading.md). A normal process is dropped
+/// with `arg0 = 0`, which its `_start` ignores (it reads argv off the stack).
+extern fn jump_to_user_arg(rip: u64, rsp: u64, arg0: u64) callconv(.c) noreturn;
+
+pub fn jumpToUserArg(entry: u64, stack_top: u64, arg0: u64) noreturn {
+    jump_to_user_arg(entry, stack_top, arg0);
+}
+
 /// Route CPU exceptions to `handler`, which receives the trap frame and does not
 /// return. Until set, faults just halt the core.
 pub fn setFaultHandler(handler: *const fn (*const CpuState) noreturn) void {

system/kernel/architecture/x86_64/isr.s

@@ -123,6 +123,22 @@ jump_to_user:
     swapgs                 # user GS base (isr_common/syscall swap back on entry)
     iretq
 
+# jump_to_user_arg(rdi = user rip, rsi = user rsp, rdx = user rdi/arg0): as
+# jump_to_user, but delivers arg0 in the user's rdi — how a fresh **thread**
+# receives its closure pointer (docs/threading.md). rdi carries the rip only until
+# it is pushed into the iretq frame, after which we overwrite it with the arg.
+.global jump_to_user_arg
+jump_to_user_arg:
+    cli
+    push $0x1B              # user SS  (0x18 | RPL 3)
+    push %rsi              # user RSP
+    push $0x202            # RFLAGS: IF | reserved-1
+    push $0x23             # user CS  (0x20 | RPL 3)
+    push %rdi             # user RIP  (consumes rdi)
+    mov %rdx, %rdi        # user rdi = arg0 (the thread's closure pointer)
+    swapgs                 # user GS base (isr_common/syscall swap back on entry)
+    iretq
+
 # --- ring 3 entry/exit ------------------------------------------------------
 
 # enter_user(rdi = user rip, rsi = user rsp, rdx = &TSS.rsp0)

system/kernel/architecture/x86_64/paging.zig

@@ -509,7 +509,7 @@ pub fn unmapInto(pml4: u64, virtual: u64) void {
 /// any address space, not just the live one). Returns null if `virtual` is not
 /// mapped at any level. Stops at a 2 MiB huge-page leaf (the physmap uses them),
 /// resolving the offset within it. The foundation for cross-address-space copies
-/// and for munmap (which needs the frame behind a user vaddr to free it).
+/// and for munmap (which needs the frame behind a user virtual_address to free it).
 pub fn translateIn(pml4: u64, virtual: u64) ?u64 {
     const pml4e = tableAt(pml4)[(virtual >> 39) & 0x1FF];
     if (pml4e & present == 0) return null;

system/kernel/ipc-synchronous.zig

@@ -355,7 +355,7 @@ pub fn replyWait(endpoint: *Endpoint, reply_ptr: u64, reply_len: u64, receive_pt
         me.ipc_client = null;
         const n = @min(reply_len, client.ipc_reply_cap);
         client.ipc_received_cap = abi.no_cap;
-        if (!copyAcross(me.aspace, reply_ptr, client.aspace, client.ipc_reply_ptr, n)) {
+        if (!copyAcross(me.address_space, reply_ptr, client.address_space, client.ipc_reply_ptr, n)) {
             client.ipc_status = -EFAULT;
         } else if (send_cap != abi.no_cap) {
             // Transfer the reply's capability into the client. A failure fails the
@@ -383,8 +383,8 @@ pub fn replyWait(endpoint: *Endpoint, reply_ptr: u64, reply_len: u64, receive_pt
         }
         if (popPost(endpoint)) |slot| {
             const n = @min(@as(usize, slot.length), receive_cap);
-            // Copy from the kernel-resident ring slot (source aspace 0) into the receiver.
-            if (!copyAcross(0, @intFromPtr(&slot.bytes), me.aspace, receive_ptr, n)) {
+            // Copy from the kernel-resident ring slot (source address_space 0) into the receiver.
+            if (!copyAcross(0, @intFromPtr(&slot.bytes), me.address_space, receive_ptr, n)) {
                 continue; // bad receive buffer: drop this message, keep serving
             }
             out_badge.* = slot.sender_id | notify_badge_bit | notify_message_bit;
@@ -392,7 +392,7 @@ pub fn replyWait(endpoint: *Endpoint, reply_ptr: u64, reply_len: u64, receive_pt
         }
         if (dequeueSender(endpoint)) |caller| {
             const n = @min(caller.ipc_send_len, receive_cap);
-            if (!copyAcross(caller.aspace, caller.ipc_send_ptr, me.aspace, receive_ptr, n)) {
+            if (!copyAcross(caller.address_space, caller.ipc_send_ptr, me.address_space, receive_ptr, n)) {
                 caller.ipc_status = -EFAULT; // bad sender buffer: fail it, keep serving
                 scheduler.readyLocked(caller);
                 continue;

system/kernel/process.zig

@@ -58,8 +58,9 @@ pub const stack_top_virtual: u64 = stack_base_virtual + parameters.user_stack_pa
 
 /// The mmap grant arena: where `mmap` hands out fresh user pages, above the image
 /// and stack but still inside PML4[224] (so no kernel mapping is widened). Each
-/// process bump-allocates from `heap_arena_base` upward via `Task.heap_next`; a
-/// 1 GiB window is far more than any user heap needs today.
+/// process bump-allocates from `heap_arena_base` upward via a per-address-space cursor
+/// (`scheduler.addressSpaceMmapNextPtr`, shared by its threads); a 1 GiB window is far more
+/// than any user heap needs today.
 pub const heap_arena_base: u64 = 0x0000_7000_1000_0000;
 pub const heap_arena_end: u64 = heap_arena_base + (1 << 30);
 
@@ -69,8 +70,8 @@ pub const user_half_end: u64 = 0x0000_8000_0000_0000;
 
 /// The MMIO-grant arena: where `mmio_map` places device windows, in PML4[226] —
 /// a user-exclusive region distinct from code/stack/heap (PML4[224]), so mapping
-/// device pages user-accessible widens no kernel mapping. Per-process cursor in
-/// `Task.device_map_next`.
+/// device pages user-accessible widens no kernel mapping. Per-address-space cursor
+/// (`scheduler.addressSpaceDeviceMapNextPtr`).
 pub const device_arena_base: u64 = 0x0000_7100_0000_0000;
 pub const device_arena_end: u64 = device_arena_base + (4 << 30);
 
@@ -163,7 +164,7 @@ fn fail(state: *architecture.CpuState) void {
 
 fn system_call(state: *architecture.CpuState) void {
     const t = scheduler.current();
-    const user = t.aspace != 0;
+    const user = t.address_space != 0;
     if (user) {
         // A condemned process (process_kill caught it running) dies at its next
         // kernel entry — before it can spawn, claim, or message anything else.
@@ -227,6 +228,22 @@ fn system_call(state: *architecture.CpuState) void {
         .shm_create => systemShmCreate(state),
         .shm_map => systemShmMap(state),
         .shm_physical => systemShmPhysical(state),
+        .thread_spawn => systemThreadSpawn(state),
+        .current_core => systemCurrentCore(state),
+        .thread_self => systemThreadSelf(state),
+        .thread_join => systemThreadJoin(state),
+        .set_thread_pointer => systemSetThreadPointer(state),
+        .futex_wait => systemFutexWait(state),
+        .futex_wake => systemFutexWake(state),
+        .thread_exit => {
+            // A thread ends like a process exit(0), but only this task: its
+            // resources are released and its address-space reference dropped (the
+            // space survives while sibling threads hold it). docs/threading.md.
+            if (scheduler.currentIsUserProcess()) {
+                scheduler.current().exit_reason = .exited;
+                terminateCurrent();
+            } else architecture.userExit();
+        },
         _ => fail(state),
     }
 }
@@ -300,7 +317,7 @@ fn systemIpcReplyWait(state: *architecture.CpuState) void {
 fn systemIpcSend(state: *architecture.CpuState) void {
     const me = scheduler.current();
     const endpoint = ipc.resolveHandle(me, architecture.systemCallArg(state, 0)) orelse return failErr(state, ipc.EBADF);
-    const r = ipc.send(endpoint, me.aspace, architecture.systemCallArg(state, 1), architecture.systemCallArg(state, 2), me.id);
+    const r = ipc.send(endpoint, me.address_space, architecture.systemCallArg(state, 1), architecture.systemCallArg(state, 2), me.id);
     architecture.setSystemCallResult(state, @bitCast(r));
 }
 
@@ -310,7 +327,7 @@ fn systemDeviceEnumerate(state: *architecture.CpuState) void {
     const buffer_ptr = architecture.systemCallArg(state, 0);
     const maximum = architecture.systemCallArg(state, 1);
     const t = scheduler.current();
-    if (t.aspace == 0 or buffer_ptr >= user_half_end) return fail(state);
+    if (t.address_space == 0 or buffer_ptr >= user_half_end) return fail(state);
     const sz = @sizeOf(device_abi.DeviceDescriptor);
     const cap = @min(maximum, (user_half_end - buffer_ptr) / sz); // clamp to the user half
     const out: [*]device_abi.DeviceDescriptor = @ptrFromInt(buffer_ptr);
@@ -334,14 +351,14 @@ fn systemDeviceClaim(state: *architecture.CpuState) void {
     } else fail(state);
 }
 
-/// mmio_map(device_id, resource_index) -> vaddr: map a claimed device's MMIO window into
+/// mmio_map(device_id, resource_index) -> virtual_address: map a claimed device's MMIO window into
 /// this address space (strong-uncacheable) and return the register base address.
 /// The claim is the capability — a process can only map hardware it owns.
 fn systemMmioMap(state: *architecture.CpuState) void {
     const device_id = architecture.systemCallArg(state, 0);
     const resource_index = architecture.systemCallArg(state, 1);
     const t = scheduler.current();
-    if (t.aspace == 0) return fail(state);
+    if (t.address_space == 0) return fail(state);
     // Read the broker table under the lock: ring-3 device_register (M19) now
     // mutates it concurrently on other cores, so a lock-free read here could
     // see a torn resource (and a torn length used to panic the arithmetic
@@ -359,18 +376,23 @@ fn systemMmioMap(state: *architecture.CpuState) void {
     if (r.len == 0) return fail(state);
     if (@addWithOverflow(r.start, r.len)[1] != 0) return fail(state);
 
-    if (t.device_map_next == 0) t.device_map_next = device_arena_base;
     const first = r.start & ~@as(u64, page_size - 1);
     const last = (r.start + r.len - 1) & ~@as(u64, page_size - 1);
     const pages = (last - first) / page_size + 1;
-    const base_v = t.device_map_next;
-    if (base_v + pages * page_size > device_arena_end) return fail(state);
-
     // A framebuffer resource asks (via its flag) to be mapped write-combining rather
     // than the strong-uncacheable default that register MMIO needs.
     const write_combining = (r.flags & device_abi.resource_flag_write_combining) != 0;
-    architecture.mapUserDeviceInto(t.aspace, base_v, r.start, r.len, write_combining);
-    t.device_map_next = base_v + pages * page_size;
+
+    // Per-address-space cursor + shared page tables → serialize under the big lock,
+    // same as mmap (docs/threading-plan.md M7).
+    const flags = sync.enter();
+    defer sync.leave(flags);
+    const cursor = scheduler.addressSpaceDeviceMapNextPtr(t.address_space) orelse return fail(state);
+    if (cursor.* == 0) cursor.* = device_arena_base; // seed the arena lazily
+    const base_v = cursor.*;
+    if (base_v + pages * page_size > device_arena_end) return fail(state);
+    architecture.mapUserDeviceInto(t.address_space, base_v, r.start, r.len, write_combining);
+    cursor.* = base_v + pages * page_size;
     architecture.setSystemCallResult(state, base_v + (r.start & (page_size - 1))); // register base
 }
 
@@ -399,7 +421,7 @@ pub fn resolveIoPort(t: *scheduler.Task, device_id: u64, resource_index: u64, of
 /// is fine. See docs/drivers.md.
 fn systemIoRead(state: *architecture.CpuState) void {
     const t = scheduler.current();
-    if (t.aspace == 0) return fail(state);
+    if (t.address_space == 0) return fail(state);
     const width = architecture.systemCallArg(state, 3);
     const port = resolveIoPort(t, architecture.systemCallArg(state, 0), architecture.systemCallArg(state, 1), architecture.systemCallArg(state, 2), width) orelse return fail(state);
     architecture.setSystemCallResult(state, architecture.pioRead(@intCast(width), port));
@@ -410,14 +432,14 @@ fn systemIoRead(state: *architecture.CpuState) void {
 /// gate as `io_read`.
 fn systemIoWrite(state: *architecture.CpuState) void {
     const t = scheduler.current();
-    if (t.aspace == 0) return fail(state);
+    if (t.address_space == 0) return fail(state);
     const width = architecture.systemCallArg(state, 3);
     const port = resolveIoPort(t, architecture.systemCallArg(state, 0), architecture.systemCallArg(state, 1), architecture.systemCallArg(state, 2), width) orelse return fail(state);
     architecture.pioWrite(@intCast(width), port, @intCast(architecture.systemCallArg(state, 4)));
     architecture.setSystemCallResult(state, 0);
 }
 
-/// dma_alloc(len, flags) -> vaddr (rax), paddr (rdx): grant `len` bytes (rounded up to
+/// dma_alloc(len, flags) -> virtual_address (rax), physical_address (rdx): grant `len` bytes (rounded up to
 /// whole pages) of DMA-capable memory — physically contiguous, zeroed, pinned, and
 /// strong-uncacheable (coherent) — mapping it into the caller's DMA arena and handing
 /// back both the virtual address to touch and the physical address to program into the
@@ -429,7 +451,7 @@ fn systemDmaAlloc(state: *architecture.CpuState) void {
     const len = architecture.systemCallArg(state, 0);
     const flags = architecture.systemCallArg(state, 1);
     const t = scheduler.current();
-    if (t.aspace == 0 or len == 0) return fail(state);
+    if (t.address_space == 0 or len == 0) return fail(state);
 
     const pages: usize = @intCast((len + page_size - 1) / page_size);
     const max_phys: u64 = if (flags & abi.dma_below_4g != 0) (@as(u64, 4) << 30) else ~@as(u64, 0);
@@ -445,14 +467,14 @@ fn systemDmaAlloc(state: *architecture.CpuState) void {
     // Zero through the physmap (the frames aren't mapped in the caller yet), then map.
     const kernel_view: [*]u8 = @ptrFromInt(boot_handoff.physicalToVirtual(phys));
     @memset(kernel_view[0 .. pages * page_size], 0);
-    architecture.mapUserDmaInto(t.aspace, base_v, phys, pages * page_size);
+    architecture.mapUserDmaInto(t.address_space, base_v, phys, pages * page_size);
 
     t.dma_map_next = base_v + pages * page_size;
     architecture.setSystemCallResult(state, base_v); // virtual address for the CPU
     architecture.setSystemCallResult2(state, phys); // physical address for the device
 }
 
-/// dma_free(vaddr, len) -> 0: release a prior `dma_alloc`. Bounded to the DMA arena so
+/// dma_free(virtual_address, len) -> 0: release a prior `dma_alloc`. Bounded to the DMA arena so
 /// it can never unmap-and-free the caller's stack, heap, or an MMIO grant; only pages
 /// actually mapped are freed (an unmapped hole is skipped). Teardown also reclaims any
 /// DMA pages left mapped at exit (they carry no `device_grant`, so `freeSubtree` frees
@@ -461,21 +483,21 @@ fn systemDmaFree(state: *architecture.CpuState) void {
     const base_v = architecture.systemCallArg(state, 0);
     const len = architecture.systemCallArg(state, 1);
     const t = scheduler.current();
-    if (t.aspace == 0) return fail(state);
+    if (t.address_space == 0) return fail(state);
     const pages: usize = @intCast((len + page_size - 1) / page_size);
     if (base_v < dma_arena_base or base_v + pages * page_size > dma_arena_end) return fail(state);
 
     for (0..pages) |i| {
         const va = base_v + i * page_size;
-        if (architecture.translate(t.aspace, va)) |phys| {
-            architecture.unmapUserPageInto(t.aspace, va);
+        if (architecture.translate(t.address_space, va)) |phys| {
+            architecture.unmapUserPageInto(t.address_space, va);
             pmm.free(phys);
         }
     }
     architecture.setSystemCallResult(state, 0);
 }
 
-/// shm_create(len) -> vaddr (rax), handle (rdx): grant `len` bytes (rounded up to whole
+/// shm_create(len) -> virtual_address (rax), handle (rdx): grant `len` bytes (rounded up to whole
 /// pages) of **shareable, zeroed, cacheable** RAM — contiguous frames mapped into the
 /// caller's shm arena — and hand back the virtual address plus a capability handle. Unlike
 /// `dma_alloc` the memory is write-back cacheable (for CPU compositing, not device DMA) and
@@ -486,7 +508,7 @@ fn systemDmaFree(state: *architecture.CpuState) void {
 fn systemShmCreate(state: *architecture.CpuState) void {
     const len = architecture.systemCallArg(state, 0);
     const t = scheduler.current();
-    if (t.aspace == 0 or len == 0) return fail(state);
+    if (t.address_space == 0 or len == 0) return fail(state);
 
     const pages: usize = @intCast((len + page_size - 1) / page_size);
     if (pages == 0 or pages > maximum_shm_pages) return fail(state);
@@ -511,20 +533,20 @@ fn systemShmCreate(state: *architecture.CpuState) void {
         return fail(state);
     }
 
-    architecture.mapUserSharedInto(t.aspace, base_v, phys, pages * page_size);
+    architecture.mapUserSharedInto(t.address_space, base_v, phys, pages * page_size);
     t.shm_map_next = base_v + pages * page_size;
-    architecture.setSystemCallResult(state, base_v); // vaddr for the CPU
+    architecture.setSystemCallResult(state, base_v); // virtual_address for the CPU
     architecture.setSystemCallResult2(state, @intCast(handle)); // capability handle to pass on
 }
 
-/// shm_map(cap) -> vaddr: map the shared region named by a capability handle the caller
+/// shm_map(cap) -> virtual_address: map the shared region named by a capability handle the caller
 /// received (via an `ipc_call` send_cap) into its shm arena — the same physical frames the
 /// creator sees — returning the virtual address. The handle already holds a reference (taken
 /// when the capability was shared), so this only adds a mapping; it never bumps the refcount.
 fn systemShmMap(state: *architecture.CpuState) void {
     const cap = architecture.systemCallArg(state, 0);
     const t = scheduler.current();
-    if (t.aspace == 0) return fail(state);
+    if (t.address_space == 0) return fail(state);
 
     const shm = ipc.resolveShm(t, cap) orelse return fail(state); // not an shm handle we hold
     if (t.shm_map_next == 0) t.shm_map_next = shm_arena_base;
@@ -532,12 +554,12 @@ fn systemShmMap(state: *architecture.CpuState) void {
     const size = shm.pages * page_size;
     if (base_v + size > shm_arena_end) return fail(state);
 
-    architecture.mapUserSharedInto(t.aspace, base_v, shm.phys, size);
+    architecture.mapUserSharedInto(t.address_space, base_v, shm.phys, size);
     t.shm_map_next = base_v + size;
     architecture.setSystemCallResult(state, base_v);
 }
 
-/// shm_physical(cap) -> paddr: the guest-physical base of a shared region the caller holds a
+/// shm_physical(cap) -> physical_address: the guest-physical base of a shared region the caller holds a
 /// capability for. The frames are contiguous (allocated by `allocContiguous`), so a single
 /// physical base + length describes the whole region — which is exactly what a driver needs
 /// to hand a shm surface to a device (virtio-gpu `attach_backing`). Only a holder of the
@@ -545,7 +567,7 @@ fn systemShmMap(state: *architecture.CpuState) void {
 fn systemShmPhysical(state: *architecture.CpuState) void {
     const cap = architecture.systemCallArg(state, 0);
     const t = scheduler.current();
-    if (t.aspace == 0) return fail(state);
+    if (t.address_space == 0) return fail(state);
     const shm = ipc.resolveShm(t, cap) orelse return fail(state); // not an shm handle we hold
     architecture.setSystemCallResult(state, shm.phys);
 }
@@ -566,10 +588,10 @@ fn systemDeviceRegister(state: *architecture.CpuState) void {
     const parent_id = architecture.systemCallArg(state, 0);
     const descriptor_ptr = architecture.systemCallArg(state, 1);
     const t = scheduler.current();
-    if (t.aspace == 0) return fail(state);
+    if (t.address_space == 0) return fail(state);
 
     var descriptor: device_abi.DeviceDescriptor = undefined;
-    if (!ipc.copyFromUser(t.aspace, descriptor_ptr, std.mem.asBytes(&descriptor))) return fail(state);
+    if (!ipc.copyFromUser(t.address_space, descriptor_ptr, std.mem.asBytes(&descriptor))) return fail(state);
 
     // Under the big kernel lock: the broker's table is also mutated by the
     // death sweep (releaseAllOwnedBy) and read by enumerate on other cores —
@@ -642,6 +664,125 @@ fn systemSpawn(state: *architecture.CpuState) void {
     fail(state); // no bundled binary by that name
 }
 
+/// thread_spawn(entry, stack_top, arg) -> tid: start a task that shares the **caller's**
+/// address space (docs/threading.md). The runtime supplies `entry` (its thread
+/// trampoline), a stack it mmap'd, and the closure pointer, which the kernel delivers in
+/// the new thread's rdi. The entry and stack must lie in the user half; the new thread is
+/// supervised by the caller and inherits its priority. Only a user process may spawn.
+fn systemThreadSpawn(state: *architecture.CpuState) void {
+    const entry = architecture.systemCallArg(state, 0);
+    const stack_top = architecture.systemCallArg(state, 1);
+    const arg = architecture.systemCallArg(state, 2);
+    const exit_handle = architecture.systemCallArg(state, 3);
+    const t = scheduler.current();
+    if (t.address_space == 0) return fail(state); // kernel tasks own no address space to share
+    if (entry == 0 or entry >= user_half_end) return fail(state);
+    if (stack_top == 0 or stack_top > user_half_end) return fail(state);
+    // The endpoint the thread notifies on exit (how join waits), or none.
+    const exit_endpoint: ?*ipc.Endpoint = if (exit_handle == abi.no_cap)
+        null
+    else
+        ipc.resolveHandle(t, exit_handle) orelse return failErr(state, ipc.EBADF);
+    const tid = spawnThreadSupervised(t.address_space, entry, stack_top, arg, t.priority, t.id, exit_endpoint) orelse return fail(state);
+    architecture.setSystemCallResult(state, tid);
+}
+
+/// Spawn a thread sharing `address_space`, taking the exit-endpoint reference under the **same**
+/// lock as the spawn (as `spawnProcessSupervised` does), so the thread cannot die before
+/// its reference exists. Returns the new thread id, or null on resource exhaustion.
+fn spawnThreadSupervised(address_space: u64, entry: u64, stack_top: u64, arg: u64, priority: scheduler.Priority, supervisor: u32, exit_endpoint: ?*ipc.Endpoint) ?u32 {
+    const flags = sync.enter();
+    defer sync.leave(flags);
+    const tid = scheduler.spawnUserLocked(address_space, entry, stack_top, arg, priority, "thread", supervisor, if (exit_endpoint) |e| @ptrCast(e) else null) orelse return null;
+    if (exit_endpoint) |endpoint| endpoint.refcount += 1; // the thread holds it birth-to-death
+    return tid;
+}
+
+/// current_core() -> index: the dense 0-based index of the core the caller runs on.
+fn systemCurrentCore(state: *architecture.CpuState) void {
+    architecture.setSystemCallResult(state, scheduler.currentCpuIndex());
+}
+
+/// thread_self() -> tid: the calling thread's kernel task id.
+fn systemThreadSelf(state: *architecture.CpuState) void {
+    architecture.setSystemCallResult(state, scheduler.currentId());
+}
+
+/// set_thread_pointer(addr) -> 0: set the caller's user-space TLS thread pointer. The
+/// arch layer maps it to IA32_FS_BASE on x86_64, `TPIDR_EL0` on aarch64; the kernel
+/// never reads it, and the scheduler restores it per task across context switches
+/// (docs/threading-plan.md M10). `addr` must be a user-half address.
+fn systemSetThreadPointer(state: *architecture.CpuState) void {
+    const addr = architecture.systemCallArg(state, 0);
+    const t = scheduler.current();
+    if (t.address_space == 0) return fail(state); // kernel tasks have no user TLS
+    if (addr >= user_half_end) return fail(state);
+    const flags = sync.enter();
+    scheduler.setThreadPointerLocked(addr);
+    sync.leave(flags);
+    architecture.setSystemCallResult(state, 0);
+}
+
+/// thread_join(tid) -> 0: block until the thread with id `tid` has exited (docs/threading-
+/// plan.md M9). Needs no per-thread IPC endpoint. The compare-and-block is one critical
+/// section, so an exit cannot slip between "is it alive?" and the block.
+fn systemThreadJoin(state: *architecture.CpuState) void {
+    const tid: u32 = @truncate(architecture.systemCallArg(state, 0));
+    const t = scheduler.current();
+    if (t.address_space == 0) return fail(state); // kernel tasks don't join
+    const flags = sync.enter();
+    scheduler.joinThreadLocked(tid);
+    sync.leave(flags);
+    architecture.setSystemCallResult(state, 0);
+}
+
+/// futex_wait(addr, expected, timeout_ns) -> status (docs/threading.md): if the 4-byte
+/// user word at `addr` still equals `expected`, block until a futex_wake on `addr` or
+/// (if timeout_ns > 0) the deadline. The compare and the block are one critical section,
+/// so a concurrent futex_wake cannot slip between them. Returns futex_woken / mismatch /
+/// timed_out.
+fn systemFutexWait(state: *architecture.CpuState) void {
+    const addr = architecture.systemCallArg(state, 0);
+    const expected: u32 = @truncate(architecture.systemCallArg(state, 1));
+    const timeout_ns = architecture.systemCallArg(state, 2);
+    const t = scheduler.current();
+    if (t.address_space == 0) return fail(state);
+    if (addr == 0 or (addr & 3) != 0 or addr + 4 > user_half_end) return fail(state);
+
+    const flags = sync.enter();
+    var word_bytes: [4]u8 = undefined;
+    if (!ipc.copyFromUser(t.address_space, addr, &word_bytes)) {
+        sync.leave(flags);
+        return fail(state);
+    }
+    if (std.mem.readInt(u32, &word_bytes, .little) != expected) {
+        sync.leave(flags);
+        architecture.setSystemCallResult(state, abi.futex_mismatch);
+        return;
+    }
+    const timeout_ms = if (timeout_ns == 0) 0 else (timeout_ns + 999_999) / 1_000_000;
+    const result = scheduler.futexWaitLocked(addr, timeout_ms);
+    sync.leave(flags);
+    architecture.setSystemCallResult(state, switch (result) {
+        .woken => abi.futex_woken,
+        .timed_out => abi.futex_timed_out,
+    });
+}
+
+/// futex_wake(addr, count) -> woken: wake up to `count` tasks blocked in futex_wait on
+/// `addr` in the caller's address space.
+fn systemFutexWake(state: *architecture.CpuState) void {
+    const addr = architecture.systemCallArg(state, 0);
+    const count: u32 = @truncate(architecture.systemCallArg(state, 1));
+    const t = scheduler.current();
+    if (t.address_space == 0) return fail(state);
+    if (addr == 0 or (addr & 3) != 0 or addr + 4 > user_half_end) return fail(state);
+    const flags = sync.enter();
+    const woken = scheduler.futexWakeLocked(t.address_space, addr, count);
+    sync.leave(flags);
+    architecture.setSystemCallResult(state, woken);
+}
+
 /// process_enumerate(buffer, maximum) -> total: snapshot the task table into the
 /// caller's buffer (up to `maximum` `abi.ProcessDescriptor` entries), returning
 /// the total live-task count — the exact shape of `device_enumerate`, so a `ps`
@@ -652,7 +793,7 @@ fn systemProcessEnumerate(state: *architecture.CpuState) void {
     const buffer_ptr = architecture.systemCallArg(state, 0);
     const maximum = architecture.systemCallArg(state, 1);
     const t = scheduler.current();
-    if (t.aspace == 0 or buffer_ptr >= user_half_end) return fail(state);
+    if (t.address_space == 0 or buffer_ptr >= user_half_end) return fail(state);
     const sz = @sizeOf(abi.ProcessDescriptor);
     const cap = @min(maximum, (user_half_end - buffer_ptr) / sz); // clamp to the user half
     const out: [*]abi.ProcessDescriptor = @ptrFromInt(buffer_ptr);
@@ -665,7 +806,7 @@ fn systemProcessEnumerate(state: *architecture.CpuState) void {
 /// cannot be a weapon (ids are never reused, so a stale one just misses).
 fn systemProcessKill(state: *architecture.CpuState) void {
     const t = scheduler.current();
-    if (t.aspace == 0) return fail(state);
+    if (t.address_space == 0) return fail(state);
     const id = architecture.systemCallArg(state, 0);
     if (id > std.math.maxInt(u32)) return failErr(state, ipc.ESRCH);
     const r = killProcess(t.id, @intCast(id));
@@ -798,7 +939,7 @@ pub fn killProcess(caller_id: u32, target_id: u32) i64 {
     const flags = sync.enter();
     defer sync.leave(flags);
     const target = scheduler.taskByIdLocked(target_id) orelse return -ipc.ESRCH;
-    if (target.aspace == 0) return -ipc.ESRCH; // kernel tasks are not processes
+    if (target.address_space == 0) return -ipc.ESRCH; // kernel tasks are not processes
     if (target.supervisor != caller_id) return -ipc.EPERM;
     target.exit_reason = .killed;
     if (target.state == .running) {
@@ -868,7 +1009,7 @@ var exit_subscribers: [exit_subscriber_capacity]?ExitSubscriber = .{null} ** exi
 /// secret between cooperating processes. -ENOSPC when the table is full.
 fn systemProcessSubscribe(state: *architecture.CpuState) void {
     const t = scheduler.current();
-    if (t.aspace == 0) return fail(state);
+    if (t.address_space == 0) return fail(state);
     const endpoint = ipc.resolveHandle(t, architecture.systemCallArg(state, 0)) orelse return failErr(state, ipc.EBADF);
     const flags = sync.enter();
     defer sync.leave(flags);
@@ -888,7 +1029,7 @@ fn systemProcessSubscribe(state: *architecture.CpuState) void {
 /// delivered immediately on bind, coalesced into one notification.
 fn systemSignalBind(state: *architecture.CpuState) void {
     const t = scheduler.current();
-    if (t.aspace == 0) return fail(state);
+    if (t.address_space == 0) return fail(state);
     const endpoint = ipc.resolveHandle(t, architecture.systemCallArg(state, 0)) orelse return failErr(state, ipc.EBADF);
     const flags = sync.enter();
     defer sync.leave(flags);
@@ -908,7 +1049,7 @@ fn systemSignalBind(state: *architecture.CpuState) void {
 /// targets accumulate the signal in their pending mask.
 fn systemProcessSignal(state: *architecture.CpuState) void {
     const t = scheduler.current();
-    if (t.aspace == 0) return fail(state);
+    if (t.address_space == 0) return fail(state);
     const id = architecture.systemCallArg(state, 0);
     const signal = architecture.systemCallArg(state, 1);
     if (id > std.math.maxInt(u32)) return failErr(state, ipc.ESRCH);
@@ -916,7 +1057,7 @@ fn systemProcessSignal(state: *architecture.CpuState) void {
     const flags = sync.enter();
     defer sync.leave(flags);
     const target = scheduler.taskByIdLocked(@intCast(id)) orelse return failErr(state, ipc.ESRCH);
-    if (target.aspace == 0) return failErr(state, ipc.ESRCH);
+    if (target.address_space == 0) return failErr(state, ipc.ESRCH);
     if (target.supervisor != t.id and target.id != t.id) return failErr(state, ipc.EPERM);
     target.pending_signals |= @as(u32, 1) << @intCast(signal);
     if (target.signal_endpoint) |raw| {
@@ -953,7 +1094,7 @@ fn timerSweepLocked() void {
 /// timer_bind(endpoint, ms): arm a one-shot timer. -ENOSPC when the table is full.
 fn systemTimerBind(state: *architecture.CpuState) void {
     const t = scheduler.current();
-    if (t.aspace == 0) return fail(state);
+    if (t.address_space == 0) return fail(state);
     const endpoint = ipc.resolveHandle(t, architecture.systemCallArg(state, 0)) orelse return failErr(state, ipc.EBADF);
     const ms = architecture.systemCallArg(state, 1);
     const flags = sync.enter();
@@ -970,7 +1111,7 @@ fn systemTimerBind(state: *architecture.CpuState) void {
 
 fn systemProcessExitReason(state: *architecture.CpuState) void {
     const t = scheduler.current();
-    if (t.aspace == 0) return fail(state);
+    if (t.address_space == 0) return fail(state);
     const id = architecture.systemCallArg(state, 0);
     if (id > std.math.maxInt(u32)) return failErr(state, ipc.ESRCH);
     const r = exitReasonOf(t.id, @intCast(id));
@@ -996,7 +1137,7 @@ fn ownedGsi(t: *scheduler.Task, device_id: u64, resource_index: u64) ?u32 {
 /// IPC_ReplyWait and is woken by the ISR; see system/kernel/irq.zig for the cycle.
 fn systemIrqBind(state: *architecture.CpuState) void {
     const t = scheduler.current();
-    if (t.aspace == 0) return fail(state);
+    if (t.address_space == 0) return fail(state);
     const gsi = ownedGsi(t, architecture.systemCallArg(state, 0), architecture.systemCallArg(state, 1)) orelse
         return fail(state);
     const endpoint = ipc.resolveHandle(t, architecture.systemCallArg(state, 2)) orelse return fail(state);
@@ -1016,7 +1157,7 @@ fn systemIrqBind(state: *architecture.CpuState) void {
 fn systemMsiBind(state: *architecture.CpuState) void {
     const device_id = architecture.systemCallArg(state, 0);
     const t = scheduler.current();
-    if (t.aspace == 0) return fail(state);
+    if (t.address_space == 0) return fail(state);
     const owner = devices_broker.ownerOf(device_id) orelse return fail(state);
     if (owner != t.id) return fail(state); // not claimed by this process
     const endpoint = ipc.resolveHandle(t, architecture.systemCallArg(state, 1)) orelse return failErr(state, ipc.EBADF);
@@ -1035,7 +1176,7 @@ fn systemMsiBind(state: *architecture.CpuState) void {
 /// more arrives until the driver says it has serviced the hardware.
 fn systemIrqAck(state: *architecture.CpuState) void {
     const t = scheduler.current();
-    if (t.aspace == 0) return fail(state);
+    if (t.address_space == 0) return fail(state);
     const gsi = ownedGsi(t, architecture.systemCallArg(state, 0), architecture.systemCallArg(state, 1)) orelse
         return fail(state);
 
@@ -1123,37 +1264,52 @@ fn systemKlogRead(state: *architecture.CpuState) void {
 fn systemMmap(state: *architecture.CpuState) void {
     const len = architecture.systemCallArg(state, 0);
     const t = scheduler.current();
-    if (t.aspace == 0) return fail(state); // not a user process — nothing to map into
+    if (t.address_space == 0) return fail(state); // not a user process — nothing to map into
     const pages = (len + page_size - 1) / page_size;
     if (pages == 0 or pages > maximum_mmap_pages) return fail(state);
 
-    if (t.heap_next == 0) t.heap_next = heap_arena_base; // seed the arena lazily
-    const base = t.heap_next;
-    if (base + pages * page_size > heap_arena_end) return fail(state); // arena exhausted
+    // Reserve a disjoint range under a *brief* lock (the cursor is shared by every thread
+    // in this address space). The mapping below then takes the lock **per page**, not for
+    // the whole grant: the big lock is held with interrupts disabled, so pinning it across
+    // a multi-MiB memset+map would freeze every other core on its next tick — which timed
+    // the `affinity` scenario out (docs/threading-plan.md M7).
+    const base = reserve: {
+        const flags = sync.enter();
+        defer sync.leave(flags);
+        const cursor = scheduler.addressSpaceMmapNextPtr(t.address_space) orelse return fail(state);
+        if (cursor.* == 0) cursor.* = heap_arena_base; // seed the arena lazily
+        const b = cursor.*;
+        if (b + pages * page_size > heap_arena_end) return fail(state); // arena exhausted
+        cursor.* = b + pages * page_size; // reserve now, so concurrent grants can't overlap
+        break :reserve b;
+    };
 
-    // Map page by page. On mid-way frame exhaustion, roll back the pages already mapped
-    // (unmap + free) so no partial grant leaks into the address space — the same
-    // all-or-nothing guarantee as before, but without a fixed scratch array, so the
-    // per-call size can be a multi-MiB framebuffer.
+    // Map the reserved range page by page, each page under a short-held lock (the range is
+    // already reserved, so pages can't overlap another thread's; the lock only serializes
+    // the shared page-table walk). On mid-way frame exhaustion, roll back the mapped pages
+    // so no partial grant leaks — the reserved-but-unmapped tail of the arena is left
+    // fallow (a rare, bounded address-space leak, not a memory leak).
     var mapped: usize = 0;
     while (mapped < pages) : (mapped += 1) {
+        const flags = sync.enter();
         const frame = pmm.alloc() orelse {
             var i: usize = 0;
             while (i < mapped) : (i += 1) {
                 const va = base + i * page_size;
-                if (architecture.translate(t.aspace, va)) |physical| {
-                    architecture.unmapUserPageInto(t.aspace, va);
+                if (architecture.translate(t.address_space, va)) |physical| {
+                    architecture.unmapUserPageInto(t.address_space, va);
                     pmm.free(physical);
                 }
             }
+            sync.leave(flags);
             return fail(state);
         };
         const destination: [*]u8 = @ptrFromInt(boot_handoff.physicalToVirtual(frame));
         @memset(destination[0..page_size], 0); // hand out zeroed memory
-        architecture.mapUserPageInto(t.aspace, base + mapped * page_size, frame, true, false); // RW + NX
+        architecture.mapUserPageInto(t.address_space, base + mapped * page_size, frame, true, false); // RW + NX
+        sync.leave(flags);
     }
-    t.heap_next = base + pages * page_size;
-    architecture.setSystemCallResult(state, base);
+    architecture.setSystemCallResult(state, base); // the cursor was already advanced at reserve
 }
 
 /// munmap(base, len): release a range previously handed out by `mmap`. Unmaps
@@ -1165,14 +1321,14 @@ fn systemMunmap(state: *architecture.CpuState) void {
     const base = architecture.systemCallArg(state, 0);
     const len = architecture.systemCallArg(state, 1);
     const t = scheduler.current();
-    if (t.aspace == 0 or base % page_size != 0) return fail(state);
+    if (t.address_space == 0 or base % page_size != 0) return fail(state);
     const pages = (len + page_size - 1) / page_size;
     if (base < heap_arena_base or base + pages * page_size > heap_arena_end) return fail(state);
 
     for (0..pages) |i| {
         const va = base + i * page_size;
-        if (architecture.translate(t.aspace, va)) |physical| {
-            architecture.unmapUserPageInto(t.aspace, va);
+        if (architecture.translate(t.address_space, va)) |physical| {
+            architecture.unmapUserPageInto(t.address_space, va);
             pmm.free(physical);
         }
     }
@@ -1236,7 +1392,7 @@ const maximum_segments = 16;
 const maximum_pages = 256; // 1 MiB loader budget; the user region caps at 2 MiB anyway
 
 const Segment = struct {
-    vaddr: u64,
+    virtual_address: u64,
     memsz: u64,
     filesz: u64,
     off: u64,
@@ -1284,7 +1440,7 @@ fn parseSegments(image: []const u8, segs: *[maximum_segments]Segment) InitError!
         if (w and x) return error.BadSegment; // W^X, even for init
 
         const seg = Segment{
-            .vaddr = phdr.p_vaddr,
+            .virtual_address = phdr.p_vaddr,
             .memsz = phdr.p_memsz,
             .filesz = phdr.p_filesz,
             .off = phdr.p_offset,
@@ -1293,9 +1449,9 @@ fn parseSegments(image: []const u8, segs: *[maximum_segments]Segment) InitError!
         };
         // No overlap with any earlier segment (page-granular, since mapping is).
         for (segs[0..count]) |other| {
-            const a_end = seg.vaddr + seg.pages() * page_size;
-            const b_end = other.vaddr + other.pages() * page_size;
-            if (seg.vaddr < b_end and other.vaddr < a_end) return error.BadSegment;
+            const a_end = seg.virtual_address + seg.pages() * page_size;
+            const b_end = other.virtual_address + other.pages() * page_size;
+            if (seg.virtual_address < b_end and other.virtual_address < a_end) return error.BadSegment;
         }
         total_pages += seg.pages();
         if (total_pages > maximum_pages) return error.ProgramTooBig;
@@ -1306,17 +1462,17 @@ fn parseSegments(image: []const u8, segs: *[maximum_segments]Segment) InitError!
 
     // The entry point must land inside an executable segment.
     for (segs[0..count]) |seg| {
-        if (seg.executable and ehdr.e_entry >= seg.vaddr and ehdr.e_entry < seg.vaddr + seg.memsz)
+        if (seg.executable and ehdr.e_entry >= seg.virtual_address and ehdr.e_entry < seg.virtual_address + seg.memsz)
             return .{ .count = count, .entry = ehdr.e_entry };
     }
     return error.BadEntry;
 }
 
-/// Load one page of a segment into address space `aspace`: a fresh frame, zeroed
+/// Load one page of a segment into address space `address_space`: a fresh frame, zeroed
 /// and filled through the physmap, mapped user-accessible with the segment's W^X.
 /// On a later failure the whole address space is torn down, which frees every
 /// frame mapped into it — so no per-page rollback list is needed here.
-fn loadPageInto(aspace: u64, image: []const u8, seg: Segment, page_index: u64) InitError!void {
+fn loadPageInto(address_space: u64, image: []const u8, seg: Segment, page_index: u64) InitError!void {
     const frame = pmm.alloc() orelse return error.OutOfMemory;
     const destination: [*]u8 = @ptrFromInt(boot_handoff.physicalToVirtual(frame));
     @memset(destination[0..page_size], 0);
@@ -1325,7 +1481,7 @@ fn loadPageInto(aspace: u64, image: []const u8, seg: Segment, page_index: u64) I
         const n = @min(page_size, seg.filesz - page_off);
         @memcpy(destination[0..n], image[seg.off + page_off ..][0..n]);
     }
-    architecture.mapUserPageInto(aspace, seg.vaddr + page_off, frame, seg.writable, seg.executable);
+    architecture.mapUserPageInto(address_space, seg.virtual_address + page_off, frame, seg.writable, seg.executable);
 }
 
 /// Build the System V AMD64 process-entry block at the top of a process's stack
@@ -1412,11 +1568,11 @@ pub fn spawnProcessSupervised(image: []const u8, priority: u3, argv: []const []c
     const flags = sync.enter();
     defer sync.leave(flags);
 
-    const aspace = architecture.createAddressSpace() orelse return error.OutOfMemory;
-    errdefer architecture.destroyAddressSpace(aspace);
+    const address_space = architecture.createAddressSpace() orelse return error.OutOfMemory;
+    errdefer architecture.destroyAddressSpace(address_space);
 
     for (segs[0..parsed.count]) |seg| {
-        for (0..seg.pages()) |i| try loadPageInto(aspace, image, seg, i);
+        for (0..seg.pages()) |i| try loadPageInto(address_space, image, seg, i);
     }
 
     // The stack: `user_stack_pages` zeroed pages below stack_top_virtual, RW + NX.
@@ -1430,10 +1586,10 @@ pub fn spawnProcessSupervised(image: []const u8, priority: u3, argv: []const []c
         const page_virtual = stack_base_virtual + i * page_size;
         if (i == parameters.user_stack_pages - 1)
             user_sp = buildEntryStack(stack_page, page_virtual, argv);
-        architecture.mapUserPageInto(aspace, page_virtual, stack_frame, true, false); // RW + NX
+        architecture.mapUserPageInto(address_space, page_virtual, stack_frame, true, false); // RW + NX
     }
 
-    const child = scheduler.spawnUserLocked(aspace, parsed.entry, user_sp, priority, argv[0], supervisor, if (exit_endpoint) |endpoint| @ptrCast(endpoint) else null) orelse
+    const child = scheduler.spawnUserLocked(address_space, parsed.entry, user_sp, 0, priority, argv[0], supervisor, if (exit_endpoint) |endpoint| @ptrCast(endpoint) else null) orelse
         return error.OutOfMemory;
     // The child holds a reference to its exit endpoint from birth to death. Taken
     // only now, after nothing can fail; the lock is still held, so the child

system/kernel/scheduler.zig

@@ -31,7 +31,10 @@ const number_priorities = 8;
 const stack_size = parameters.kernel_stack_size; // each task's kernel stack
 const maximum_tasks = parameters.maximum_tasks; // maximum tasks alive at once (static pool)
 
-const State = enum { free, ready, running, blocked };
+// `reaping` = the task has exited and is queued on its core's reap list; its slot must not
+// be reused (freeSlot skips it) until the reaper has freed its kernel stack and set it
+// `free` (docs/threading-plan.md M8/M9).
+const State = enum { free, ready, running, blocked, reaping };
 
 pub const Task = struct {
     id: u32 = 0,
@@ -75,16 +78,25 @@ pub const Task = struct {
     ipc_wait_endpoint: ?*anyopaque = null,
     // Physical root of this task's address space, or 0 for a kernel task (which
     // runs on the shared kernel page tables). A user task carries its own.
-    aspace: u64 = 0,
+    address_space: u64 = 0,
     user_ip: u64 = 0, // user-mode entry point (user task only)
     user_sp: u64 = 0, // user-mode stack pointer (user task only)
-    // Next free virtual address in this task's mmap grant arena (0 = uninitialised;
-    // process.zig lazily seeds it to the arena base on the first mmap). Bumped up
-    // as the user heap grows; user task only.
-    heap_next: u64 = 0,
-    // Next free virtual address in this task's MMIO-grant arena (PML4[226]; 0 =
-    // uninitialised, process.zig seeds it on the first mmio_map). User task only.
-    device_map_next: u64 = 0,
+    user_arg: u64 = 0, // value delivered in the user's first argument register at first entry
+    // (rdi on x86_64, via architecture.jumpToUserArg): 0 for a process (its _start ignores
+    // it), the closure pointer for a thread (docs/threading.md)
+    // The user address this task is blocked on in futex_wait (0 = not futex-waiting).
+    // Cleared to 0 by futexWakeLocked as the "woken, not timed out" signal (docs/threading.md).
+    futex_addr: u64 = 0,
+    // The task id this task is blocked in `thread_join` on (0 = not joining). Woken by
+    // `wakeJoinersLocked` when that task exits (docs/threading-plan.md M9).
+    join_target: u32 = 0,
+    // This task's user-space TLS thread pointer — 0 until set via `set_thread_pointer`.
+    // Architecture-neutral: the arch layer maps it to the FS base on x86_64, `TPIDR_EL0` on
+    // aarch64. Restored on every context switch to this task (docs/threading-plan.md M10).
+    thread_pointer: u64 = 0,
+    // The mmap / MMIO grant-arena cursors moved from Task to the per-address-space object
+    // (`AddressSpaceRef`, below) so threads sharing one address space hand out disjoint grants
+    // — see addressSpaceMmapNextPtr / addressSpaceDeviceMapNextPtr (docs/threading-plan.md M7).
     // --- synchronous IPC (ipc_sync.zig) ---
     // Per-process handle table: a small-int handle names a kernel capability object.
     // Each entry tags its `kind` (an IPC endpoint or a shared-memory object) so the
@@ -95,9 +107,9 @@ pub const Task = struct {
     // receive, cleared when it replies). A client, while blocked in Call, records
     // its message + reply buffers here and its result lands in `ipc_status`.
     ipc_client: ?*Task = null,
-    ipc_send_ptr: u64 = 0, // client: outgoing message (vaddr in this task's AS)
+    ipc_send_ptr: u64 = 0, // client: outgoing message (virtual_address in this task's address space)
     ipc_send_len: u64 = 0,
-    ipc_reply_ptr: u64 = 0, // client: reply buffer (vaddr)
+    ipc_reply_ptr: u64 = 0, // client: reply buffer (virtual_address)
     ipc_reply_cap: u64 = 0,
     ipc_status: i64 = 0, // client: reply length / -errno, written by the replier
     dma_map_next: u64 = 0, // bump pointer into this task's DMA arena (0 = unseeded)
@@ -136,6 +148,127 @@ pub const ipc_maximum_handles = 16;
 pub const HandleObject = struct { kind: u8, ptr: *anyopaque };
 
 var tasks = [_]Task{.{}} ** maximum_tasks;
+
+/// Address-space reference counts: one live entry per address space, counting the
+/// tasks that share it. An address space is 1:1 with a process today; threads
+/// (docs/threading.md) will push a count above 1, and `destroyAddressSpace` must run
+/// only when the **last** task on an address space exits. All access is under the big
+/// kernel lock. There can be no more live address spaces than tasks, so the table is
+/// sized to the task pool and never overflows in practice.
+// The per-address-space kernel object: a reference count plus the grant-arena cursors.
+// One live entry per address space; threads sharing an address space share this entry,
+// so their mmap/mmio grants bump one cursor and never overlap (docs/threading-plan.md M7).
+// `mmap_next`/`device_map_next` are 0 until process.zig seeds them to the arena base.
+const AddressSpaceRef = struct { root: u64 = 0, count: u32 = 0, mmap_next: u64 = 0, device_map_next: u64 = 0 };
+var address_space_refs = [_]AddressSpaceRef{.{}} ** maximum_tasks;
+var address_space_destroy_count: u64 = 0;
+
+/// Total bytes of task **kernel** stacks currently allocated from the kernel heap —
+/// incremented when a task is created, decremented when the reaper frees a dead task's
+/// stack. A test-observable proof that the reaper reclaims every stack (docs/threading-
+/// plan.md M8): with no live tasks beyond the baseline, this returns to its baseline.
+var live_stack_bytes: usize = 0;
+
+/// Test-observable: bytes of task kernel stacks currently live (see `live_stack_bytes`).
+pub fn liveStackBytes() usize {
+    return live_stack_bytes;
+}
+
+/// Free a dead task's kernel stack and drop it from `live_stack_bytes`. The task must be
+/// off that stack already (killed while not running, or reaped after it switched away).
+/// Caller holds the kernel lock.
+fn reapStackLocked(t: *Task) void {
+    if (t.stack.len == 0) return; // boot/idle tasks run on a static stack — nothing to free
+    live_stack_bytes -= t.stack.len;
+    heap.allocator().free(t.stack);
+    t.stack = &.{};
+    t.kstack_top = 0;
+}
+
+/// Free every `.reaping` task queued on this core's reap list and mark each `.free` (now
+/// its slot may be reused). The tasks are all off their stacks (they switched away), and
+/// the caller holds the lock, so freeing is safe (docs/threading-plan.md M8/M9).
+fn drainReapListLocked(pc: *PerCpu) void {
+    var node = pc.reap_list;
+    pc.reap_list = null;
+    while (node) |t| {
+        node = t.next; // save the link before we clear it
+        t.next = null;
+        reapStackLocked(t);
+        t.state = .free; // reusable only now, after the stack is freed
+    }
+}
+
+/// Take a reference to address space `root` (0 = a kernel task, which owns none).
+/// Returns false only if the ref table is full — bounded by `maximum_tasks`, so in
+/// practice it never is. Caller holds the kernel lock.
+fn retainAddressSpace(root: u64) bool {
+    if (root == 0) return true;
+    var free: ?*AddressSpaceRef = null;
+    for (&address_space_refs) |*entry| {
+        if (entry.count != 0 and entry.root == root) {
+            entry.count += 1;
+            return true;
+        }
+        if (entry.count == 0 and free == null) free = entry;
+    }
+    const slot = free orelse return false;
+    slot.* = .{ .root = root, .count = 1 };
+    return true;
+}
+
+/// Drop a reference to `root`; destroy the address space when the **last** one drops.
+/// A `root` with no entry — never retained, e.g. a hand-built test space — is
+/// destroyed directly, preserving the pre-refcount behaviour. Caller holds the lock.
+fn releaseAddressSpace(root: u64) void {
+    if (root == 0) return;
+    for (&address_space_refs) |*entry| {
+        if (entry.count == 0 or entry.root != root) continue;
+        entry.count -= 1;
+        if (entry.count == 0) {
+            entry.root = 0;
+            architecture.destroyAddressSpace(root);
+            address_space_destroy_count += 1;
+        }
+        return;
+    }
+    architecture.destroyAddressSpace(root);
+    address_space_destroy_count += 1;
+}
+
+/// Test-observable: how many address spaces are live (entries with a nonzero count).
+pub fn liveAddressSpaceCount() u32 {
+    var live: u32 = 0;
+    for (&address_space_refs) |*entry| {
+        if (entry.count != 0) live += 1;
+    }
+    return live;
+}
+
+/// Test-observable: total address-space destructions since boot.
+pub fn addressSpaceDestroyCount() u64 {
+    return address_space_destroy_count;
+}
+
+/// Pointer to the mmap grant-arena cursor for address space `root`, so the mmap syscall
+/// can read-and-bump it. Per-address-space (not per-task), so sibling threads get
+/// disjoint grants. **Caller holds the kernel lock** (the entry is stable while held).
+/// Null only if `root` was never retained — which can't happen for a live user task.
+pub fn addressSpaceMmapNextPtr(root: u64) ?*u64 {
+    for (&address_space_refs) |*entry| {
+        if (entry.count != 0 and entry.root == root) return &entry.mmap_next;
+    }
+    return null;
+}
+
+/// Pointer to the MMIO grant-arena cursor for address space `root` (see
+/// `addressSpaceMmapNextPtr`). Caller holds the kernel lock.
+pub fn addressSpaceDeviceMapNextPtr(root: u64) ?*u64 {
+    for (&address_space_refs) |*entry| {
+        if (entry.count != 0 and entry.root == root) return &entry.device_map_next;
+    }
+    return null;
+}
 var next_id: u32 = 1;
 
 /// Per-CPU scheduler state: the task each core is running, its own idle task, and a
@@ -155,11 +288,18 @@ pub const PerCpu = struct {
     hw_id: u32 = 0, // the core's hardware id (Local APIC id on x86_64)
     index: u32 = 0, // dense 0-based core index
     online: bool = false, // has this core finished bring-up?
-    loaded_aspace: u64 = 0, // the address-space root currently loaded on this core
+    loaded_address_space: u64 = 0, // the address-space root currently loaded on this core
+    loaded_thread_pointer: u64 = 0, // the TLS thread pointer currently loaded on this core (docs/threading-plan.md M10)
     // Tasks pinned to this core (affinity == index), per priority level + bitmap.
     pinned_head: [number_priorities]?*Task = .{null} ** number_priorities,
     pinned_tail: [number_priorities]?*Task = .{null} ** number_priorities,
     pinned_bitmap: u8 = 0,
+    // Tasks that ended while running on THIS core: they could not free the kernel stack
+    // they were standing on, so each pushed itself onto this list (`.reaping` state, linked
+    // via `Task.next`) and switched away. The next task to run on this core — or the timer
+    // tick — frees their stacks from its own stack, safely (docs/threading-plan.md M8). A
+    // *list* (not one slot) so a second death before the first is drained can't lose it.
+    reap_list: ?*Task = null,
 };
 
 const maximum_cpus = parameters.maximum_cpus;
@@ -191,7 +331,7 @@ var preemption_enabled = true;
 /// boot, before interrupts are enabled — so no lock is needed here.
 pub fn init(boot_priority: Priority) void {
     const pc = &cpus[0];
-    pc.* = .{ .index = 0, .online = true, .loaded_aspace = architecture.kernelPageTable() };
+    pc.* = .{ .index = 0, .online = true, .loaded_address_space = architecture.kernelPageTable() };
     architecture.setCpuLocal(0, @intFromPtr(pc));
     tasks[0] = .{ .id = 0, .state = .running, .priority = boot_priority };
     pc.current = &tasks[0];
@@ -230,7 +370,7 @@ pub fn secondaryMain() callconv(.c) noreturn {
     pc.current = t;
     pc.idle = t;
     pc.online = true;
-    pc.loaded_aspace = architecture.kernelPageTable(); // the AP adopted the kernel tables at bring-up
+    pc.loaded_address_space = architecture.kernelPageTable(); // the AP adopted the kernel tables at bring-up
     sync.leave(flags);
 
     architecture.enableInterrupts(); // the timer now preempts this idle context into work
@@ -316,7 +456,7 @@ pub fn spawnOn(entry: *const fn () void, priority: Priority, cpu: u32) bool {
     return ok;
 }
 
-/// Spawn a **user** task: a task with its own address space (`aspace`) that starts
+/// Spawn a **user** task: a task with its own address space (`address_space`) that starts
 /// in user mode at `entry` on `user_sp`, recorded under `name` (its argv[0]).
 /// `supervisor` is the id of the spawning process (0 = the kernel) — the kill
 /// authority — and `exit_endpoint` (an *ipc.Endpoint whose reference the caller
@@ -325,19 +465,27 @@ pub fn spawnOn(entry: *const fn () void, priority: Priority, cpu: u32) bool {
 /// lands in `user_task_trampoline`.
 /// Returns the new process id, or null (creating nothing) if the table is full or
 /// out of memory.
-/// **Caller must hold the kernel lock** (the loader that builds `aspace` holds it
+/// **Caller must hold the kernel lock** (the loader that builds `address_space` holds it
 /// across the whole spawn, so the address space and the task appear atomically).
-pub fn spawnUserLocked(aspace: u64, entry: u64, user_sp: u64, priority: Priority, task_name: []const u8, supervisor: u32, exit_endpoint: ?*anyopaque) ?u32 {
+pub fn spawnUserLocked(address_space: u64, entry: u64, user_sp: u64, user_arg: u64, priority: Priority, task_name: []const u8, supervisor: u32, exit_endpoint: ?*anyopaque) ?u32 {
     const t = freeSlot() orelse return null;
     const stack = heap.allocator().alloc(u8, stack_size) catch return null;
+    // Take this task's reference to the address space before we commit the slot, so a
+    // failure here leaves nothing to unwind (the caller still owns the raw `address_space`).
+    if (!retainAddressSpace(address_space)) {
+        heap.allocator().free(stack);
+        return null;
+    }
+    live_stack_bytes += stack.len; // the reaper drops this when the task dies (M8)
     t.* = .{
         .id = next_id,
         .state = .ready,
         .priority = priority,
         .stack = stack,
-        .aspace = aspace,
+        .address_space = address_space,
         .user_ip = entry,
         .user_sp = user_sp,
+        .user_arg = user_arg,
         .supervisor = supervisor,
         .exit_endpoint = exit_endpoint,
     };
@@ -363,7 +511,7 @@ fn startUserTask() void {
     // No serial chatter here: this runs on every spawn, unserialized against
     // user-space writes, and its output used to shear concurrent log lines in
     // half — the largest source of corrupted markers in the QEMU scenarios.
-    architecture.jumpToUser(t.user_ip, t.user_sp); // noreturn
+    architecture.jumpToUserArg(t.user_ip, t.user_sp, t.user_arg); // noreturn (arg0 = 0 for a process)
 }
 
 /// The unlocked task-creation primitive. Caller must hold the kernel lock (or be the
@@ -372,6 +520,7 @@ fn startUserTask() void {
 fn create(entry: *const fn () void, priority: Priority, affinity: ?u32) *Task {
     const t = freeSlot() orelse @panic("sched: task table full");
     const stack = heap.allocator().alloc(u8, stack_size) catch @panic("sched: no memory for task stack");
+    live_stack_bytes += stack.len; // the reaper drops this when the task dies (M8)
     t.* = .{ .id = next_id, .state = .ready, .priority = priority, .stack = stack, .affinity = affinity };
     next_id += 1;
     const top = @intFromPtr(stack.ptr) + stack.len;
@@ -412,7 +561,7 @@ fn schedule() void {
 /// Make `next` this core's running task: publish its kernel stack (TSS.rsp0, so a
 /// user-mode interrupt lands on a good stack) and its address space (only when
 /// it differs from what's loaded — every page-table switch is a full TLB flush),
-/// then switch registers/stacks. Kernel tasks (aspace == 0, no kstack_top used
+/// then switch registers/stacks. Kernel tasks (address_space == 0, no kstack_top used
 /// from user mode) resolve to the shared kernel page tables and skip the kernel-
 /// stack write, so this is a no-op beyond the register switch for a pure-kernel
 /// workload. The big kernel lock is held and interrupts are off throughout, so no
@@ -420,12 +569,25 @@ fn schedule() void {
 /// `save_sp` receives the outgoing task's stack pointer.
 fn switchTo(pc: *PerCpu, save_sp: *usize, next: *Task) void {
     if (next.kstack_top != 0) architecture.setKernelStack(pc.index, next.kstack_top);
-    const want = if (next.aspace != 0) next.aspace else architecture.kernelPageTable();
-    if (want != pc.loaded_aspace) {
+    const want = if (next.address_space != 0) next.address_space else architecture.kernelPageTable();
+    if (want != pc.loaded_address_space) {
         architecture.loadPageTable(want);
-        pc.loaded_aspace = want;
+        pc.loaded_address_space = want;
+    }
+    // Restore the next task's user TLS thread pointer — only on change, the same
+    // conditional-load discipline as CR3 above (docs/threading-plan.md M10).
+    if (next.thread_pointer != pc.loaded_thread_pointer) {
+        architecture.setThreadPointer(next.thread_pointer);
+        pc.loaded_thread_pointer = next.thread_pointer;
     }
     architecture.switchContext(save_sp, next.sp);
+    // Resumed now (switchContext returned into our own switchTo frame). Re-fetch the core
+    // via thisCpu(): the `pc` parameter is from *our* earlier switchTo call, so it names
+    // the core we last ran on — stale if we migrated. switchContext only swaps stacks on
+    // the current core, so thisCpu() is the core the just-dead task died on. If a task
+    // died switching to us, free its kernel stack: we're on ours so it's safe, and the big
+    // lock is still held so its slot can't have been reused (docs/threading-plan.md M8).
+    drainReapListLocked(thisCpu());
 }
 
 /// Voluntarily give up the CPU to the next ready task.
@@ -446,6 +608,98 @@ pub fn sleep(ms: u64) void {
     sync.leave(flags);
 }
 
+// --- futex: block/wake on a user address (docs/threading.md) ----------------
+//
+// A futex waiter is not linked into any queue — it is simply a `.blocked` task
+// tagged with the address it waits on (`futex_addr`). Waking scans the task table
+// (bounded) for matching waiters. A timed wait also sets `wake_at`, so the timer's
+// `wakeExpired` can wake it; `futex_addr` stays non-zero in that case, which is how
+// the waiter tells a timeout from a real wake.
+
+pub const FutexResult = enum { woken, timed_out };
+
+/// Block the current task on futex `addr` until woken, or (if `timeout_ms > 0`) the
+/// deadline. **Precondition:** the big kernel lock is held and the caller has already
+/// checked, under this same lock, that the futex word equals the expected value — so
+/// no wake can be missed. Returns with the lock still held.
+pub fn futexWaitLocked(addr: u64, timeout_ms: u64) FutexResult {
+    const t = current();
+    t.futex_addr = addr;
+    t.wake_at = if (timeout_ms > 0) architecture.millis() + timeout_ms else 0;
+    t.state = .blocked;
+    schedule(); // woken by futexWakeLocked (clears futex_addr) or wakeExpired (timeout)
+    const woken = t.futex_addr == 0;
+    t.futex_addr = 0;
+    t.wake_at = 0;
+    return if (woken) .woken else .timed_out;
+}
+
+/// Wake up to `count` tasks blocked in `futex_wait` on `addr` in address space
+/// `address_space`. Precondition: the big kernel lock is held. Returns how many woke.
+pub fn futexWakeLocked(address_space: u64, addr: u64, count: u32) u32 {
+    var woken: u32 = 0;
+    for (&tasks) |*t| {
+        if (woken >= count) break;
+        if (t.state == .blocked and t.address_space == address_space and t.futex_addr == addr) {
+            t.futex_addr = 0; // the "woken, not timed out" signal to futexWaitLocked
+            t.wake_at = 0;
+            t.state = .ready;
+            enqueue(t);
+            woken += 1;
+        }
+    }
+    return woken;
+}
+
+// --- thread join (docs/threading-plan.md M9) --------------------------------
+//
+// join needs no per-thread IPC endpoint: `thread_join(tid)` blocks the caller until the
+// task with id `tid` has exited, and the exit paths wake any joiner. The caller only ever
+// reclaims the joined thread's *user* stack (which the thread vacated the moment it entered
+// the kernel to exit), so waking at exit time — not reap time — is safe.
+
+/// True if a task with id `tid` is still live (has not exited). Caller holds the lock.
+fn aliveTid(tid: u32) bool {
+    for (&tasks) |*t| {
+        if (t.id == tid and t.state != .free and t.state != .reaping) return true;
+    }
+    return false;
+}
+
+/// Block the current task until the task with id `tid` exits (or return at once if it
+/// already has / never existed). **Precondition:** the big kernel lock is held; returns
+/// with it still held. Woken by `wakeJoinersLocked`.
+pub fn joinThreadLocked(tid: u32) void {
+    while (aliveTid(tid)) {
+        const t = current();
+        t.join_target = tid;
+        t.state = .blocked;
+        schedule(); // woken when the joined task exits; lock handed off across the switch
+        t.join_target = 0;
+    }
+}
+
+/// Set the calling task's user TLS thread pointer and load it now. Persisted on the Task so
+/// context switches restore it (docs/threading-plan.md M10). Caller holds the kernel lock.
+pub fn setThreadPointerLocked(addr: u64) void {
+    const pc = thisCpu();
+    pc.current.thread_pointer = addr;
+    architecture.setThreadPointer(addr);
+    pc.loaded_thread_pointer = addr;
+}
+
+/// Wake every task blocked in `thread_join` on `tid` — called from the exit paths once the
+/// exiting task's state is `.free`. Caller holds the lock.
+fn wakeJoinersLocked(tid: u32) void {
+    for (&tasks) |*t| {
+        if (t.state == .blocked and t.join_target == tid) {
+            t.join_target = 0;
+            t.state = .ready;
+            enqueue(t);
+        }
+    }
+}
+
 // --- event-based blocking -------------------------------------------------
 //
 // A WaitQueue is a set of tasks blocked waiting for something (a resource, a
@@ -547,7 +801,7 @@ fn removeFrom(head: *[number_priorities]?*Task, tail: *[number_priorities]?*Task
 /// Precondition: the big kernel lock is held.
 pub fn taskByIdLocked(id: u32) ?*Task {
     for (&tasks) |*t| {
-        if (t.state != .free and t.id == id) return t;
+        if (t.state != .free and t.state != .reaping and t.id == id) return t;
     }
     return null;
 }
@@ -557,7 +811,7 @@ pub fn taskByIdLocked(id: u32) ?*Task {
 /// Precondition: the big kernel lock is held.
 pub fn forgetIpcClientLocked(t: *Task) void {
     for (&tasks) |*other| {
-        if (other.state != .free and other.ipc_client == t) other.ipc_client = null;
+        if (other.state != .free and other.state != .reaping and other.ipc_client == t) other.ipc_client = null;
     }
 }
 
@@ -649,7 +903,11 @@ pub var reap_task_hook: ?*const fn (*Task) void = null;
 fn reapKillPendingLocked() void {
     const pc = thisCpu();
     const cur = pc.current;
-    if (cur.kill_pending and cur.aspace != 0 and !cur.in_system_call) {
+    // Safety net: if a dying task switched to a *fresh* task (which enters via
+    // task_trampoline, not switchTo's tail), its stack is still queued here. The dying
+    // task switched away before this tick, so it is off its stack — drain now (M8).
+    drainReapListLocked(pc);
+    if (cur.kill_pending and cur.address_space != 0 and !cur.in_system_call) {
         if (terminate_current_hook) |hook| hook(); // noreturn
     }
     if (reap_task_hook) |hook| {
@@ -690,7 +948,11 @@ pub fn setPreemption(enabled: bool) void {
 pub fn exit() noreturn {
     _ = sync.enter();
     const pc = thisCpu();
-    pc.current.state = .free;
+    // Queue this task for reaping: `.reaping` keeps its slot out of freeSlot until its
+    // stack is freed; `next` links it on the core's reap list (M8/M9).
+    pc.current.state = .reaping;
+    pc.current.next = pc.reap_list;
+    pc.reap_list = pc.current;
     const next = dequeueHighest(pc) orelse @panic("sched: no task left to run");
     next.state = .running;
     pc.current = next;
@@ -715,17 +977,21 @@ pub fn exitUser() noreturn {
 pub fn exitUserLocked() noreturn {
     const pc = thisCpu();
     const dying = pc.current;
-    const as = dying.aspace;
+    const as = dying.address_space;
     if (as != 0) {
         const kroot = architecture.kernelPageTable();
         architecture.loadPageTable(kroot); // off the process tables before freeing them
-        pc.loaded_aspace = kroot;
-        architecture.destroyAddressSpace(as);
+        pc.loaded_address_space = kroot;
+        releaseAddressSpace(as); // destroys only when this was the last task on the space
     }
-    dying.state = .free;
-    dying.aspace = 0;
+    dying.state = .reaping; // dead but its slot stays reserved until the stack is freed
+    wakeJoinersLocked(dying.id); // let any thread_join(dying.id) return (M9)
+    dying.address_space = 0;
     dying.kill_pending = false;
     dying.in_system_call = false;
+    // Queue for reaping: the task we switch to (or the next tick) frees this stack (M8/M9).
+    dying.next = pc.reap_list;
+    pc.reap_list = dying;
     const next = dequeueHighest(pc) orelse @panic("sched: no task left to run");
     next.state = .running;
     pc.current = next;
@@ -741,12 +1007,14 @@ pub fn exitUserLocked() noreturn {
 /// task isn't running). The kernel stack is leaked, as in `exitUser` (no reaper
 /// yet). Precondition: the big kernel lock is held.
 pub fn destroyTaskLocked(t: *Task) void {
-    if (t.aspace != 0) architecture.destroyAddressSpace(t.aspace);
-    t.aspace = 0;
+    if (t.address_space != 0) releaseAddressSpace(t.address_space); // destroys only on the last reference
+    reapStackLocked(t); // safe to free now: `t` is not running on any core (M8)
+    t.address_space = 0;
     t.kill_pending = false;
     t.in_system_call = false;
     t.wake_at = 0;
     t.state = .free;
+    wakeJoinersLocked(t.id); // a killed thread's joiners must return too (M9)
 }
 
 /// Snapshot the task table into `out` (up to its length), returning the total
@@ -760,7 +1028,7 @@ pub fn enumerate(out: []abi.ProcessDescriptor) u64 {
     defer sync.leave(flags);
     var total: u64 = 0;
     for (&tasks) |*t| {
-        if (t.state == .free) continue;
+        if (t.state == .free or t.state == .reaping) continue; // reaping = already exited
         if (total < out.len) {
             const d = &out[total];
             d.* = .{
@@ -770,7 +1038,7 @@ pub fn enumerate(out: []abi.ProcessDescriptor) u64 {
                     .ready => .ready,
                     .running => .running,
                     .blocked => .blocked,
-                    .free => unreachable,
+                    .free, .reaping => unreachable,
                 })),
                 .priority = t.priority,
                 .name_length = t.name_length,
@@ -784,7 +1052,7 @@ pub fn enumerate(out: []abi.ProcessDescriptor) u64 {
 
 /// Whether the running task is a user process (has its own address space).
 pub fn currentIsUserProcess() bool {
-    return current().aspace != 0;
+    return current().address_space != 0;
 }
 
 pub fn currentId() u32 {

system/kernel/tests.zig

@@ -139,6 +139,26 @@ pub fn run(case: []const u8, boot_information: *const BootInformation) void {
         userPfTest();
     } else if (eql(case, "fault-recovery")) {
         faultRecoveryTest(boot_information);
+    } else if (eql(case, "address-space-refcount")) {
+        addressSpaceRefcountTest(boot_information);
+    } else if (eql(case, "thread-spawn")) {
+        threadSpawnTest(boot_information);
+    } else if (eql(case, "thread-join")) {
+        threadJoinTest(boot_information);
+    } else if (eql(case, "thread-futex")) {
+        threadFutexTest(boot_information);
+    } else if (eql(case, "thread-mutex")) {
+        threadMutexTest(boot_information);
+    } else if (eql(case, "thread-id")) {
+        threadIdTest(boot_information);
+    } else if (eql(case, "thread-alloc")) {
+        threadAllocTest(boot_information);
+    } else if (eql(case, "task-reap")) {
+        taskReapTest(boot_information);
+    } else if (eql(case, "thread-tls")) {
+        threadTlsTest(boot_information);
+    } else if (eql(case, "thread-rwlock")) {
+        threadRwlockTest(boot_information);
     } else if (eql(case, "args")) {
         argsTest(boot_information);
     } else if (eql(case, "init")) {
@@ -767,11 +787,15 @@ fn affinityTest() void {
         return;
     }
 
-    var spins: u64 = 0;
-    while (spins < 3_000_000_000) spins +%= 1; // many time slices across the cores
+    // Let many time slices pass so the scheduler runs the pinned worker across ticks.
+    // Wait on the wall clock, not a raw iteration count: a fixed-count busy-loop's
+    // wall-time is a codegen lottery (the optimiser may elide or vectorise it), so an
+    // unrelated change elsewhere in this file could swing this test from ~4 s to ~50 s.
+    const run_until = architecture.millis() + 400;
+    while (architecture.millis() < run_until) {}
     affinity_running = false;
-    var settle: u64 = 0;
-    while (settle < 200_000_000) settle +%= 1; // let the worker see the flag and exit
+    const settle_until = architecture.millis() + 50;
+    while (architecture.millis() < settle_until) {} // let the worker see the flag and exit
 
     var others: u32 = 0;
     for (affinity_cores, 0..) |seen, c| {
@@ -896,12 +920,12 @@ fn userMemTest() void {
     log("DANOS-TEST-BEGIN: usermem\n", .{});
     const base_free = pmm.stats().free_frames;
 
-    const aspace = architecture.createAddressSpace() orelse {
+    const address_space = architecture.createAddressSpace() orelse {
         check("created a fresh address space", false);
         result();
         return;
     };
-    check("created a fresh address space", aspace != 0);
+    check("created a fresh address space", address_space != 0);
 
     // Grant three pages into the arena, mapped RW + NX (the mmap contract).
     const npages = 3;
@@ -910,7 +934,7 @@ fn userMemTest() void {
     var mapped: usize = 0;
     while (mapped < npages) : (mapped += 1) {
         frames[mapped] = pmm.alloc() orelse break;
-        architecture.mapUserPageInto(aspace, arena + mapped * abi.page_size, frames[mapped], true, false);
+        architecture.mapUserPageInto(address_space, arena + mapped * abi.page_size, frames[mapped], true, false);
     }
     check("granted three user pages", mapped == npages);
 
@@ -919,7 +943,7 @@ fn userMemTest() void {
     var rw_ok = true;
     for (0..npages) |i| {
         const va = arena + i * abi.page_size;
-        const physical = architecture.translate(aspace, va) orelse {
+        const physical = architecture.translate(address_space, va) orelse {
             translate_ok = false;
             continue;
         };
@@ -934,13 +958,13 @@ fn userMemTest() void {
     // Release them the way munmap does, then tear down the address space.
     for (0..npages) |i| {
         const va = arena + i * abi.page_size;
-        if (architecture.translate(aspace, va)) |physical| {
-            architecture.unmapUserPageInto(aspace, va);
+        if (architecture.translate(address_space, va)) |physical| {
+            architecture.unmapUserPageInto(address_space, va);
             pmm.free(physical);
         }
     }
-    check("munmap unmapped every grant", architecture.translate(aspace, arena) == null);
-    architecture.destroyAddressSpace(aspace);
+    check("munmap unmapped every grant", architecture.translate(address_space, arena) == null);
+    architecture.destroyAddressSpace(address_space);
 
     check("no frames leaked (free count restored)", pmm.stats().free_frames == base_free);
     result();
@@ -1108,12 +1132,12 @@ fn dmaTest() void {
 
     // Map the run into a fresh address space as coherent DMA and translate each page
     // back: the same physical run, in order — proving contiguity and the mapping.
-    const aspace = architecture.createAddressSpace().?;
-    architecture.mapUserDmaInto(aspace, process.dma_arena_base, phys, frames * abi.page_size);
+    const address_space = architecture.createAddressSpace().?;
+    architecture.mapUserDmaInto(address_space, process.dma_arena_base, phys, frames * abi.page_size);
     var mapped_ok = true;
     for (0..frames) |i| {
         const va = process.dma_arena_base + i * abi.page_size;
-        const got = architecture.translate(aspace, va) orelse {
+        const got = architecture.translate(address_space, va) orelse {
             mapped_ok = false;
             break;
         };
@@ -1123,7 +1147,7 @@ fn dmaTest() void {
 
     // Teardown must reclaim the DMA RAM (the leaves carry no device_grant, so
     // freeSubtree frees them as ordinary frames) — a driver that just dies leaks none.
-    architecture.destroyAddressSpace(aspace);
+    architecture.destroyAddressSpace(address_space);
     for (0..2) |i| pmm.free(low + i * abi.page_size);
     check("no frames leaked after DMA teardown", pmm.stats().free_frames == base_free);
     result();
@@ -1355,9 +1379,9 @@ fn spawnFaultingProcess() ?u32 {
     const flags = sync.enter();
     defer sync.leave(flags);
 
-    const aspace = architecture.createAddressSpace() orelse return null;
+    const address_space = architecture.createAddressSpace() orelse return null;
     const code_frame = pmm.alloc() orelse {
-        architecture.destroyAddressSpace(aspace);
+        architecture.destroyAddressSpace(address_space);
         return null;
     };
     // Fill through the physmap (the user mapping is read-only); pad with int3 so a
@@ -1365,17 +1389,17 @@ fn spawnFaultingProcess() ?u32 {
     const code: [*]u8 = @ptrFromInt(boot_handoff.physicalToVirtual(code_frame));
     @memset(code[0..abi.page_size], 0xCC);
     @memcpy(code[0..blob.len], blob);
-    architecture.mapUserPageInto(aspace, process.code_virtual, code_frame, false, true); // RO + X
+    architecture.mapUserPageInto(address_space, process.code_virtual, code_frame, false, true); // RO + X
 
     const stack_frame = pmm.alloc() orelse {
-        architecture.destroyAddressSpace(aspace); // frees code_frame too — it's mapped
+        architecture.destroyAddressSpace(address_space); // frees code_frame too — it's mapped
         return null;
     };
-    architecture.mapUserPageInto(aspace, process.stack_base_virtual, stack_frame, true, false); // RW + NX
+    architecture.mapUserPageInto(address_space, process.stack_base_virtual, stack_frame, true, false); // RW + NX
 
     // Supervised by the calling test task, so exitReasonOf can read the verdict.
-    const id = scheduler.spawnUserLocked(aspace, process.code_virtual, process.stack_base_virtual + abi.page_size, 4, "fault-probe", scheduler.currentId(), null) orelse {
-        architecture.destroyAddressSpace(aspace);
+    const id = scheduler.spawnUserLocked(address_space, process.code_virtual, process.stack_base_virtual + abi.page_size, 0, 4, "fault-probe", scheduler.currentId(), null) orelse {
+        architecture.destroyAddressSpace(address_space);
         return null;
     };
     return id;
@@ -1429,6 +1453,420 @@ fn faultRecoveryTest(boot_information: *const BootInformation) void {
     result();
 }
 
+/// Address-space refcount (docs/threading-plan.md M1): every process holds exactly one
+/// reference to its address space, released when it dies, so `destroyAddressSpace` runs
+/// exactly once per space — no leak, no double-free. Spawn and kill several ring-3
+/// processes (the faulting probe, reaped by the kernel) and confirm the count of live
+/// address spaces returns to baseline while destructions advance by exactly that many.
+/// This is the foundation threads (shared address spaces) build on: the refactor must be
+/// invisible while every space still has exactly one task.
+fn addressSpaceRefcountTest(boot_information: *const BootInformation) void {
+    _ = boot_information;
+    log("DANOS-TEST-BEGIN: address-space-refcount\n", .{});
+    const base_live = scheduler.liveAddressSpaceCount();
+    const base_destroyed = scheduler.addressSpaceDestroyCount();
+    const rounds: u32 = 5;
+    var killed: u32 = 0;
+    var round: u32 = 0;
+    while (round < rounds) : (round += 1) {
+        process.fault_kill_count = 0;
+        const probe = spawnFaultingProcess() orelse break;
+        _ = probe;
+        // Let the probe fault on its first instruction and be reaped.
+        scheduler.setPriority(1);
+        const deadline = architecture.millis() + 5000;
+        while (process.fault_kill_count < 1 and architecture.millis() < deadline) scheduler.yield();
+        scheduler.setPriority(4);
+        if (process.fault_kill_count >= 1) killed += 1;
+    }
+    check("all probes spawned and were killed", killed == rounds);
+    check("live address-space count returned to baseline", scheduler.liveAddressSpaceCount() == base_live);
+    check("each address space destroyed exactly once", scheduler.addressSpaceDestroyCount() == base_destroyed + rounds);
+    if (killed == rounds and scheduler.liveAddressSpaceCount() == base_live and
+        scheduler.addressSpaceDestroyCount() == base_destroyed + rounds)
+        log("address-space-refcount: spaces released to baseline ok\n", .{});
+    result();
+}
+
+/// Thread spawn (docs/threading-plan.md M2): the `thread-test` service spawns a worker
+/// thread that writes a shared global; the main thread, polling that memory, observes the
+/// write — proving `runtime.Thread.spawn` started a task in the **same** address space
+/// (a separate process could not touch it). The service's own marker is the verdict.
+fn threadSpawnTest(boot_information: *const BootInformation) void {
+    log("DANOS-TEST-BEGIN: thread-spawn\n", .{});
+    if (boot_information.initial_ramdisk_len == 0) {
+        check("bootloader handed over an initial_ramdisk", false);
+        result();
+        return;
+    }
+    const image = @as([*]const u8, @ptrFromInt(boot_handoff.physicalToVirtual(boot_information.initial_ramdisk_base)))[0..boot_information.initial_ramdisk_len];
+    const rd = initial_ramdisk.Reader.init(image) orelse {
+        check("initial_ramdisk image is valid", false);
+        result();
+        return;
+    };
+
+    check("thread-test spawned", spawnNamed(rd, "thread-test"));
+
+    // Wait for the service's verdict marker (it polls shared memory the worker wrote).
+    const ok_marker = "thread-test: child ran in shared address space ok";
+    const fail_marker = "thread-test: FAIL";
+    scheduler.setPriority(1);
+    const deadline = architecture.millis() + 12000;
+    while (architecture.millis() < deadline) {
+        if (bufferHas(ok_marker) or bufferHas(fail_marker)) break;
+        scheduler.yield();
+    }
+    scheduler.setPriority(4);
+
+    check("a worker thread ran in the shared address space (shared write observed)", bufferHas(ok_marker));
+    check("the thread path reported no failure", !bufferHas(fail_marker));
+    result();
+}
+
+/// Thread join + parallelism (docs/threading-plan.md M3): `thread-test` in join mode
+/// spawns N workers that each do K atomic increments on a shared counter and stamp the
+/// core they ran on; it `join`s all N and asserts the total is exactly N*K (every worker
+/// ran, join waited for each) and that >1 core was used (genuine parallelism), then a
+/// detached worker proves `detach`. Its single verdict marker is the case result.
+fn threadJoinTest(boot_information: *const BootInformation) void {
+    log("DANOS-TEST-BEGIN: thread-join\n", .{});
+    if (boot_information.initial_ramdisk_len == 0) {
+        check("bootloader handed over an initial_ramdisk", false);
+        result();
+        return;
+    }
+    const image = @as([*]const u8, @ptrFromInt(boot_handoff.physicalToVirtual(boot_information.initial_ramdisk_base)))[0..boot_information.initial_ramdisk_len];
+    const rd = initial_ramdisk.Reader.init(image) orelse {
+        check("initial_ramdisk image is valid", false);
+        result();
+        return;
+    };
+
+    // Spawn thread-test in join mode (argv selects the mode).
+    var started = false;
+    var i: u32 = 0;
+    while (i < rd.count) : (i += 1) {
+        const item = rd.entry(i) orelse continue;
+        if (!eql(item.name, "thread-test")) continue;
+        started = if (process.spawnProcess(item.blob, 4, &.{ "thread-test", "join" })) true else |_| false;
+        break;
+    }
+    check("thread-test (join mode) spawned", started);
+
+    const ok_marker = "thread-test: join ok";
+    const fail_marker = "thread-test: FAIL";
+    scheduler.setPriority(1);
+    const deadline = architecture.millis() + 15000;
+    while (architecture.millis() < deadline) {
+        if (bufferHas(ok_marker) or bufferHas(fail_marker)) break;
+        scheduler.yield();
+    }
+    scheduler.setPriority(4);
+
+    check("N worker threads joined; counter exact (N*K) and >1 core used", bufferHas(ok_marker));
+    check("no thread failure reported", !bufferHas(fail_marker));
+    result();
+}
+
+/// Futex (docs/threading-plan.md M4): `thread-test` in futex mode has a waiter thread
+/// block in `futex_wait` on a word; the main thread publishes the word and `futex_wake`s
+/// it. The serial order `waiting → waking → woke` shows the kernel handoff (the waiter
+/// parked and was woken, not spun), and a `timedWait` on an unwoken word reports a
+/// timeout. The verdict marker is emitted only after both hold.
+fn threadFutexTest(boot_information: *const BootInformation) void {
+    log("DANOS-TEST-BEGIN: thread-futex\n", .{});
+    if (boot_information.initial_ramdisk_len == 0) {
+        check("bootloader handed over an initial_ramdisk", false);
+        result();
+        return;
+    }
+    const image = @as([*]const u8, @ptrFromInt(boot_handoff.physicalToVirtual(boot_information.initial_ramdisk_base)))[0..boot_information.initial_ramdisk_len];
+    const rd = initial_ramdisk.Reader.init(image) orelse {
+        check("initial_ramdisk image is valid", false);
+        result();
+        return;
+    };
+
+    var started = false;
+    var i: u32 = 0;
+    while (i < rd.count) : (i += 1) {
+        const item = rd.entry(i) orelse continue;
+        if (!eql(item.name, "thread-test")) continue;
+        started = if (process.spawnProcess(item.blob, 4, &.{ "thread-test", "futex" })) true else |_| false;
+        break;
+    }
+    check("thread-test (futex mode) spawned", started);
+
+    const ok_marker = "thread-futex: ok";
+    const fail_marker = "thread-futex: FAIL";
+    scheduler.setPriority(1);
+    const deadline = architecture.millis() + 15000;
+    while (architecture.millis() < deadline) {
+        if (bufferHas(ok_marker) or bufferHas(fail_marker)) break;
+        scheduler.yield();
+    }
+    scheduler.setPriority(4);
+
+    // Only the freshest marker is checked here — the kernel's log ring buffer may have
+    // evicted the earlier ones by now. The waiting/waking/woke ordering (the handoff
+    // proof) is asserted against the full serial stream by the qemu case's regex; the
+    // verdict marker is emitted by thread-test only after the wake AND the timeout hold.
+    check("futex handoff + timeout completed (verdict reached, no failure)", bufferHas(ok_marker) and !bufferHas(fail_marker));
+    result();
+}
+
+/// Mutex + Condition (docs/threading-plan.md M5): `thread-test` in mutex mode runs a
+/// bounded producer/consumer — P producers and C consumers over one `Mutex` and two
+/// `Condition`s move N unique items through a small ring. Every item is produced once;
+/// if the lock and condition variables are correct under real cross-core contention,
+/// the consumed checksum and tally match exactly (no lost or duplicated item, no
+/// overrun). The verdict marker is emitted only when both match.
+fn threadMutexTest(boot_information: *const BootInformation) void {
+    log("DANOS-TEST-BEGIN: thread-mutex\n", .{});
+    if (boot_information.initial_ramdisk_len == 0) {
+        check("bootloader handed over an initial_ramdisk", false);
+        result();
+        return;
+    }
+    const image = @as([*]const u8, @ptrFromInt(boot_handoff.physicalToVirtual(boot_information.initial_ramdisk_base)))[0..boot_information.initial_ramdisk_len];
+    const rd = initial_ramdisk.Reader.init(image) orelse {
+        check("initial_ramdisk image is valid", false);
+        result();
+        return;
+    };
+
+    var started = false;
+    var i: u32 = 0;
+    while (i < rd.count) : (i += 1) {
+        const item = rd.entry(i) orelse continue;
+        if (!eql(item.name, "thread-test")) continue;
+        started = if (process.spawnProcess(item.blob, 4, &.{ "thread-test", "mutex" })) true else |_| false;
+        break;
+    }
+    check("thread-test (mutex mode) spawned", started);
+
+    const ok_marker = "thread-mutex: ok";
+    const fail_marker = "thread-mutex: FAIL";
+    scheduler.setPriority(1);
+    const deadline = architecture.millis() + 20000;
+    while (architecture.millis() < deadline) {
+        if (bufferHas(ok_marker) or bufferHas(fail_marker)) break;
+        scheduler.yield();
+    }
+    scheduler.setPriority(4);
+
+    check("producer/consumer over Mutex+Condition moved every item exactly once", bufferHas(ok_marker) and !bufferHas(fail_marker));
+    result();
+}
+
+/// Thread identity (docs/threading-plan.md M6): `thread-test` in id mode spawns two
+/// workers that each read `runtime.Thread.getCurrentId`; the main thread confirms all
+/// three ids are non-zero and distinct — proof each thread has its own kernel identity.
+fn threadIdTest(boot_information: *const BootInformation) void {
+    log("DANOS-TEST-BEGIN: thread-id\n", .{});
+    if (boot_information.initial_ramdisk_len == 0) {
+        check("bootloader handed over an initial_ramdisk", false);
+        result();
+        return;
+    }
+    const image = @as([*]const u8, @ptrFromInt(boot_handoff.physicalToVirtual(boot_information.initial_ramdisk_base)))[0..boot_information.initial_ramdisk_len];
+    const rd = initial_ramdisk.Reader.init(image) orelse {
+        check("initial_ramdisk image is valid", false);
+        result();
+        return;
+    };
+
+    var started = false;
+    var i: u32 = 0;
+    while (i < rd.count) : (i += 1) {
+        const item = rd.entry(i) orelse continue;
+        if (!eql(item.name, "thread-test")) continue;
+        started = if (process.spawnProcess(item.blob, 4, &.{ "thread-test", "id" })) true else |_| false;
+        break;
+    }
+    check("thread-test (id mode) spawned", started);
+
+    const ok_marker = "thread-id: ok";
+    const fail_marker = "thread-id: FAIL";
+    scheduler.setPriority(1);
+    const deadline = architecture.millis() + 12000;
+    while (architecture.millis() < deadline) {
+        if (bufferHas(ok_marker) or bufferHas(fail_marker)) break;
+        scheduler.yield();
+    }
+    scheduler.setPriority(4);
+
+    check("each thread has a distinct, non-zero getCurrentId", bufferHas(ok_marker) and !bufferHas(fail_marker));
+    result();
+}
+
+/// Thread-safe allocation (docs/threading-plan.md M7): `thread-test` in alloc mode runs N
+/// threads that each do many `alloc`/fill/verify/`free` cycles of varied sizes on the
+/// shared runtime heap. If the heap lock or the per-address-space mmap arena were unsafe,
+/// two threads' blocks would overlap and a thread would read another's pattern; the
+/// verdict marker is emitted only when every thread completes with every block intact.
+fn threadAllocTest(boot_information: *const BootInformation) void {
+    log("DANOS-TEST-BEGIN: thread-alloc\n", .{});
+    if (boot_information.initial_ramdisk_len == 0) {
+        check("bootloader handed over an initial_ramdisk", false);
+        result();
+        return;
+    }
+    const image = @as([*]const u8, @ptrFromInt(boot_handoff.physicalToVirtual(boot_information.initial_ramdisk_base)))[0..boot_information.initial_ramdisk_len];
+    const rd = initial_ramdisk.Reader.init(image) orelse {
+        check("initial_ramdisk image is valid", false);
+        result();
+        return;
+    };
+
+    var started = false;
+    var i: u32 = 0;
+    while (i < rd.count) : (i += 1) {
+        const item = rd.entry(i) orelse continue;
+        if (!eql(item.name, "thread-test")) continue;
+        started = if (process.spawnProcess(item.blob, 4, &.{ "thread-test", "alloc" })) true else |_| false;
+        break;
+    }
+    check("thread-test (alloc mode) spawned", started);
+
+    const ok_marker = "thread-alloc: ok";
+    const fail_marker = "thread-alloc: FAIL";
+    scheduler.setPriority(1);
+    const deadline = architecture.millis() + 20000;
+    while (architecture.millis() < deadline) {
+        if (bufferHas(ok_marker) or bufferHas(fail_marker)) break;
+        scheduler.yield();
+    }
+    scheduler.setPriority(4);
+
+    check("concurrent heap allocation stayed corruption-free (shared heap + per-address-space arena)", bufferHas(ok_marker) and !bufferHas(fail_marker));
+    result();
+}
+
+/// Per-thread TLS / FS base (docs/threading-plan.md M10): `thread-test` in tls mode has two
+/// threads each set their own FS base and write a unique marker to `%fs:8`, then — after
+/// both have written — read it back. If the FS base were not per-thread and restored across
+/// context switches, the second write would clobber the first and a thread would read the
+/// wrong marker. The verdict marker means both read their own value (no cross-talk).
+fn threadTlsTest(boot_information: *const BootInformation) void {
+    log("DANOS-TEST-BEGIN: thread-tls\n", .{});
+    if (boot_information.initial_ramdisk_len == 0) {
+        check("bootloader handed over an initial_ramdisk", false);
+        result();
+        return;
+    }
+    const image = @as([*]const u8, @ptrFromInt(boot_handoff.physicalToVirtual(boot_information.initial_ramdisk_base)))[0..boot_information.initial_ramdisk_len];
+    const rd = initial_ramdisk.Reader.init(image) orelse {
+        check("initial_ramdisk image is valid", false);
+        result();
+        return;
+    };
+
+    var started = false;
+    var i: u32 = 0;
+    while (i < rd.count) : (i += 1) {
+        const item = rd.entry(i) orelse continue;
+        if (!eql(item.name, "thread-test")) continue;
+        started = if (process.spawnProcess(item.blob, 4, &.{ "thread-test", "tls" })) true else |_| false;
+        break;
+    }
+    check("thread-test (tls mode) spawned", started);
+
+    const ok_marker = "thread-tls: ok";
+    const fail_marker = "thread-tls: FAIL";
+    scheduler.setPriority(1);
+    const deadline = architecture.millis() + 12000;
+    while (architecture.millis() < deadline) {
+        if (bufferHas(ok_marker) or bufferHas(fail_marker)) break;
+        scheduler.yield();
+    }
+    scheduler.setPriority(4);
+
+    check("each thread has its own FS-base TLS slot (no cross-talk across switches)", bufferHas(ok_marker) and !bufferHas(fail_marker));
+    result();
+}
+
+/// RwLock (docs/threading-plan.md M11): `thread-test` in rwlock mode runs writers that set
+/// two halves of a value under the exclusive lock and readers that check the halves match
+/// under the shared lock. If the reader/writer lock were wrong, a reader would observe a
+/// half-written value; zero violations across many reads → the lock holds.
+fn threadRwlockTest(boot_information: *const BootInformation) void {
+    log("DANOS-TEST-BEGIN: thread-rwlock\n", .{});
+    if (boot_information.initial_ramdisk_len == 0) {
+        check("bootloader handed over an initial_ramdisk", false);
+        result();
+        return;
+    }
+    const image = @as([*]const u8, @ptrFromInt(boot_handoff.physicalToVirtual(boot_information.initial_ramdisk_base)))[0..boot_information.initial_ramdisk_len];
+    const rd = initial_ramdisk.Reader.init(image) orelse {
+        check("initial_ramdisk image is valid", false);
+        result();
+        return;
+    };
+
+    var started = false;
+    var i: u32 = 0;
+    while (i < rd.count) : (i += 1) {
+        const item = rd.entry(i) orelse continue;
+        if (!eql(item.name, "thread-test")) continue;
+        started = if (process.spawnProcess(item.blob, 4, &.{ "thread-test", "rwlock" })) true else |_| false;
+        break;
+    }
+    check("thread-test (rwlock mode) spawned", started);
+
+    const ok_marker = "thread-rwlock: ok";
+    const fail_marker = "thread-rwlock: FAIL";
+    scheduler.setPriority(1);
+    const deadline = architecture.millis() + 20000;
+    while (architecture.millis() < deadline) {
+        if (bufferHas(ok_marker) or bufferHas(fail_marker)) break;
+        scheduler.yield();
+    }
+    scheduler.setPriority(4);
+
+    check("readers/writers over an RwLock never observed a half-written value", bufferHas(ok_marker) and !bufferHas(fail_marker));
+    result();
+}
+
+/// The task reaper (docs/threading-plan.md M8): a dead task's kernel stack used to be
+/// leaked ("no reaper yet"). Spawn and kill many ring-3 processes and confirm the total
+/// kernel-stack bytes return to baseline — every stack reclaimed, no leak. (Threads exit
+/// through the same exitUserLocked path, so this covers them too.)
+fn taskReapTest(boot_information: *const BootInformation) void {
+    _ = boot_information;
+    log("DANOS-TEST-BEGIN: task-reap\n", .{});
+    const base = scheduler.liveStackBytes();
+    const rounds: u32 = 12;
+    var killed: u32 = 0;
+    var round: u32 = 0;
+    while (round < rounds) : (round += 1) {
+        process.fault_kill_count = 0;
+        const probe = spawnFaultingProcess() orelse break;
+        _ = probe;
+        scheduler.setPriority(1);
+        const deadline = architecture.millis() + 5000;
+        while (process.fault_kill_count < 1 and architecture.millis() < deadline) scheduler.yield();
+        scheduler.setPriority(4);
+        if (process.fault_kill_count >= 1) killed += 1;
+    }
+    // Reaping is asynchronous — a dead task's stack is freed when its core next switches
+    // or ticks. Poll (bounded) until the live bytes return to baseline: a correct reaper
+    // gets there in a few ms; a genuine leak never does and this times out.
+    scheduler.setPriority(1);
+    const settle_deadline = architecture.millis() + 3000;
+    while (scheduler.liveStackBytes() != base and architecture.millis() < settle_deadline) scheduler.yield();
+    scheduler.setPriority(4);
+
+    const final = scheduler.liveStackBytes();
+    log("task-reap: base={d} final={d} killed={d}/{d}\n", .{ base, final, killed, rounds });
+    check("all probes spawned and were killed", killed == rounds);
+    check("kernel stacks reclaimed to baseline (no leak)", final == base);
+    if (killed == rounds and final == base)
+        log("task-reap: kernel stacks reclaimed to baseline ok\n", .{});
+    result();
+}
+
 /// The full PID-1 path: the bootloader read /system/services/init off the boot volume and
 /// handed it over; load it as a user ELF and spawn it as a real ring-3 process
 /// — the same call the normal boot path makes — then confirm it beats. init
@@ -2851,20 +3289,20 @@ fn ioPassTest() void {
     log("DANOS-TEST-BEGIN: iopass\n", .{});
     const base_free = pmm.stats().free_frames;
 
-    const aspace = architecture.createAddressSpace() orelse {
+    const address_space = architecture.createAddressSpace() orelse {
         check("created a fresh address space", false);
         result();
         return;
     };
     const frame = pmm.alloc() orelse {
-        architecture.destroyAddressSpace(aspace);
+        architecture.destroyAddressSpace(address_space);
         check("allocated a frame to grant", false);
         result();
         return;
     };
     // Map it the way mmio_map does (device grant, strong-uncacheable), then tear the space down.
-    architecture.mapUserDeviceInto(aspace, process.device_arena_base, frame, abi.page_size, false);
-    architecture.destroyAddressSpace(aspace);
+    architecture.mapUserDeviceInto(address_space, process.device_arena_base, frame, abi.page_size, false);
+    architecture.destroyAddressSpace(address_space);
 
     // The page tables were reclaimed; the device-granted frame must not have been.
     check("device-granted frame survived teardown (not reclaimed as RAM)", pmm.stats().free_frames == base_free - 1);
@@ -2916,26 +3354,26 @@ fn displayTest(boot_information: *const BootInformation) void {
     // space, and confirm the leaf's cache type. We never run this space (no CR3 load) —
     // we only read back the page-table entries — so aliasing the same physical page at
     // two cache types below is inert.
-    const aspace = architecture.createAddressSpace() orelse {
+    const address_space = architecture.createAddressSpace() orelse {
         check("created a fresh address space", false);
         result();
         return;
     };
-    defer architecture.destroyAddressSpace(aspace);
+    defer architecture.destroyAddressSpace(address_space);
 
     const page_base = fb.base & ~@as(u64, abi.page_size - 1);
-    architecture.mapUserDeviceInto(aspace, process.device_arena_base, page_base, abi.page_size, true);
+    architecture.mapUserDeviceInto(address_space, process.device_arena_base, page_base, abi.page_size, true);
     check(
         "the framebuffer maps write-combining (PAT entry 4: PAT bit set, PCD/PWT clear)",
-        architecture.userLeafIsWriteCombining(aspace, process.device_arena_base) == true,
+        architecture.userLeafIsWriteCombining(address_space, process.device_arena_base) == true,
     );
 
     // Regression guard: the strong-uncacheable default is still that, so WC is a real
     // choice the flag makes, not the only behaviour.
-    architecture.mapUserDeviceInto(aspace, process.device_arena_base + abi.page_size, page_base, abi.page_size, false);
+    architecture.mapUserDeviceInto(address_space, process.device_arena_base + abi.page_size, page_base, abi.page_size, false);
     check(
         "a register window still maps strong-uncacheable",
-        architecture.userLeafIsWriteCombining(aspace, process.device_arena_base + abi.page_size) == false,
+        architecture.userLeafIsWriteCombining(address_space, process.device_arena_base + abi.page_size) == false,
     );
 
     log("display: mapped {d}x{d} pitch {d} (write-combining)\n", .{ fb.width, fb.height, fb.pitch });

system/services/init/init.zig

@@ -20,6 +20,7 @@
 const std = @import("std");
 const runtime = @import("runtime");
 const power = runtime.power_protocol;
+const build_options = @import("build_options");
 
 /// Where the kernel boot log is persisted on the USB FAT volume — an 8.3 name at
 /// the mount root (see system/services/log-flush). init writes it at shutdown;
@@ -90,10 +91,13 @@ pub fn main() void {
     // triggers the same shutdown path.
     subscribePower();
 
-    // A re-arming timer drives the liveness heartbeat: proof PID 1 is alive
-    // (the init test's marker) while the loop stays free to receive signals,
-    // power events, and children's exit notifications.
-    _ = runtime.system.timerOnce(supervision_endpoint, 1000);
+    // A re-arming timer drives the liveness heartbeat — proof PID 1 is alive (the
+    // init test's marker) and a -Dserial diagnostic. It is a serial/test-build-only
+    // concern: a flashable (serial-off) image runs a purely event-driven PID 1 that
+    // wakes only for real work (signals, power events, children's exits), never for a
+    // periodic beat. `build_options.serial` is comptime, so the heartbeat — its timer
+    // and the handler below — folds away entirely when serial is off.
+    if (build_options.serial) _ = runtime.system.timerOnce(supervision_endpoint, 1000);
 
     var receive: [power.message_maximum]u8 = undefined;
     while (true) {
@@ -102,7 +106,7 @@ pub fn main() void {
             if (signals.has(.terminate)) shutDown();
             continue;
         }
-        if (got.isTimer()) {
+        if (build_options.serial and got.isTimer()) {
             _ = runtime.system.write("/system/services/init: heartbeat\n");
             _ = runtime.system.timerOnce(supervision_endpoint, 1000);
             continue;

system/services/thread-test/thread-test.zig

@@ -0,0 +1,491 @@
+//! thread-test — danos's multi-threaded exerciser (docs/threading-plan.md M2, M3).
+//!
+//! Two modes, chosen by argv[1] (default "spawn"):
+//!   spawn — M2: one worker writes a shared global; the main thread observes it, proving
+//!           `runtime.Thread.spawn` started a task in the **same** address space.
+//!   join  — M3: N workers each do K atomic increments on a shared counter and stamp the
+//!           core they ran on; the main thread `join`s all N and checks the total is
+//!           exactly N*K (every worker ran, join waited) and that >1 core was used
+//!           (genuine parallelism). Then a detached worker proves `detach` runs and
+//!           needs no join.
+//!
+//! Built multi-threaded (`addThreadedUserBinary`) so atomics/shared reads are real.
+
+const std = @import("std");
+const runtime = @import("runtime");
+
+fn write(comptime s: []const u8) void {
+    _ = runtime.system.write(s);
+}
+
+// --- M2: spawn mode ---------------------------------------------------------
+
+var shared_value: u32 = 0;
+var spawn_done = std.atomic.Value(u32).init(0);
+const sentinel: u32 = 0xA5A5;
+
+fn spawnWorker() void {
+    shared_value = sentinel;
+    spawn_done.store(1, .release);
+}
+
+fn runSpawnMode() void {
+    write("thread-test: starting\n");
+    _ = runtime.Thread.spawn(.{}, spawnWorker, .{}) catch {
+        write("thread-test: FAIL spawn refused\n");
+        return;
+    };
+    var spins: usize = 0;
+    while (spawn_done.load(.acquire) == 0 and spins < 50_000_000) : (spins += 1) {
+        runtime.system.yield();
+    }
+    if (spawn_done.load(.acquire) == 1 and shared_value == sentinel) {
+        write("thread-test: child ran in shared address space ok\n");
+    } else {
+        write("thread-test: FAIL worker did not update shared memory\n");
+    }
+}
+
+// --- M3: join mode ----------------------------------------------------------
+
+const worker_count: u32 = 4;
+const iterations: u64 = 100_000;
+
+var counter = std.atomic.Value(u64).init(0);
+var cores_seen = std.atomic.Value(u32).init(0);
+
+fn joinWorker() void {
+    var i: u64 = 0;
+    while (i < iterations) : (i += 1) {
+        _ = counter.fetchAdd(1, .monotonic);
+        if (i % 1000 == 0) stampCore(); // periodic: catches cross-core migration too
+    }
+    stampCore();
+}
+
+fn stampCore() void {
+    const core = runtime.Thread.currentCore();
+    if (core < 32) _ = cores_seen.fetchOr(@as(u32, 1) << @intCast(core), .monotonic);
+}
+
+var detach_done = std.atomic.Value(u32).init(0);
+
+fn detachWorker() void {
+    detach_done.store(1, .release);
+}
+
+fn noopWorker() void {}
+
+fn runJoinMode() void {
+    write("thread-test: join mode starting\n");
+
+    var threads: [worker_count]runtime.Thread = undefined;
+    var spawned: u32 = 0;
+    while (spawned < worker_count) : (spawned += 1) {
+        threads[spawned] = runtime.Thread.spawn(.{}, joinWorker, .{}) catch break;
+    }
+    if (spawned != worker_count) {
+        write("thread-test: FAIL could not spawn all workers\n");
+        return;
+    }
+    for (threads[0..spawned]) |t| t.join();
+
+    const total = counter.load(.acquire);
+    const cores = @popCount(cores_seen.load(.acquire));
+    if (total != worker_count * iterations) {
+        write("thread-test: FAIL counter mismatch (a worker was lost or join did not wait)\n");
+        return;
+    }
+    if (cores <= 1) {
+        write("thread-test: FAIL workers never ran on more than one core\n");
+        return;
+    }
+
+    // detach: the worker runs and we never join it.
+    const dt = runtime.Thread.spawn(.{}, detachWorker, .{}) catch {
+        write("thread-test: FAIL detach spawn refused\n");
+        return;
+    };
+    dt.detach();
+    var spins: usize = 0;
+    while (detach_done.load(.acquire) == 0 and spins < 50_000_000) : (spins += 1) {
+        runtime.system.yield();
+    }
+    if (detach_done.load(.acquire) != 1) {
+        write("thread-test: FAIL detached worker did not run\n");
+        return;
+    }
+
+    // Prove join needs no per-thread kernel endpoint (M9): many spawn+join cycles. Under
+    // the old per-thread-endpoint scheme these leaked handles and would exhaust the
+    // 16-slot handle table well before 40; here they all succeed.
+    var cycle: u32 = 0;
+    while (cycle < 40) : (cycle += 1) {
+        const th = runtime.Thread.spawn(.{}, noopWorker, .{}) catch {
+            write("thread-test: FAIL spawn exhausted across join cycles (endpoint leak?)\n");
+            return;
+        };
+        th.join();
+    }
+
+    write("thread-test: join ok\n"); // the M3/M9 verdict marker
+}
+
+// --- M4: futex mode ---------------------------------------------------------
+
+const Futex = runtime.Thread.Futex;
+
+var futex_word = std.atomic.Value(u32).init(0);
+var waiter_parked = std.atomic.Value(u32).init(0);
+
+fn futexWaiter() void {
+    write("thread-futex: waiting\n");
+    waiter_parked.store(1, .release);
+    // Block while the word is still 0; the waker sets it to 1 and wakes us.
+    while (futex_word.load(.acquire) == 0) {
+        Futex.wait(&futex_word, 0);
+    }
+    write("thread-futex: woke\n");
+}
+
+fn runFutexMode() void {
+    write("thread-futex: starting\n");
+
+    const waiter = runtime.Thread.spawn(.{}, futexWaiter, .{}) catch {
+        write("thread-futex: FAIL spawn refused\n");
+        return;
+    };
+    // Let the waiter reach its wait, then give it a beat to actually park in-kernel.
+    var spins: usize = 0;
+    while (waiter_parked.load(.acquire) == 0 and spins < 50_000_000) : (spins += 1) {
+        runtime.system.yield();
+    }
+    runtime.system.sleep(50);
+
+    // The handshake: publish the value, then wake the parked waiter.
+    futex_word.store(1, .release);
+    write("thread-futex: waking\n");
+    Futex.wake(&futex_word, 1);
+
+    waiter.join(); // returns once the waiter woke and printed "woke"
+
+    // Timeout: nobody ever wakes this word, so timedWait must report a timeout.
+    var lonely = std.atomic.Value(u32).init(0);
+    if (Futex.timedWait(&lonely, 0, 100_000_000)) |_| {
+        write("thread-futex: FAIL timedWait did not time out\n");
+        return;
+    } else |_| {}
+    write("thread-futex: timeout ok\n");
+
+    write("thread-futex: ok\n"); // the M4 verdict marker
+}
+
+// --- M5: mutex mode (bounded producer/consumer over Mutex + Condition) ------
+
+const Mutex = runtime.Thread.Mutex;
+const Condition = runtime.Thread.Condition;
+
+const producers: u32 = 2;
+const consumers: u32 = 2;
+const per_producer: u32 = 1000;
+const per_consumer: u32 = 1000; // producers*per_producer == consumers*per_consumer (balanced)
+const total_items: u32 = producers * per_producer;
+const ring_cap: usize = 8; // small, so producers block on full and consumers on empty
+
+var ring: [ring_cap]u32 = undefined;
+var ring_count: usize = 0;
+var ring_head: usize = 0;
+var ring_tail: usize = 0;
+
+var pc_mutex = Mutex{};
+var not_full = Condition{};
+var not_empty = Condition{};
+
+// Verified outside the lock: the checksum and tally of everything consumed.
+var consumed_sum = std.atomic.Value(u64).init(0);
+var consumed_count = std.atomic.Value(u32).init(0);
+
+fn producer(base: u32) void {
+    var i: u32 = 0;
+    while (i < per_producer) : (i += 1) {
+        const item = base + i;
+        pc_mutex.lock();
+        while (ring_count == ring_cap) not_full.wait(&pc_mutex);
+        ring[ring_tail] = item;
+        ring_tail = (ring_tail + 1) % ring_cap;
+        ring_count += 1;
+        pc_mutex.unlock();
+        not_empty.signal();
+    }
+}
+
+fn consumer() void {
+    var i: u32 = 0;
+    while (i < per_consumer) : (i += 1) {
+        pc_mutex.lock();
+        while (ring_count == 0) not_empty.wait(&pc_mutex);
+        const item = ring[ring_head];
+        ring_head = (ring_head + 1) % ring_cap;
+        ring_count -= 1;
+        pc_mutex.unlock();
+        not_full.signal();
+        _ = consumed_sum.fetchAdd(item, .monotonic);
+        _ = consumed_count.fetchAdd(1, .monotonic);
+    }
+}
+
+fn runMutexMode() void {
+    write("thread-mutex: starting\n");
+
+    var threads: [producers + consumers]runtime.Thread = undefined;
+    var n: usize = 0;
+    var p: u32 = 0;
+    while (p < producers) : (p += 1) {
+        threads[n] = runtime.Thread.spawn(.{}, producer, .{p * per_producer}) catch {
+            write("thread-mutex: FAIL producer spawn\n");
+            return;
+        };
+        n += 1;
+    }
+    var c: u32 = 0;
+    while (c < consumers) : (c += 1) {
+        threads[n] = runtime.Thread.spawn(.{}, consumer, .{}) catch {
+            write("thread-mutex: FAIL consumer spawn\n");
+            return;
+        };
+        n += 1;
+    }
+    for (threads[0..n]) |t| t.join();
+
+    // Every item 0..total_items-1 was produced exactly once; if the mutex/condition are
+    // correct, each was consumed exactly once, so the checksum matches.
+    const expected_sum: u64 = @as(u64, total_items) * (total_items - 1) / 2;
+    if (consumed_count.load(.acquire) != total_items) {
+        write("thread-mutex: FAIL wrong number of items consumed\n");
+        return;
+    }
+    if (consumed_sum.load(.acquire) != expected_sum) {
+        write("thread-mutex: FAIL checksum mismatch (item lost or duplicated)\n");
+        return;
+    }
+    write("thread-mutex: ok\n"); // the M5 verdict marker
+}
+
+// --- M6: id mode (getCurrentId identity) ------------------------------------
+
+var worker_ids: [2]std.atomic.Value(u32) = .{ std.atomic.Value(u32).init(0), std.atomic.Value(u32).init(0) };
+
+fn idWorker(slot: usize) void {
+    worker_ids[slot].store(runtime.Thread.getCurrentId(), .release);
+}
+
+fn runIdMode() void {
+    write("thread-id: starting\n");
+    const main_id = runtime.Thread.getCurrentId();
+
+    const t0 = runtime.Thread.spawn(.{}, idWorker, .{@as(usize, 0)}) catch {
+        write("thread-id: FAIL spawn\n");
+        return;
+    };
+    const t1 = runtime.Thread.spawn(.{}, idWorker, .{@as(usize, 1)}) catch {
+        write("thread-id: FAIL spawn\n");
+        return;
+    };
+    t0.join();
+    t1.join();
+
+    const id0 = worker_ids[0].load(.acquire);
+    const id1 = worker_ids[1].load(.acquire);
+    // Each thread has its own kernel task id: all three distinct and non-zero.
+    if (main_id == 0 or id0 == 0 or id1 == 0) {
+        write("thread-id: FAIL a thread reported id 0\n");
+        return;
+    }
+    if (id0 == id1 or id0 == main_id or id1 == main_id) {
+        write("thread-id: FAIL thread ids collided\n");
+        return;
+    }
+    write("thread-id: ok\n"); // the M6 verdict marker
+}
+
+// --- M7: alloc mode (concurrent heap allocation) ----------------------------
+
+const alloc_threads: u32 = 4;
+const allocs_per_thread: u32 = 500;
+var allocs_clean = std.atomic.Value(u32).init(0);
+
+fn allocWorker(seed: u32) void {
+    const gpa = runtime.allocator();
+    var rng: u32 = seed | 1;
+    var round: u32 = 0;
+    while (round < allocs_per_thread) : (round += 1) {
+        rng = rng *% 1664525 +% 1013904223; // cheap LCG for varied sizes
+        const size: usize = 16 + (rng % 4080); // 16..4095 bytes
+        const buf = gpa.alloc(u8, size) catch return; // OOM: don't count this thread clean
+        const pattern: u8 = @truncate(seed +% round);
+        @memset(buf, pattern);
+        // Nothing else should touch our block; if a concurrent allocation overlapped it,
+        // one of us would read the other's pattern here.
+        var ok = true;
+        for (buf) |b| {
+            if (b != pattern) ok = false;
+        }
+        gpa.free(buf);
+        if (!ok) return; // corruption — leave without counting clean
+    }
+    _ = allocs_clean.fetchAdd(1, .monotonic);
+}
+
+fn runAllocMode() void {
+    write("thread-alloc: starting\n");
+    var threads: [alloc_threads]runtime.Thread = undefined;
+    var n: u32 = 0;
+    while (n < alloc_threads) : (n += 1) {
+        threads[n] = runtime.Thread.spawn(.{}, allocWorker, .{n +% 1}) catch {
+            write("thread-alloc: FAIL spawn\n");
+            return;
+        };
+    }
+    for (threads[0..alloc_threads]) |t| t.join();
+
+    // Every thread must have completed all rounds with each block intact — proof the
+    // shared heap and the per-address_space mmap arena are safe under concurrent allocation.
+    if (allocs_clean.load(.acquire) != alloc_threads) {
+        write("thread-alloc: FAIL corruption or OOM under concurrent allocation\n");
+        return;
+    }
+    write("thread-alloc: ok\n"); // the M7 verdict marker
+}
+
+// --- M10: tls mode (per-thread FS base storage) -----------------------------
+
+fn writeTlsSlot(value: u64) void {
+    asm volatile ("movq %[v], %%fs:8"
+        :
+        : [v] "r" (value),
+        : .{ .memory = true });
+}
+
+fn readTlsSlot() u64 {
+    return asm volatile ("movq %%fs:8, %[out]"
+        : [out] "=r" (-> u64),
+        :
+        : .{ .memory = true });
+}
+
+var tls_written = std.atomic.Value(u32).init(0);
+var tls_ok = std.atomic.Value(u32).init(0);
+
+fn tlsWorker(marker: u64) void {
+    writeTlsSlot(marker);
+    _ = tls_written.fetchAdd(1, .release);
+    // Wait until both threads have written their own slot. If the FS base were shared, the
+    // second write would clobber the first, and the read below would return the wrong
+    // marker — cross-talk. A per-thread FS base keeps each thread's slot private.
+    var spins: usize = 0;
+    while (tls_written.load(.acquire) < 2 and spins < 50_000_000) : (spins += 1) {
+        runtime.system.yield();
+    }
+    if (readTlsSlot() == marker and runtime.Thread.getCurrentId() != 0) {
+        _ = tls_ok.fetchAdd(1, .monotonic);
+    }
+}
+
+fn runTlsMode() void {
+    write("thread-tls: starting\n");
+    const t0 = runtime.Thread.spawn(.{}, tlsWorker, .{@as(u64, 0xAAAA_0000)}) catch {
+        write("thread-tls: FAIL spawn\n");
+        return;
+    };
+    const t1 = runtime.Thread.spawn(.{}, tlsWorker, .{@as(u64, 0xBBBB_0000)}) catch {
+        write("thread-tls: FAIL spawn\n");
+        return;
+    };
+    t0.join();
+    t1.join();
+    if (tls_ok.load(.acquire) == 2) {
+        write("thread-tls: ok\n"); // the M10 verdict marker
+    } else {
+        write("thread-tls: FAIL cross-talk (FS base not per-thread)\n");
+    }
+}
+
+// --- M11: rwlock mode (readers/writers over an RwLock) ----------------------
+
+const RwLock = runtime.Thread.RwLock;
+
+var rwlock = RwLock{};
+var rw_a: u64 = 0;
+var rw_b: u64 = 0; // invariant while any lock is held: rw_a == rw_b
+var rw_stop = std.atomic.Value(u32).init(0);
+var rw_violations = std.atomic.Value(u32).init(0);
+var rw_reads = std.atomic.Value(u64).init(0);
+
+fn rwWriter() void {
+    var v: u64 = 1;
+    while (rw_stop.load(.acquire) == 0) : (v +%= 1) {
+        rwlock.lock(); // exclusive: no reader may observe the gap between the two writes
+        rw_a = v;
+        rw_b = v;
+        rwlock.unlock();
+    }
+}
+
+fn rwReader() void {
+    const reads: u64 = 50_000;
+    var i: u64 = 0;
+    while (i < reads) : (i += 1) {
+        rwlock.lockShared();
+        if (rw_a != rw_b) _ = rw_violations.fetchAdd(1, .monotonic); // saw a half-write!
+        rwlock.unlockShared();
+    }
+    _ = rw_reads.fetchAdd(reads, .monotonic);
+}
+
+fn runRwlockMode() void {
+    write("thread-rwlock: starting\n");
+    var writers: [2]runtime.Thread = undefined;
+    var readers: [3]runtime.Thread = undefined;
+    for (&writers) |*w| {
+        w.* = runtime.Thread.spawn(.{}, rwWriter, .{}) catch {
+            write("thread-rwlock: FAIL spawn\n");
+            return;
+        };
+    }
+    for (&readers) |*r| {
+        r.* = runtime.Thread.spawn(.{}, rwReader, .{}) catch {
+            write("thread-rwlock: FAIL spawn\n");
+            return;
+        };
+    }
+    for (readers) |r| r.join();
+    rw_stop.store(1, .release); // readers done → stop the writers
+    for (writers) |w| w.join();
+
+    if (rw_violations.load(.acquire) == 0 and rw_reads.load(.acquire) > 0) {
+        write("thread-rwlock: ok\n"); // the M11 verdict marker
+    } else {
+        write("thread-rwlock: FAIL reader observed a half-written value\n");
+    }
+}
+
+pub fn main(init: runtime.process.Init) void {
+    const mode = init.arguments.get(1) orelse "spawn";
+    if (std.mem.eql(u8, mode, "join")) {
+        runJoinMode();
+    } else if (std.mem.eql(u8, mode, "futex")) {
+        runFutexMode();
+    } else if (std.mem.eql(u8, mode, "mutex")) {
+        runMutexMode();
+    } else if (std.mem.eql(u8, mode, "id")) {
+        runIdMode();
+    } else if (std.mem.eql(u8, mode, "alloc")) {
+        runAllocMode();
+    } else if (std.mem.eql(u8, mode, "tls")) {
+        runTlsMode();
+    } else if (std.mem.eql(u8, mode, "rwlock")) {
+        runRwlockMode();
+    } else {
+        runSpawnMode();
+    }
+}

test/qemu_test.py

@@ -293,6 +293,84 @@ CASES = [
      "timeout": 60,
      "expect": r"DANOS-TEST-RESULT: PASS",
      "fail":   r"DANOS-TEST-RESULT: FAIL"},
+
+    # docs/threading-plan.md M1: address-space refcount — spaces destroyed exactly
+    # once per process, no leak/double-free (the foundation shared-address-space threads need).
+    {"name": "address-space-refcount",
+     "timeout": 60,
+     "expect": r"DANOS-TEST-RESULT: PASS",
+     "fail":   r"DANOS-TEST-RESULT: FAIL"},
+
+    # docs/threading-plan.md M2: runtime.Thread.spawn — a worker thread runs in the
+    # caller's address space (a shared-memory write, observed by the main thread).
+    {"name": "thread-spawn",
+     "timeout": 60,
+     "expect": r"DANOS-TEST-RESULT: PASS",
+     "fail":   r"DANOS-TEST-RESULT: FAIL"},
+
+    # docs/threading-plan.md M3: join + parallelism — N workers each do K atomic
+    # increments (total exactly N*K after join) and run on >1 core; plus detach.
+    {"name": "thread-join",
+     "smp":    4,
+     "timeout": 60,
+     "expect": r"DANOS-TEST-RESULT: PASS",
+     "fail":   r"DANOS-TEST-RESULT: FAIL"},
+
+    # docs/threading-plan.md M4: futex — a thread parks in futex_wait and is woken by
+    # futex_wake (serial order waiting/waking/woke), and timedWait reports a timeout.
+    {"name": "thread-futex",
+     "smp":    4,
+     "timeout": 60,
+     "expect": r"thread-futex: waiting[\s\S]*thread-futex: waking[\s\S]*thread-futex: woke[\s\S]*DANOS-TEST-RESULT: PASS",
+     "fail":   r"DANOS-TEST-RESULT: FAIL"},
+
+    # docs/threading-plan.md M5: Mutex + Condition — a bounded producer/consumer moves
+    # N unique items across cores; the consumed checksum matches exactly (no loss).
+    {"name": "thread-mutex",
+     "smp":    4,
+     "timeout": 60,
+     "expect": r"DANOS-TEST-RESULT: PASS",
+     "fail":   r"DANOS-TEST-RESULT: FAIL"},
+
+    # docs/threading-plan.md M6: thread identity — getCurrentId is distinct and non-zero
+    # for the main thread and two workers.
+    {"name": "thread-id",
+     "smp":    4,
+     "timeout": 60,
+     "expect": r"DANOS-TEST-RESULT: PASS",
+     "fail":   r"DANOS-TEST-RESULT: FAIL"},
+
+    # docs/threading-plan.md M7: thread-safe allocation — N threads hammer the shared heap
+    # (per-aspace mmap arena + locked free list) with no cross-block corruption.
+    {"name": "thread-alloc",
+     "smp":    4,
+     "timeout": 60,
+     "expect": r"DANOS-TEST-RESULT: PASS",
+     "fail":   r"DANOS-TEST-RESULT: FAIL"},
+
+    # docs/threading-plan.md M8: the task reaper — spawn+kill many processes; total kernel
+    # stack bytes return to baseline (every dead task's stack reclaimed, no leak).
+    {"name": "task-reap",
+     "smp":    4,
+     "timeout": 60,
+     "expect": r"DANOS-TEST-RESULT: PASS",
+     "fail":   r"DANOS-TEST-RESULT: FAIL"},
+
+    # docs/threading-plan.md M10: per-thread fs.base — two threads keep private %fs:8 TLS
+    # slots across context switches (no cross-talk).
+    {"name": "thread-tls",
+     "smp":    4,
+     "timeout": 60,
+     "expect": r"DANOS-TEST-RESULT: PASS",
+     "fail":   r"DANOS-TEST-RESULT: FAIL"},
+
+    # docs/threading-plan.md M11: RwLock — readers/writers across cores; a reader never
+    # observes a half-written value (writers hold it exclusively).
+    {"name": "thread-rwlock",
+     "smp":    4,
+     "timeout": 60,
+     "expect": r"DANOS-TEST-RESULT: PASS",
+     "fail":   r"DANOS-TEST-RESULT: FAIL"},
     # Process arguments: argv arrives on the SysV entry stack (argv[0] = the spawned
     # name, argv[1..] = the system_spawn argument blob) and echoes back intact.
     {"name": "args",

tools/make-iso-image.py

@@ -0,0 +1,261 @@
+#!/usr/bin/env python3
+"""Wrap the FAT32 boot volume in a hybrid ISO — the flashable danos release image.
+
+Mirrors tools/make-fat-image.py in spirit: pure Python 3 standard library, no
+external tools (no xorriso / mkisofs / isohybrid). The output is one file that
+boots both ways release media is consumed:
+
+  * Flashed raw to a USB stick (Etcher, dd): the ISO's system area carries an
+    MBR whose single partition (type 0xEF, "EFI System") points at the FAT32
+    image embedded in the ISO, so UEFI firmware finds the ESP and runs
+    \\EFI\\BOOT\\BOOTX64.efi off it.
+  * Burned to optical media: an El Torito boot catalog with an EFI platform
+    entry points at the same embedded FAT image.
+
+The ISO9660 filesystem itself is minimal but valid — a primary volume
+descriptor, the El Torito boot record, path tables, and a root directory that
+lists the boot catalog and the FAT image — so inspection tools can open it.
+
+    make-iso-image.py <out.iso> <esp.img>
+    make-iso-image.py --verify <out.iso>
+
+All timestamp fields are zero ("not specified") so the build is reproducible.
+"""
+
+import struct
+import sys
+
+ISO_SECTOR = 2048
+
+# Fixed layout, in ISO sectors (LBA). Sectors 0-15 are the system area (the
+# hybrid MBR lives in its first 512 bytes); volume descriptors start at 16.
+PVD_LBA = 16          # primary volume descriptor
+BOOT_RECORD_LBA = 17  # El Torito boot record volume descriptor
+TERMINATOR_LBA = 18   # volume descriptor set terminator
+PATH_TABLE_L_LBA = 19
+PATH_TABLE_M_LBA = 20
+ROOT_DIR_LBA = 21     # root directory (one sector holds our four records)
+CATALOG_LBA = 22      # El Torito boot catalog
+ESP_LBA = 23          # the embedded FAT32 image starts here
+
+MBR_PARTITION_TYPE_ESP = 0xEF
+
+
+def both16(value):
+    """ISO9660 both-byte-order encoding: little-endian then big-endian."""
+    return struct.pack("<H", value) + struct.pack(">H", value)
+
+
+def both32(value):
+    return struct.pack("<I", value) + struct.pack(">I", value)
+
+
+def directory_record(identifier, lba, size, flags):
+    length = 33 + len(identifier)
+    if length % 2:
+        length += 1  # records are padded to even length
+    record = bytearray(length)
+    record[0] = length
+    record[2:10] = both32(lba)
+    record[10:18] = both32(size)
+    # record[18:25] is the recording date; zero = unspecified (reproducible).
+    record[25] = flags  # 0x02 = directory
+    record[28:32] = both16(1)  # volume sequence number
+    record[32] = len(identifier)
+    record[33:33 + len(identifier)] = identifier
+    return bytes(record)
+
+
+def primary_volume_descriptor(total_sectors, path_table_size):
+    sector = bytearray(ISO_SECTOR)
+    sector[0] = 1  # type: primary
+    sector[1:6] = b"CD001"
+    sector[6] = 1  # version
+    sector[8:40] = b"DANOS".ljust(32)  # system identifier
+    sector[40:72] = b"DANOS".ljust(32)  # volume identifier
+    sector[80:88] = both32(total_sectors)
+    sector[120:124] = both16(1)  # volume set size
+    sector[124:128] = both16(1)  # volume sequence number
+    sector[128:132] = both16(ISO_SECTOR)  # logical block size
+    sector[132:140] = both32(path_table_size)
+    sector[140:144] = struct.pack("<I", PATH_TABLE_L_LBA)
+    sector[148:152] = struct.pack(">I", PATH_TABLE_M_LBA)
+    sector[156:190] = directory_record(b"\x00", ROOT_DIR_LBA, ISO_SECTOR, 0x02)
+    sector[190:318] = b" " * 128  # volume set identifier
+    sector[318:446] = b" " * 128  # publisher
+    sector[446:574] = b" " * 128  # data preparer
+    sector[574:702] = b"DANOS MAKE-ISO-IMAGE".ljust(128)  # application
+    sector[702:739] = b" " * 37  # copyright file
+    sector[739:776] = b" " * 37  # abstract file
+    sector[776:813] = b" " * 37  # bibliographic file
+    unspecified_date = b"0" * 16 + b"\x00"
+    for offset in (813, 830, 847, 864):  # creation/modification/expiry/effective
+        sector[offset:offset + 17] = unspecified_date
+    sector[881] = 1  # file structure version
+    return bytes(sector)
+
+
+def boot_record_descriptor():
+    sector = bytearray(ISO_SECTOR)
+    sector[0] = 0  # type: boot record
+    sector[1:6] = b"CD001"
+    sector[6] = 1
+    sector[7:39] = b"EL TORITO SPECIFICATION".ljust(32, b"\x00")
+    sector[71:75] = struct.pack("<I", CATALOG_LBA)
+    return bytes(sector)
+
+
+def terminator_descriptor():
+    sector = bytearray(ISO_SECTOR)
+    sector[0] = 255
+    sector[1:6] = b"CD001"
+    sector[6] = 1
+    return bytes(sector)
+
+
+def path_table(byte_order):
+    # A single entry: the root directory.
+    return (struct.pack("BB", 1, 0)
+            + struct.pack(byte_order + "I", ROOT_DIR_LBA)
+            + struct.pack(byte_order + "H", 1)
+            + b"\x00\x00")  # identifier 0x00 + pad to even
+
+
+def root_directory(esp_size):
+    # Records must be sorted by identifier; BOOT.CAT < EFI.IMG holds.
+    entries = (directory_record(b"\x00", ROOT_DIR_LBA, ISO_SECTOR, 0x02)
+               + directory_record(b"\x01", ROOT_DIR_LBA, ISO_SECTOR, 0x02)
+               + directory_record(b"BOOT.CAT;1", CATALOG_LBA, ISO_SECTOR, 0)
+               + directory_record(b"EFI.IMG;1", ESP_LBA, esp_size, 0))
+    return entries + b"\x00" * (ISO_SECTOR - len(entries))
+
+
+def boot_catalog(esp_size):
+    # Validation entry: EFI platform (0xEF), checksummed so its 16-bit words sum
+    # to zero, closed by the 0x55AA key bytes.
+    validation = bytearray(32)
+    validation[0] = 0x01
+    validation[1] = 0xEF
+    validation[4:28] = b"danos".ljust(24, b"\x00")
+    validation[30] = 0x55
+    validation[31] = 0xAA
+    checksum = (-sum(struct.unpack("<16H", validation))) & 0xFFFF
+    validation[28:30] = struct.pack("<H", checksum)
+    # Initial/default entry: bootable, no emulation, image at ESP_LBA. The
+    # sector-count field is 16-bit (units of 512 bytes) so it can't span a large
+    # ESP; UEFI firmware sizes the FAT filesystem from its own BPB, and the
+    # image's boot files sit well inside the capped span regardless.
+    default = bytearray(32)
+    default[0] = 0x88  # bootable
+    default[1] = 0x00  # no emulation
+    sector_count = min(0xFFFF, esp_size // 512)
+    default[6:8] = struct.pack("<H", sector_count)
+    default[8:12] = struct.pack("<I", ESP_LBA)
+    catalog = bytes(validation) + bytes(default)
+    return catalog + b"\x00" * (ISO_SECTOR - len(catalog))
+
+
+def hybrid_mbr(esp_size):
+    """The system-area MBR that makes the ISO flashable: one ESP partition."""
+    mbr = bytearray(512)
+    mbr[440:444] = b"dano"  # disk signature (fixed: reproducible builds)
+    start_lba = ESP_LBA * (ISO_SECTOR // 512)
+    partition = struct.pack(
+        "<B3sB3sII",
+        0x80,                      # status: active (harmless; helps picky firmware)
+        b"\xFE\xFF\xFF",           # CHS start: maxed out, LBA is authoritative
+        MBR_PARTITION_TYPE_ESP,    # type: EFI System
+        b"\xFE\xFF\xFF",           # CHS end
+        start_lba,
+        esp_size // 512,
+    )
+    mbr[446:462] = partition
+    mbr[510] = 0x55
+    mbr[511] = 0xAA
+    return bytes(mbr)
+
+
+def build(out_path, esp_path):
+    with open(esp_path, "rb") as handle:
+        esp = handle.read()
+    if len(esp) % ISO_SECTOR:
+        esp += b"\x00" * (ISO_SECTOR - len(esp) % ISO_SECTOR)
+    esp_sectors = len(esp) // ISO_SECTOR
+    total_sectors = ESP_LBA + esp_sectors
+
+    table_l = path_table("<")
+    image = bytearray(total_sectors * ISO_SECTOR)
+    image[0:512] = hybrid_mbr(len(esp))
+    image[PVD_LBA * ISO_SECTOR:(PVD_LBA + 1) * ISO_SECTOR] = \
+        primary_volume_descriptor(total_sectors, len(table_l))
+    image[BOOT_RECORD_LBA * ISO_SECTOR:(BOOT_RECORD_LBA + 1) * ISO_SECTOR] = \
+        boot_record_descriptor()
+    image[TERMINATOR_LBA * ISO_SECTOR:(TERMINATOR_LBA + 1) * ISO_SECTOR] = \
+        terminator_descriptor()
+    image[PATH_TABLE_L_LBA * ISO_SECTOR:PATH_TABLE_L_LBA * ISO_SECTOR + len(table_l)] = table_l
+    table_m = path_table(">")
+    image[PATH_TABLE_M_LBA * ISO_SECTOR:PATH_TABLE_M_LBA * ISO_SECTOR + len(table_m)] = table_m
+    image[ROOT_DIR_LBA * ISO_SECTOR:(ROOT_DIR_LBA + 1) * ISO_SECTOR] = root_directory(len(esp))
+    image[CATALOG_LBA * ISO_SECTOR:(CATALOG_LBA + 1) * ISO_SECTOR] = boot_catalog(len(esp))
+    image[ESP_LBA * ISO_SECTOR:] = esp
+
+    with open(out_path, "wb") as handle:
+        handle.write(image)
+    print(f"make-iso-image: wrote {out_path} "
+          f"({total_sectors * ISO_SECTOR // (1024 * 1024)} MiB hybrid ISO, "
+          f"ESP at LBA {ESP_LBA}, {esp_sectors} sectors)")
+
+
+def verify(path):
+    with open(path, "rb") as handle:
+        data = handle.read()
+    # The hybrid MBR (the Etcher/dd boot path).
+    if data[510] != 0x55 or data[511] != 0xAA:
+        sys.exit("verify: missing MBR 0x55AA signature")
+    status, _, part_type, _, part_start, part_sectors = \
+        struct.unpack_from("<B3sB3sII", data, 446)
+    if part_type != MBR_PARTITION_TYPE_ESP:
+        sys.exit(f"verify: MBR partition type 0x{part_type:02X}, expected 0xEF (ESP)")
+    # The ISO9660 descriptors (the optical boot path).
+    if data[PVD_LBA * ISO_SECTOR + 1:PVD_LBA * ISO_SECTOR + 6] != b"CD001":
+        sys.exit("verify: no primary volume descriptor")
+    boot_record = data[BOOT_RECORD_LBA * ISO_SECTOR:(BOOT_RECORD_LBA + 1) * ISO_SECTOR]
+    if not boot_record.startswith(b"\x00CD001") or \
+            not boot_record[7:30].startswith(b"EL TORITO SPECIFICATION"):
+        sys.exit("verify: no El Torito boot record")
+    catalog_lba = struct.unpack_from("<I", boot_record, 71)[0]
+    catalog = data[catalog_lba * ISO_SECTOR:(catalog_lba + 1) * ISO_SECTOR]
+    if catalog[0] != 0x01 or catalog[1] != 0xEF or catalog[30:32] != b"\x55\xAA":
+        sys.exit("verify: boot catalog validation entry is not an EFI entry")
+    if sum(struct.unpack("<16H", catalog[0:32])) & 0xFFFF != 0:
+        sys.exit("verify: boot catalog validation checksum is wrong")
+    if catalog[32] != 0x88:
+        sys.exit("verify: default catalog entry is not bootable")
+    boot_lba = struct.unpack_from("<I", catalog, 40)[0]
+    # Both paths must agree on where the ESP lives, and it must be a FAT32 image.
+    if boot_lba * (ISO_SECTOR // 512) != part_start:
+        sys.exit(f"verify: catalog boot image (LBA {boot_lba}) and MBR partition "
+                 f"(sector {part_start}) disagree")
+    esp = data[boot_lba * ISO_SECTOR:]
+    if len(esp) < part_sectors * 512:
+        sys.exit("verify: MBR partition extends past the end of the file")
+    if esp[510] != 0x55 or esp[511] != 0xAA or esp[82:90] != b"FAT32   ":
+        sys.exit("verify: embedded image is not a FAT32 boot volume")
+    print(f"verify: {path} is a hybrid ISO — MBR ESP partition (sector {part_start}, "
+          f"{part_sectors} sectors, active={status == 0x80}) and El Torito EFI entry "
+          f"both point at the embedded FAT32 image")
+
+
+def main(argv):
+    if len(argv) == 3 and argv[1] == "--verify":
+        verify(argv[2])
+        return 0
+    if len(argv) != 3:
+        sys.exit("usage: make-iso-image.py <out.iso> <esp.img>\n"
+                 "       make-iso-image.py --verify <out.iso>")
+    build(argv[1], argv[2])
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))