Vision

Mission

VibeOS aims to be a modern operating system built from scratch in C and C++ for production-grade research, advanced systems experimentation, and eventual real-world deployment. The system is designed to provide strong performance, principled security, and a compatibility strategy that can host applications originating from Linux, Windows, and macOS.

Design principles

1. Security first

Security is a first-class architectural property, not an add-on. The system is designed around least privilege, strong isolation, memory protection, capability-aware resource access, and explicit trust boundaries between kernel, services, drivers, and applications.

2. Performance without hidden complexity

Fast paths must stay simple, measurable, and observable. Kernel transitions, scheduling, IPC, memory management, and I/O paths should be designed with low overhead and scalability on many-core systems.

3. Modular evolution

The OS must support distributed development by allowing major subsystems to evolve independently behind stable interfaces. This includes driver hosting, filesystem services, compatibility runtimes, networking, and userland service layers.

4. Compatibility as architecture

Running third-party software from Linux, Windows, and macOS must influence core design decisions from day one. The OS must expose the right primitives for compatibility layers, ABI shims, containerization, and lightweight virtualization.

5. Portability by construction

The architecture should separate machine-independent kernel code from platform-specific code. Initial implementation targets x86_64, but interfaces should anticipate future ARM64 support.

Product goals

Performance goals

• low-latency scheduling and interrupt handling
• low-overhead system call and IPC paths
• scalable multicore execution with minimized global contention
• NUMA-aware evolution path for future hardware targets
• efficient page fault handling and virtual memory operations

Security goals

• strong process and service isolation
• explicit privilege domains
• memory-safe subsystem boundaries where practical through language and interface discipline
• hardened kernel build and runtime protections
• sandboxing for untrusted applications and compatibility runtimes

Compatibility goals

• Linux application support as the first compatibility priority
• Windows user-mode compatibility as the second major priority
• macOS compatibility pursued selectively through runtime, API translation, and managed execution strategies rather than full binary parity in early phases
• architecture support for containers, para-virtualization, and restricted guest environments

Non-goals for early phases

• immediate support for all hardware classes
• complete POSIX, Win32, or Darwin kernel parity in the first milestones
• broad consumer desktop readiness before core kernel reliability
• unrestricted kernel extension ABI stability before internal interfaces mature

Success criteria for the project foundation

Phase 1 is successful when the project has:

• a clear architectural stance
• documented subsystem boundaries
• repository organization suitable for long-term work
• milestone sequencing that de-risks the kernel bring-up path
• a compatibility strategy that does not compromise kernel integrity

Architecture

Kernel architecture options evaluated

Monolithic kernel

Advantages:

• best-case performance due to fewer context switches and direct internal calls
• simpler early boot and subsystem bring-up
• mature development pattern used by several high-performance kernels

Disadvantages:

• weak fault isolation for drivers and services
• larger trusted computing base
• harder long-term maintainability for a compatibility-heavy OS
• greater risk when integrating experimental subsystems

Microkernel

Advantages:

• strong isolation for drivers, filesystems, and services
• smaller privileged kernel core
• better resilience and restartability of failed services
• natural fit for compatibility subsystems living outside kernel mode

Disadvantages:

• IPC overhead can harm performance if not designed carefully
• more complex service orchestration and bootstrapping
• harder path for latency-critical subsystems if purity is enforced rigidly

Hybrid kernel

Advantages:

• allows microkernel-like compartmentalization without forcing every service out of kernel space
• lets the project keep latency-critical primitives in privileged space
• supports pragmatic evolution as performance data becomes available

Disadvantages:

• architectural discipline is harder to maintain
• can devolve into a monolith without strict module boundaries
• requires careful criteria for what may run in kernel space

Modular monolithic kernel

Advantages:

• practical implementation path
• kernel modules can be developed independently
• strong performance characteristics

Disadvantages:

• modules still share the same failure domain
• weaker security boundaries for drivers and compatibility components
• poor fit for long-term least-privilege goals

Final decision

VibeOS adopts a hybrid microkernel-inspired modular architecture.

Rationale

This design best satisfies the project goals:

• performance-critical primitives remain in a compact kernel core
• compatibility services and risky subsystems can run outside the kernel
• the system can evolve toward stronger isolation without rewriting the core
• user-space services can host Linux, Windows, and macOS translation layers more safely than a monolithic compatibility design

High-level structure

Ring 0 kernel core

• trap and interrupt management
• virtual memory primitives
• scheduler and CPU topology management
• thread, process, and handle core objects
• IPC and synchronization primitives
• kernel object namespace and capability enforcement
• timekeeping and low-level hardware abstraction

Privileged kernel modules

Allowed only for measured performance or boot-critical reasons:

• physical and virtual memory backends
• select storage and network fast paths
• architecture-specific low-level platform support

User-space system services

• driver hosts
• filesystem servers
• network control plane services
• process manager extensions
• security policy engines
• compatibility subsystems
• service manager and session manager

Placement policy

To prevent the hybrid design from collapsing into an undisciplined monolith, a subsystem may run in kernel space only if it satisfies at least one of the following:

• it is required before the first trusted user-space service can start
• it sits directly on an interrupt-latency-critical path
• it would impose unacceptable context-switch or copying overhead if moved out of kernel space
• it enforces a protection boundary that cannot safely be delegated

Everything else defaults to user space. Any exception should be justified by measurement, not convenience.

Core abstractions

Execution model

• CPU
• kernel thread
• user thread
• process
• job or cgroup-like resource domain
• protection domain

Resource model

• handle-based object access
• capability-tagged rights for sensitive objects
• explicit namespace boundaries
• service endpoints for message-based interaction

Communication model

• fast local IPC with shared-memory assisted channels
• async and sync message passing
• event objects and wait sets
• brokered cross-domain communication for sandboxed applications

Portability strategy

The codebase is split into:

• kernel/arch/ architecture-specific code
• kernel/platform/ firmware and board integration
• kernel/ architecture-independent core
• user/ user-space services and applications

Initial target:

• x86_64 with UEFI boot and SMP

Planned next target:

• ARM64 with UEFI or platform loader support

Compatibility architecture placement

Compatibility is not implemented inside the core kernel ABI. Instead, VibeOS exposes kernel primitives that allow:

• Linux personality runtimes
• Windows subsystem servers
• macOS-oriented runtime environments
• lightweight virtual machines for unmodified workloads where translation is not viable

This reduces kernel ABI bloat and keeps policy and emulation logic outside ring 0.

Architectural constraints

The design deliberately avoids:

• exposing foreign kernel ABIs as first-class native kernel interfaces
• allowing user-space subsystems to depend on unstable private kernel structures
• placing full filesystem parsers or broad driver stacks in ring 0 without demonstrated need

Where the code currently differs. The five filesystem drivers, the virtio block and network drivers and the PS/2 input drivers are in ring 0 today, not in user-space services. That is a deliberate staging decision - getting the semantics right in one address space first - and not a revision of the target above. The layering is arranged so the move is possible: a filesystem driver reaches the disk only through vibeos_blockdev_t, and callers reach a filesystem only through vibeos_fs_ops_t, so neither side names the other. It should be read as debt with a plan, not as the design.

• promising complete foreign application parity before subsystem maturity and legal review

Software Architecture Specification

0. Scope and Source Inputs

This document consolidates the project-manager-level material already present in the repository into a single software architecture specification suitable for system engineers. It is the primary technical reference for Phase 2 and later implementation work.

Source inputs:

• project vision and goals
• architectural direction and subsystem design notes
• compatibility strategy
• development roadmap and risk register

Primary source documents already available in the repository:

• docs/vision.md
• docs/architecture.md
• docs/boot.md
• docs/kernel_design.md
• docs/memory_management.md
• docs/scheduler.md
• docs/filesystem.md
• docs/security.md
• docs/compatibility.md
• docs/ipc.md
• docs/toolchain.md
• docs/testing_strategy.md

1. Architectural Vision

1.1 System mission

VibeOS is a new operating system built from scratch in C and C++. It targets modern x86_64 systems first, with a planned ARM64 path, and is designed to combine:

• a security-first execution model
• low-overhead multicore performance
• modular subsystem evolution
• support for Linux, Windows, and selected Darwin or macOS-adjacent software through compatibility subsystems rather than native-kernel ABI cloning

1.2 Architecture style selection

1.3 Selected kernel model

The system shall use a hybrid microkernel-inspired modular kernel with the following rule:

• the kernel core contains only primitives that are unsafe, impossible, or measurably inefficient to host in user space
• drivers, filesystems, policy engines, compatibility runtimes, and high-risk parsers default to user space
  • as implemented today, the filesystem and device drivers are in the kernel; see the note in docs/architecture.md for why, and for the interfaces that keep the move open
• any privileged exception requires architectural review and benchmark evidence

1.4 Design drivers

2. System Context and High-Level Structure

2.1 Layered model

Applications
  -> Native VibeOS apps
  -> Linux compatibility domain
  -> Windows compatibility domain
  -> Darwin/macOS-adjacent runtime domain

System services
  -> init
  -> service manager
  -> device manager
  -> filesystem services
  -> network services
  -> security services
  -> compatibility subsystem hosts

Kernel core
  -> scheduler
  -> virtual memory
  -> object model and handles
  -> IPC primitives
  -> interrupt and exception handling
  -> timekeeping

Platform layer
  -> CPU and SMP bring-up
  -> interrupt controllers
  -> timers
  -> firmware tables
  -> bus discovery support

2.2 Major execution domains

2.3 Placement policy

A component may execute in kernel space only if at least one of these is true:

• it is required before trusted user-space services exist
• it is on an interrupt-latency-critical path
• moving it out of kernel space causes unacceptable measured overhead
• it enforces a protection boundary that cannot be delegated safely

All other components shall remain in user space.

3. Kernel Architecture

3.1 Process management

The process model is object-based.

Each process owns:

• one virtual address space
• one handle table
• one security identity and rights context
• one resource-accounting record
• one or more threads

Optional higher-order containment objects, called jobs, group multiple processes for:

• resource accounting
• lifetime control
• sandbox policy application
• compatibility-domain scoping

Process creation modes shall include:

• native image spawn
• fork-like compatibility mode implemented above the native API
• service host spawn
• restricted sandbox spawn

3.2 Thread model

The kernel uses a 1:1 kernel-thread model for schedulable entities. User-space runtimes may build additional user-thread or coroutine schedulers, but the kernel is aware only of kernel threads.

Each thread owns:

• CPU register state
• scheduling attributes and affinity mask
• exception state
• thread-local storage metadata
• wait state for IPC, timers, and synchronization objects

3.3 Scheduling

The scheduler is preemptive and priority-aware with fair distribution inside each priority class.

Mandatory properties:

• per-CPU run queues
• timer-driven preemption
• migration support for SMP balancing
• wake-up latency optimization for interactive threads
• starvation prevention through aging

Initial classes:

• realtime reserved for future controlled use
• interactive
• normal
• background

The first implementation may use round-robin within each priority band, but the contract shall allow later evolution toward weighted fair scheduling and deadline classes.

3.4 IPC

IPC is a first-class kernel subsystem because the architecture relies on service isolation.

Mandatory IPC primitives:

• message channels with preserved message boundaries
• shared memory objects for bulk transfer
• events for low-cost signaling
• wait sets for multiplexed blocking

IPC requirements:

• secure handle transfer
• bounded queues with backpressure
• synchronous request-response capability
• asynchronous notification support
• traceable latency and queue metrics

3.5 System call interface

The native syscall interface shall be compact, handle-based, and versioned.

Native syscall groups:

• process and thread lifecycle
• address-space and memory-object management
• channel, event, timer, and wait operations
• device and I/O primitives
• trace and diagnostic support
• security token and rights operations

The native syscall ABI shall not mirror Linux, Win32, or Darwin kernel APIs directly. Foreign-OS compatibility must be implemented above the native interface.

4. Hardware Abstraction Layer

4.1 Scope

The HAL provides the minimum architecture-specific layer required to hide platform differences from the kernel core.

Responsibilities:

• CPU feature discovery
• privileged instruction wrappers
• interrupt controller integration
• timer device integration
• memory-map ingestion from firmware
• SMP bring-up support
• bus and DMA mediation hooks for drivers

4.2 CPU management

For x86_64, the HAL shall support:

• bootstrap processor and application processor bring-up
• CPU-local storage and per-CPU structures
• context-switch support
• feature detection for paging, timers, and security capabilities

The design must isolate architecture-dependent code under kernel/arch/ and kernel/platform/ to permit ARM64 introduction without rewriting generic schedulers, IPC, or object-management logic.

4.3 Interrupt handling

Interrupt flow:

1. low-level trap entry in architecture code
2. interrupt source acknowledgement
3. dispatch to kernel interrupt handling layer
4. wake or schedule affected kernel or user-mode service work

Requirements:

• bounded interrupt-disabled sections
• deferred work outside the hardest interrupt path
• explicit distinction between exceptions, interrupts, and inter-processor interrupts

4.4 Hardware compatibility

Phase 1 assumptions:

• UEFI firmware
• x86_64 SMP
• QEMU as the first validation platform
• PCIe-centric discovery path

Later hardware enablement should proceed by adding device classes and platform adapters, not by widening kernel-global assumptions.

5. Memory Management

5.1 Physical memory management

The physical memory manager shall:

• ingest the firmware memory map
• classify regions into usable, reserved, firmware, device, and special-purpose ranges
• expose page-frame allocation services
• support DMA-constrained pools where required

Recommended first implementation:

• early boot bump allocator
• runtime buddy allocator for general page frames

5.2 Virtual memory

The virtual memory subsystem shall support:

• per-process address spaces
• higher-half kernel mapping
• direct physical map for kernel internals
• demand paging
• copy-on-write
• shared memory mappings
• file-backed mappings
• explicit protection changes

5.3 Allocators

5.4 Protection and hardening

Mandatory protections:

• user/kernel address-space separation
• per-page read, write, execute permissions
• W^X where compatible
• stack guard regions
• ASLR roadmap for kernel and user space

5.5 Cache and page-cache management

The system shall distinguish:

• CPU caches, managed indirectly through allocator locality and coherence rules
• kernel object caches for frequent fixed-size allocations
• unified page cache for file-backed data where feasible

The page cache must integrate with:

• filesystem services
• memory-mapped file objects
• invalidation on write-back and truncation

6. File System and Storage

6.1 VFS

The VFS shall provide:

• path resolution
• mount namespace handling
• file and directory object abstraction
• permission and policy hooks
• cache integration

6.2 Native filesystem

The native filesystem, currently referred to as AuroraFS, shall target:

• copy-on-write metadata updates
• metadata checksums
• optional data checksums
• extent-based allocation
• snapshot-ready design

Integrity model:

• metadata integrity is mandatory
• crash consistency must be provided by transactional or journaling-equivalent mechanisms

6.3 Storage stack

The storage architecture shall separate:

• block-device interfaces
• storage driver hosts
• filesystem services
• cache and memory-object integration

6.4 Foreign filesystem support

Planned interoperability path:

• FAT32 or exFAT for boot media and removable storage
• ext4 read-first support
• NTFS read support in later phases
• APFS deferred due to complexity and ecosystem constraints

Foreign filesystem write support requires explicit validation and must not be enabled based only on parser completeness.

7. Security Model

7.1 Security domains

The security model distinguishes:

• kernel core
• privileged services
• standard services
• compatibility runtimes
• sandboxed applications
• guest-backed workloads

7.2 Access control

The baseline mechanism is rights-controlled handle access.

Each handle contains:

• object type
• rights mask
• ownership or provenance metadata as needed

On top of handle rights, the system shall support a mandatory policy layer governing:

• filesystem access
• device access
• network permissions
• process interaction
• compatibility-domain restrictions

7.3 Authentication and identity

Early phases require local identities for:

• users
• system services
• sandbox principals

Enterprise identity, network authentication, and federated login are out of scope for the first implementation phases.

7.4 Sandboxing

Sandbox policy shall be able to restrict:

• visible filesystem roots
• device classes
• outbound and inbound network access
• IPC peers
• executable memory permissions

Compatibility runtimes must execute inside explicit compatibility domains with separate policy envelopes.

7.5 Capability and MAC direction

The preferred model is hybrid:

• capability-like handle rights for concrete object access
• MAC-like policy decisions for cross-cutting rules

This combines explicit kernel object authorization with system-wide policy control.

8. Networking Stack

8.1 Stack scope

The initial stack supports standard host networking for native and compatibility workloads.

Layer responsibilities:

• link layer integration through drivers
• IP routing and packet processing
• transport protocols
• socket API mediation
• control-plane configuration services

8.2 Required protocol support

Phase-ordered support:

• Ethernet
• IPv4
• IPv6
• ARP and neighbor discovery
• ICMP
• UDP
• TCP

Later candidates:

• firewalling and traffic policy
• TLS assist hooks
• QUIC-friendly APIs
• virtual switching and namespace-aware networking

8.3 Socket model

The native socket model shall support:

• blocking and non-blocking operation
• event-driven readiness
• compatibility translation for POSIX and Winsock semantics
• brokered raw-socket access for privileged use only

9. Driver Architecture

9.1 Driver model

Default rule: drivers run in user-space driver hosts.

Exception rule: a driver may run in privileged space only if it is:

• required before user-space services are available
• in a path that cannot tolerate user-space round-trips
• too tightly coupled to interrupt-time mechanisms

9.2 Driver manager

The device manager service shall handle:

• device discovery
• driver matching
• driver host spawning
• lifecycle supervision
• crash and restart policy

9.3 Dynamic loading and safety

Driver loading must be:

• explicit and policy-controlled
• version-checked against published driver-service contracts
• restartable for user-space hosted drivers

Direct unrestricted DMA or MMIO access must not be handed to drivers without mediation and auditing support.

10. User Space

10.1 Core services

Mandatory early services:

• init
• servicemgr
• devmgr
• filesystem service
• network service
• security policy service
• logging or tracing collector

10.2 System libraries and APIs

The user-space API stack shall include:

• a native C runtime
• a system library exposing the native kernel API
• optional C++ support for higher-level services

The native API is the only stable first-party contract. POSIX-like, Win32-like, or Darwin-like behavior belongs in compatibility layers.

10.3 Runtime environments

Supported runtime categories:

• native VibeOS runtime
• Linux compatibility runtime
• Windows subsystem runtime
• Darwin-oriented compatibility or guest-assist runtime

Compatibility runtimes must be separately versioned and testable.

11. Boot Process

11.1 Boot sequence

UEFI
  -> bootloader
  -> kernel image load
  -> early memory bootstrap
  -> trap and timer setup
  -> virtual memory enablement
  -> SMP startup
  -> init process
  -> service manager
  -> core services
  -> compatibility services

11.2 Bootloader responsibilities

The bootloader shall:

• load the kernel image
• provide a structured boot information block
• pass memory map and firmware tables
• hand over framebuffer or console information
• optionally verify images in secure boot configurations

11.3 Kernel initialization phases

1. early architecture setup
2. early allocation and memory-map parsing
3. interrupt and exception descriptor setup
4. scheduler bootstrap
5. SMP processor bring-up
6. transition to full allocators
7. launch first user-space process

12. Observability

12.1 Logging

Mandatory early logging channels:

• serial console
• in-memory kernel log buffer

Later channels:

• structured event stream
• persistent diagnostic storage

12.2 Tracing

The system shall provide tracepoints for:

• scheduler events
• IPC latency
• page faults and mapping changes
• driver and service failures
• compatibility runtime translation faults

12.3 Debugging

Required debugging capabilities:

• symbolized panic output in debug builds
• emulator-friendly debug attachment
• kernel assertions
• crash signature capture

13. Scalability and Performance

13.1 Multicore strategy

The architecture targets SMP from the beginning.

Mandatory properties:

• per-CPU run queues
• per-CPU statistics and local data where beneficial
• minimal global scheduler locks
• inter-processor interrupt support for wake-ups and TLB shootdowns

13.2 Optimization strategy

The performance plan prioritizes:

• short syscall paths
• shared-memory-assisted IPC
• lock partitioning
• reduced-copy I/O for large transfers
• locality-aware allocation

13.3 Scalability envelope

The first implementation targets developer and workstation-class systems. The architecture should remain extensible toward:

• higher core counts
• NUMA-aware scheduling and allocation
• container-heavy workloads
• mixed native and compatibility-domain concurrency

14. Modularity and Extensibility

14.1 Module boundaries

Subsystem boundaries are defined by:

• stable kernel-internal interfaces for core modules
• versioned IPC contracts for user-space services
• explicit compatibility-runtime interfaces

14.2 Plugin and module policy

VibeOS is extensible, but unrestricted in-kernel plugin models are not a design goal.

Preferred extension mechanisms:

• user-space services
• driver hosts
• compatibility runtime modules
• versioned user-space libraries

Kernel modules are permitted only under the placement policy defined earlier.

14.3 API and ABI versioning

Versioning rules:

• native kernel ABI is versioned
• service protocols are versioned independently
• compatibility runtimes track their own supported foreign ABI surface
• breaking changes require compatibility windows or migration tooling

15. Architecture Decisions Requiring Ongoing Validation

The following decisions are accepted for now but must be revalidated during implementation:

• whether specific storage or network fast paths remain out of kernel space
• whether the first native filesystem uses transactional metadata, journaling, or a hybrid integrity model
• how much Linux compatibility can be implemented through translation before requiring guest-backed execution for practicality
• whether selected Windows subsystem pieces need privileged acceleration

16. Open Questions / Missing Requirements

• What is the primary product target for the first usable release: developer workstation, headless server, embedded appliance, or research platform?
• Is a GUI stack required before the first public milestone, or is a command-line-only release acceptable?
• What security posture is mandatory for version 1: secure boot optional, recommended, or required?
• Is disk encryption in scope for the first storage milestone?
• What hardware profile defines the minimum supported machine: RAM floor, CPU feature floor, storage type, and network assumptions?
• Is realtime scheduling a firm requirement or only a future extensibility goal?
• What degree of POSIX conformance is required for Linux compatibility milestones?
• What classes of Windows software matter first: console tools, services, GUI applications, or specific enterprise workloads?
• Is any level of unmodified macOS application support actually required, or is Darwin-adjacent developer-tool portability sufficient?
• What legal and distribution constraints will govern compatibility work, especially for macOS-adjacent behavior and foreign binary testing?
• Is hypervisor support required in the base OS, or is lightweight guest execution allowed to depend on a later subsystem?
• What persistence and recovery guarantees are required for the first native filesystem milestone?
• Are hot-plug, suspend/resume, and power-management features required in the initial hardware support envelope?
• Which observability outputs are mandatory in CI: serial logs only, trace artifacts, crash dumps, or performance counters?
• What formal stability promise, if any, should be made for the native syscall ABI before version 1?

Boot System

Goals

• deterministic early boot path
• support for modern firmware on x86_64
• clear separation between bootloader responsibilities and kernel initialization
• smooth future transition to ARM64 platform bring-up

Boot model

Phase 0: firmware entry

Initial target firmware is UEFI. Legacy BIOS support is intentionally deferred to reduce complexity in early milestones.

Phase 1: project bootloader

The project will eventually provide a custom bootloader with the following responsibilities:

• load kernel image and core modules
• collect memory map and firmware tables
• establish framebuffer and console handoff data
• load initial ramdisk or boot package
• verify image signatures in secure boot configurations
• pass structured boot information to the kernel

During bring-up, a simpler standards-compliant boot path may be used temporarily if it does not compromise the from-scratch kernel requirement.

Recommended staging:

• early bring-up may target a well-defined external boot protocol to shorten time-to-first-kernel
• the long-term architecture still assumes a project-owned bootloader and boot information contract
• no existing kernel code is reused; only the boot handoff convention may be borrowed temporarily

Phase 2: kernel early init

• establish early serial and framebuffer logging
• parse boot information structure
• initialize physical memory manager
• create early page tables and higher-half kernel mapping
• enable interrupts after core descriptor tables are ready
• bring up bootstrap processor services

Phase 3: SMP and service handoff

• discover and start application processors
• initialize scheduler on all cores
• start init service and system service manager
• transition from early allocators to full memory subsystem

Early memory strategy

Boot allocators

• bump allocator for pre-paging early boot
• early page allocator for initial mappings
• handoff to full physical frame allocator once memory regions are classified

Address space model

• higher-half kernel mapping
• direct physical map for kernel internal memory operations
• per-process user address spaces with guarded kernel/user split

Boot data contract

The bootloader passes a versioned boot information block containing:

• memory map
• CPU and topology data
• ACPI or equivalent firmware tables
• framebuffer information
• boot medium metadata
• init package descriptors
• security and measured boot state

Risks and mitigation

• firmware diversity risk is mitigated by targeting UEFI first
• early memory corruption risk is reduced through strict phase separation
• boot ABI drift is controlled through versioned handoff structures

Current implementation snapshot

• bootloader stub exposes boot-info validation and memory summary helpers.
• boot-info contract checks now reject zero-length memory regions and invalid base contracts before kernel bring-up.
• kernel bootstrap initializes security-audit state during early core initialization.
• bootloader helpers now expose region-type counters and overlap detection for memory-map sanity checks.
• sanitized boot-info builder now normalizes memory maps (supported-type filtering, base-order sort, adjacent-merge by type) before kernel handoff.
• boot contract now provides max physical address helper to support early direct-map sizing decisions.
• boot handoff metadata helpers now cover firmware table pointers (ACPI/SMBIOS), initrd boundaries, and framebuffer geometry with strict validation.
• boot validation now enforces memory-map placement rules for firmware pointers, initrd ranges, and framebuffer regions to prevent invalid handoff layouts.
• bootloader can now extract firmware tags into handoff fields/flags (secure boot, measured boot) and produce a PE32+ load plan for UEFI-style kernel image mapping.

Kernel Design

Design intent, written before the code. What is actually built, and how, is in core/ and implementation_progress/kernel_core.md.

Kernel scope

The kernel core is intentionally small and responsible only for primitives that are unsafe or inefficient to place in user space.

Core responsibilities

• interrupt and exception handling
• low-level memory management
• scheduling and dispatch
• process and thread lifecycle primitives
• inter-process communication primitives
• synchronization objects
• timekeeping and timers
• capability-aware object management
• architecture and platform abstraction

Object model

Every kernel-visible resource is represented as a typed object:

• process
• thread
• address space
• channel
• shared memory object
• event
• timer
• device endpoint
• job or resource domain

Objects are referenced through handles. Handles carry rights masks and can be transferred in controlled ways through IPC.

Current runtime prototype updates:

• handle tables support configurable per-table quota limits.
• handle allocation failure counters are tracked for observability.
• object-type counters are available for process/thread handle accounting.
• handle lifecycle hooks are available for alloc/close/revoke event instrumentation and cleanup orchestration.

Process model

Process

A process owns:

• one address space
• one handle table
• resource accounting state
• security token and capability set
• one or more threads

Thread

A thread owns:

• register state
• scheduling attributes
• signal or exception delivery state
• thread-local storage metadata

IPC model

IPC is central to the system design.

See also: docs/ipc.md for the dedicated transport and contract strategy.

Requirements

• low overhead for local RPC-style service calls
• secure handle passing
• async messaging for service-oriented architecture
• support for compatibility runtimes that need brokering

Mechanisms

• message channels with bounded queues
• shared-memory regions for bulk data
• event signaling and wait sets
• optional zero-copy path for large transfers where mappings permit

Kernel module policy

Kernel modules are permitted only when they satisfy at least one of these conditions:

• required during early boot
• latency-sensitive enough to justify privileged execution
• too tightly coupled to interrupt-time hardware handling

All other subsystems should prefer user-space services.

Failure containment

• drivers and filesystems should restart independently when hosted out of kernel
• kernel panics should preserve diagnosable crash data
• watchdog supervision should detect failed core services

Observability

The kernel should expose:

• structured tracepoints
• per-CPU scheduling statistics
• memory and IPC counters
• fault reporting interfaces
• boot and runtime diagnostics suitable for automated testing

Current runtime prototype status

• interrupt controller runtime now supports IRQ masking/unmasking and global enable/disable gates.
• timer runtime includes tick-to-time conversion helpers, deadline arming/expiry checks, and IRQ-backend binding semantics.
• process security model includes token capabilities, security labels, and policy-driven interaction checks.

Memory Management

Design intent, written before the code. What is actually built, and how, is in mm/ and implementation_progress/memory_manager.md.

Goals

• strong isolation between protection domains
• predictable page fault and mapping behavior
• scalable memory allocation on multicore systems
• support for compatibility runtimes with different memory semantics

Physical memory management

Early phase

• firmware-provided memory map ingestion
• boot-time region classification
• early frame allocator for bootstrap use

Runtime phase

• buddy allocator or segmented frame allocator for general page allocation
• separate pools for DMA-capable memory when required
• accounting by zone and future NUMA node

Virtual memory model

Kernel space

• higher-half kernel mapping
• direct map for physical memory access
• guard pages around critical regions

User space

• per-process address spaces
• demand paging support
• copy-on-write support for process creation and memory sharing
• mapped objects for files, anonymous memory, and shared memory

Memory objects

All mappings are backed by explicit memory objects:

• anonymous memory object
• file-backed memory object
• shared memory object
• device memory object

This simplifies accounting, rights management, and compatibility runtime integration.

Kernel heap

The kernel heap should be layered:

• early bump allocator
• slab or object caches for fixed-size kernel objects
• general-purpose heap for variable allocations

The design should favor cache locality and deterministic behavior for hot object types.

Userland allocation support

User processes receive kernel primitives for:

• reserving virtual address space
• committing and decommitting pages
• protection changes
• shared memory mapping
• memory-mapped file creation

These primitives are sufficient to emulate Linux mmap, Windows virtual memory APIs, and selected Darwin allocation behavior in user-space compatibility layers.

Hardening

• W^X enforcement where compatible
• ASLR for kernel and user spaces as platform maturity allows
• stack guards
• guarded pools for sensitive allocations
• optional page poisoning and quarantine in debug builds

Future enhancements

• transparent huge pages where beneficial
• compressed memory experiments
• NUMA-aware placement
• confidential-computing-friendly abstractions

Current implementation snapshot

• VM runtime now supports partial unmap (unmap_range) with map splitting semantics.
• VM observability helpers expose total map count and total mapped bytes.
• read-only clone support is available (clone_readonly) to model early copy-on-write style address-space duplication.
• on x86-64 this is no longer a model: fork is real copy-on-write, with the writable bit cleared, PTE_COW set and a frame refcount table deciding when a page can be freed. The three places that have to agree about it - the fault handler accepting kernel-mode writes, hw_user_range_ok treating a COW page as writable, and a second fork preserving the bit - are described in docs/process_semantics.md.
• VM integrity helpers now include address-space validation (validate) and adjacent-map compaction (compact) for safer and denser map layouts.
• PMM bootstrap can now select the best usable region from boot memory maps while avoiding initrd overlap, instead of assuming a fixed first-region layout.

Scheduler

Design intent, written before the code. What is actually built, and how, is in sched/ and implementation_progress/sched.md.

Goals

• low wake-up latency
• fairness under mixed interactive and background workloads
• multicore scalability
• affinity and topology awareness
• support for real-time and near-real-time classes in later phases

Scheduling model

VibeOS uses a preemptive priority-based scheduler with fair scheduling within priority bands.

Thread classes

• realtime reserved for strict bounded-latency system tasks in later phases
• interactive for UI and latency-sensitive applications
• normal for standard user workloads
• background for maintenance and batch work

Core design

Per-CPU run queues

Each CPU maintains a local run queue to reduce lock contention and cache disruption.

Load balancing

Periodic and event-driven balancing migrates threads across CPUs based on:

• CPU utilization
• thread affinity
• cache locality hints
• NUMA domain awareness in future phases

Priority handling

• dynamic boosts for wake-up responsiveness
• starvation prevention through aging
• priority ceilings for specific kernel-mediated synchronization paths when necessary

Timeslice policy

• interactive threads receive shorter slices with stronger latency preference
• throughput-oriented threads receive longer slices
• kernel workers should avoid monopolizing CPU time by default

Multicore strategy

• minimal global scheduler state
• per-CPU timer events where possible
• explicit handling for idle CPUs and wake-up targets
• future support for heterogeneous core topologies

Roadmap

Early implementation

• fixed priority bands
• round-robin within queues
• basic SMP balancing

Mid-stage evolution

• fair scheduling weights
• better I/O wake heuristics
• CPU topology awareness

Advanced stage

• real-time scheduling class
• deadline scheduling for selected workloads
• energy-aware placement for mobile-class platforms

Current runtime prototype status

• class-based default timeslice selection is implemented (background=8, normal=4, interactive=2, realtime=1).
• enqueue paths normalize zero-timeslice threads to class defaults.
• per-CPU and aggregate scheduler counters remain available through runtime telemetry helpers and syscall observability paths.
• runqueue aging helpers are available (age_cpu, age_all) to apply bounded timeslice boosts and reduce starvation risk.
• the x86-64 runtime runs preemptively on four cores, and the boot gate asserts all four are online rather than assuming it. Two cores ending up on one task and a lost TLS base both reproduced at roughly one boot in three, which is why scheduler changes here are checked with scripts/dev/repeat-boot.sh and not with a single green run.

System Call Interface

Design intent, written before the code. What is actually built, and how, is in abi/ and implementation_progress/system_call_interface.md.

Design goals

• compact, stable, orthogonal kernel API
• low overhead on hot paths
• minimal policy in the syscall surface
• compatibility enablement without kernel ABI explosion

Design philosophy

VibeOS does not expose Linux, Win32, or Darwin syscalls directly as the native kernel ABI. Instead, it provides a smaller native syscall set centered on:

• process and thread management
• virtual memory operations
• IPC and synchronization
• time and timers
• object and handle management
• device and I/O primitives
• security token and capability operations

Compatibility layers translate foreign application behavior into this native model.

Interface style

• handle-based operations rather than global integer descriptors where possible
• explicit rights checks at object boundaries
• structured error codes with deterministic semantics
• capability negotiation for optional features

ABI v0 argument mapping (frozen baseline)

vibeos_syscall_frame_t keeps the fixed layout (id, arg0, arg1, arg2, result).

Argument semantics for current syscall groups:

| PROC_AUDIT_COUNT_ACTION | action enum | reserved (0) | caller pid (0 = global, non-zero = caller-scoped) | | PROC_AUDIT_COUNT_SUCCESS | success value (0/1) | reserved (0) | caller pid (0 = global, non-zero = caller-scoped) | | PROC_AUDIT_SUMMARY | reserved (0) | reserved (0) | caller pid (0 = global, non-zero = caller-scoped) | | PROCESS_TOKEN_GET | target pid | reserved (0) | caller pid (0 = kernel; otherwise self or directly related process) | | PROCESS_TOKEN_SET | target pid | capability mask | caller pid (0 = kernel; otherwise self only) | | POLICY_CAPABILITY_GET | policy target enum (1 fs-open, 2 net-bind, 3 process-spawn, 4 process-interact override) | reserved (0) | caller pid (advisory, unrestricted read) | | POLICY_CAPABILITY_SET | policy target enum (1 fs-open, 2 net-bind, 3 process-spawn, 4 process-interact override) | required capability bit (0..31) | caller pid (0 required) | | POLICY_SUMMARY_GET | reserved (0) | reserved (0) | caller pid (advisory, unrestricted read) | | SEC_AUDIT_COUNT | reserved (0) | reserved (0) | caller pid (0 = global, non-zero = caller-scoped) | | SEC_AUDIT_GET | event index (caller-local if arg2 != 0) | reserved (0) | caller pid (0 = global, non-zero = caller-scoped) | | SEC_AUDIT_COUNT_ACTION | security-audit action enum | reserved (0) | caller pid (0 = global, non-zero = caller-scoped) | | SEC_AUDIT_COUNT_SUCCESS | success value (0/1) | reserved (0) | caller pid (0 = global, non-zero = caller-scoped) | | SEC_AUDIT_SUMMARY | reserved (0) | reserved (0) | caller pid (0 = global, non-zero = caller-scoped) | | SEC_AUDIT_RESET | reserved (0) | reserved (0) | caller pid (0 required) | | PROCESS_SECURITY_LABEL_GET | target pid | reserved (0) | caller pid (0 = kernel; otherwise self or directly related process) | | PROCESS_SECURITY_LABEL_SET | target pid | security label | caller pid (0 = kernel; otherwise self only) | | PROCESS_INTERACT_CHECK | target pid | reserved (0) | caller pid (!= 0, no kernel shortcut) |

PROC_AUDIT_GET returns:

• result = event.seq (positive on success)
• arg0 = event.action
• arg1 = event.success
• arg2 = event.revoked_count

PROC_AUDIT_POLICY_GET returns:

• result = current retention policy enum value.

PROC_AUDIT_DROPPED returns:

• result = cumulative number of dropped audit events (only when retention mode is DROP_NEWEST).

WAITSET_STATS_GET returns:

• arg0 = added
• arg1 = removed
• arg2 = wait_calls
• result = wait_timeouts

WAITSET_STATS_EXT_GET returns:

• arg0 = wait_wakes
• arg1 = ownership_denials
• arg2 = owner_pid
• result = current waitset event count

WAITSET_WAKE_POLICY_GET returns:

• result = current wake policy enum (0 FIFO, 1 REVERSE).

WAITSET_OWNER_GET returns:

• result = waitset owner pid
• arg0 = ownership enforcement flag
• arg1 = current waitset event count

WAITSET_SNAPSHOT_GET returns:

• result = waitset owner pid
• arg0 = ownership enforcement flag
• arg1 = wake policy enum (0 FIFO, 1 REVERSE)
• arg2 = current waitset event count

PROCESS_STATE_SUMMARY_GET returns:

• arg0 = count in NEW
• arg1 = count in RUNNING
• arg2 = count in BLOCKED
• result = count in TERMINATED

THREAD_STATE_SUMMARY_GET returns:

• arg0 = count in NEW
• arg1 = count in RUNNABLE
• arg2 = count in BLOCKED
• result = count in EXITED

PROC_TRANSITION_COUNTERS_GET returns:

• arg0 = process-state transition count
• arg1 = thread-state transition count
• arg2 = process-termination count
• result = thread-exit count

SCHED_COUNTER_SUMMARY_GET returns:

• arg0 = total preemptions
• arg1 = total wait timeouts
• arg2 = total wait wakes
• result = total runnable threads

PROC_AUDIT_SUMMARY returns:

• arg0 = total visible audit events
• arg1 = visible successful events
• arg2 = visible failed events
• result = 0 on success

PROCESS_TOKEN_GET returns:

• arg0 = token uid
• arg1 = token gid
• arg2 = token capability mask
• result = 0 on success

POLICY_CAPABILITY_GET returns:

• result = required capability bit for the requested target

POLICY_SUMMARY_GET returns:

• arg0 = required capability bit for fs-open policy checks
• arg1 = required capability bit for net-bind policy checks
• arg2 = required capability bit for process-spawn policy checks
• result = required capability bit for process-interact override checks

SEC_AUDIT_GET returns:

• result = security audit sequence (caller-local redacted sequence when caller_pid != 0)
• arg0 = action enum (1 process-spawn, 2 process-token-set, 3 policy-capability-set)
• arg1 = success flag (0/1)
• arg2 = target pid (0 when not process-targeted)

SEC_AUDIT_SUMMARY returns:

• arg0 = total visible security audit events
• arg1 = visible successful events
• arg2 = visible failed events
• result = 0 on success

PROCESS_SECURITY_LABEL_GET returns:

• result = target process security label

PROCESS_INTERACT_CHECK returns:

• result = 1 if caller is currently allowed to interact with target process according to label and override capability policy, 0 if denied

Access policy:

• caller_pid == 0: full global audit stream.
• caller_pid != 0: only events where event.owner_pid == caller_pid; result is redacted to caller-local sequence (index + 1).
• PROC_AUDIT_POLICY_SET, PROC_AUDIT_POLICY_GET, PROC_AUDIT_DROPPED are kernel-only (caller_pid == 0) in ABI v0.
• PROCESS_STATE_GET is kernel-only, self-introspection, or directly related process introspection (parent or child).
• PROCESS_STATE_SET and PROCESS_TERMINATE are kernel-only or self-targeted.
• PROCESS_TOKEN_GET is kernel-only, self-introspection, or directly related process introspection (parent or child).
• PROCESS_TOKEN_SET is kernel-only or self-targeted.
• PROCESS_SECURITY_LABEL_GET is kernel-only, self-introspection, or directly related process introspection (parent or child).
• PROCESS_SECURITY_LABEL_SET is kernel-only or self-targeted.
• SEC_AUDIT_COUNT, SEC_AUDIT_GET, SEC_AUDIT_COUNT_ACTION, and SEC_AUDIT_SUMMARY are kernel-global for caller_pid == 0, caller-scoped otherwise.
• THREAD_STATE_GET, THREAD_STATE_SET, THREAD_EXIT are kernel-only or thread-owner scoped.
• WAITSET_STATS_GET and WAITSET_STATS_EXT_GET are kernel-only or waitset-owner scoped.
• WAITSET_WAKE_POLICY_SET, WAITSET_WAKE_POLICY_GET, and WAITSET_STATS_RESET are kernel-only or waitset-owner scoped.
• WAITSET_OWNER_GET is kernel-only or waitset-owner scoped.
• WAITSET_SNAPSHOT_GET is kernel-only or waitset-owner scoped.
• PROC_TRANSITION_COUNTERS_RESET is kernel-only.
• SCHED_COUNTERS_RESET is kernel-only.
• POLICY_CAPABILITY_SET is kernel-only.
• SEC_AUDIT_RESET is kernel-only.

Implementation helpers for ABI v0 are centralized in include/vibeos/syscall_abi.h and should be preferred over direct field writes in kernel tests and user-space glue.

ABI stability strategy

• native ABI is versioned
• deprecated calls remain shimmed for defined support windows
• compatibility runtimes own most foreign ABI churn

Performance considerations

• vDSO-style user mappings for clock and other safe queries in future phases
• batched IPC and handle transfer operations
• minimal-copy I/O design for large transfers

Early syscall groups

• process
• thread
• address_space
• memory_object
• channel
• event
• timer
• device
• debug and trace

The Linux ABI as implemented on metal

The native ABI above is the design. Separately, and in parallel, the x86-64 port serves the Linux system-call ABI directly to ring 3, because that is what lets real programs run before a native userland exists. Entry is the syscall instruction (with int 0x80 kept as a bring-up path); both reach one dispatcher in kernel/arch/x86_64/arch_hw.c.

Two rules govern what goes in it:

• A syscall either does the thing or returns the error Linux returns. Reporting a success that did not happen makes the program fail later, somewhere unrelated, with nothing pointing back to the kernel. rseq and getrandom return -ENOSYS for exactly this reason: both have mandatory fallbacks, and a fabricated answer is worse than a refusal - particularly for the syscall a program uses to get key material.
• Unimplemented numbers are named in the serial log, so a missing one is visible the first time it is reached rather than inferred from a crash.

The list below is the switch in vibeos_x86_64_linux_syscall, not an aspiration. Anything not in it is refused with -ENOSYS and named in the log.

Deliberately refused with -ENOSYS: rseq, getrandom, sendfile, and clone when CLONE_VM or CLONE_THREAD is set. Each has a documented caller fallback; a fabricated success would move the failure somewhere unrelated.

Notable semantics:

• arch_prctl(ARCH_SET_FS) writes MSR_FS_BASE and the value is per task, reloaded on every context switch - thread-local storage is the first thing a C runtime touches, and leaving one task's base loaded for another would let a program read someone else's thread state. A base outside user memory is refused before the write, since a non-canonical value faults in ring 0.
• mprotect and munmap change the real page-table entries and flush the TLB. MAP_FIXED and file-backed mmap are refused rather than ignored.
• ioctl returns -ENOTTY. There is no terminal device here, and that is the answer a libc uses to decide stdout should be block buffered. fstat on a standard descriptor agrees with it: a character device that is not a terminal.
• fork shares pages instead of copying them. Every writable user leaf becomes read-only and copy-on-write in both address spaces, the frame's reference count goes up, and the first write from either side faults and duplicates it. Three details make it work rather than nearly work: the fault handler must accept a fault raised in ring 0, because the kernel writes user buffers with CR0.WP set and read() filling a freshly forked buffer is exactly such a write; hw_user_range_ok must treat a copy-on-write page as writable, or a syscall rejects the buffer before the fault can fix it; and a second fork must recognise an already-COW page rather than filing it under "read-only, so it never needs copying", which would leave it permanently unwritable.
• Signals are real. rt_sigaction and rt_sigprocmask install dispositions and masks that are honoured; a raise sets a pending bit and wakes the task if it was blocked; delivery happens on the way back to user space, where the process's own stack is available. The frame is built below the 128-byte red zone, 16-byte aligned with room for a return address, and the return address is the C library's SA_RESTORER trampoline - a handler installed without one cannot return anywhere, so the signal takes its default action instead. rt_sigreturn restores the saved frame but forces cs, ss and rflags back to safe values, because that frame lives in memory the program can write and nothing read out of it may decide privilege. A magic word in the frame is checked for the same reason.
• A Linux sigset_t numbers its bits from zero: bit 0 is signal 1. This kernel numbers them by signal, and converts only in hw_sigset_from_user / hw_sigset_to_user. Getting it wrong shifts every mask by one.
• SIGKILL and SIGSTOP can be neither caught nor blocked: rt_sigaction returns EINVAL for them and rt_sigprocmask accepts the request and drops the two bits, as Linux does.
• A wait status from wait4 is not an exit code. The exit code sits in the high byte and a killing signal in the low seven bits; 128 + sig is what a shell prints, not what the kernel stores.
• pipe2 allocates one buffer and two descriptors, read end first; O_CLOEXEC is accepted and ignored, since there is no close-on-exec list. dup2 onto 0, 1 or 2 records a standard-descriptor redirection, which is how a shell attaches a pipe to a program that knows nothing about it. dup is dup2 onto the lowest free descriptor. Descriptors are inherited across fork with the pipe's reader and writer counts incremented, and released on exit - a pipe stays alive until both ends are gone, so a reader can still drain data after the last writer closed. Writing to a pipe with no readers raises SIGPIPE and returns EPIPE.
• clone is what a C library actually calls for fork. Flags that mean a thread (CLONE_VM, CLONE_THREAD) return -ENOSYS; anything else forks. tkill and tgkill reduce to kill, since there is one thread per process.
• getcwd returns / and readlinkat answers only /proc/self/exe, from the path execve was given. Both say what is true rather than inventing a path a program would then fail to open.
• openat accepts only AT_FDCWD; newfstatat additionally handles an empty path with AT_EMPTY_PATH, and distinguishes a directory from a file by trying to list it, because ls behaves differently for each.
• setuid/setgid succeed for 0 and return EPERM otherwise. There is one identity here and it is root.
• time and clock_gettime are derived from the timer tick, not from a real-time clock.

How much of this a gate defends

The boot gate (scripts/qemu-cli-smoke-linux.py) drives these paths through real programs rather than a test written to agree with the kernel. It fails on signal_delivery_broken if a program built by musl-gcc against a real libc (tests/linux/musl_signal.c, staged as SIGNAL.ELF) does not print SIG_OK after exercising handlers, masking, ignoring and default actions - the trampoline a handler returns through comes from that libc, not from a test that agrees with the kernel; on pipeline_did_not_complete if ls /EFI/BOOT | wc -l in BusyBox's shell does not get as far as the PIPE_OK that follows it; and on busybox_file_operations_failed if openat, fstat, read or getdents64 regress, since those are BusyBox's own error messages.

Copy-on-write is reported, not asserted: the kernel prints [MM] COW_STATS shared=... copied=... at the end of the self-test - 1221 and 24 on the boot this was written against - but no invariant checks the numbers. What the gate defends is that forking and exec'ing programs keep working.

Compatibility note

Linux compatibility may expose a Linux-like user ABI inside its subsystem, but translation happens above the native kernel API unless a measured exception is justified.

IPC Design

Why IPC is central

VibeOS depends on IPC not only for ordinary application communication but also for core system structure. Drivers, filesystems, compatibility layers, policy services, and service supervision all rely on IPC as the primary contract surface between protection domains.

Goals

• low latency for request-response service calls
• secure transfer of handles and shared memory references
• bounded memory usage under load
• clean support for async and sync communication
• debuggable and versionable service contracts

Primitive set

Channels

Bidirectional or paired message channels are the default control-path primitive.

Properties:

• message boundaries preserved
• kernel-validated handle passing
• optional reply capability for RPC-style interactions
• cancellation-aware waiting

Shared memory

Shared memory complements channels for bulk transfer.

Use cases:

• filesystem I/O buffers
• graphics surfaces
• network packet rings
• compatibility runtime staging buffers

Events and wait sets

Events allow low-cost signaling. Wait sets allow a service to block on multiple channels, timers, and events without ad hoc polling loops.

Current runtime notes:

• wait sets support FIFO, REVERSE, and ROUND_ROBIN wake policy modes.
• round-robin wake policy keeps a rotating cursor to improve fairness under sustained multi-event contention.

Contract model

• every long-lived system service should publish a versioned IPC contract
• contracts should be documented separately from implementation code
• incompatible protocol changes require explicit version negotiation or side-by-side compatibility
• security-sensitive services should prefer brokered narrow interfaces over generic escape hatches

Performance strategy

• fast path for small fixed-size messages
• shared-memory-assisted transfer for large payloads
• per-CPU delivery queues where appropriate
• backpressure on overloaded receivers
• tracing hooks to measure queue depth, latency, and copy counts

Security strategy

• sender identity and rights checked at receive boundary
• no ambient authority through channel inheritance by default
• handle transfer allowed only with explicit rights masks
• broker services mediate privileged operations for sandboxed runtimes

Early implementation scope

• local same-machine IPC only
• synchronous request-response and asynchronous notification
• handle passing
• wait sets and timeout support

Distributed IPC or transparent remote IPC is explicitly out of scope for early phases.

Filesystem

Design intent, written before the code. What is actually built, and how, is in io/ and implementation_progress/filesystem_layer.md.

The production-oriented namespace, directory tree, mount policy, compatibility mapping and staged migration are specified in filesystem-design/. That design does not change the current boot layout or mark the storage layer complete; it deliberately separates the target hierarchy from the FAT-root bring-up environment.

Goals

• modern reliability and integrity model
• efficient metadata operations
• support for snapshots and crash recovery in future phases
• clean separation between VFS and concrete filesystem implementations

Architecture

Virtual filesystem layer

The VFS provides:

• path resolution
• mount management
• file handle abstraction
• permission and policy hooks
• filesystem-neutral caching interfaces

Filesystem hosting model

The preferred architecture is:

• VFS and page-cache integration in privileged space or tightly controlled kernel services
• concrete filesystems hosted as isolated services when practical

This allows experimentation without placing all on-disk parsing logic in the kernel.

Native filesystem direction

The native filesystem, tentatively named AuroraFS, should target:

• copy-on-write metadata updates
• checksummed metadata
• optional checksummed data
• extent-based allocation
• snapshot support
• efficient small-file performance

Compatibility strategy

Where this now stands

Five filesystems are implemented, each behind the same vibeos_fs_ops_t, so nothing above the mount layer names any of them:

MBR and GPT partition tables are parsed. ext4 and APFS remain unimplemented; ext2 was built first because it is the same shape of problem with a fraction of the surface, and it is what proved the interface could hold a second filesystem at all.

Full write support for foreign filesystems stays gated behind test coverage, and the bar here is a sabotage case per guard: removing any single check must turn a named test red.

Caching model

• unified page cache where feasible
• write-back with journalling or transaction semantics for supported filesystems. The block cache is write-back today and its flush reaches the device's own cache, which is what makes a barrier real rather than nominal.
• explicit invalidation contracts for compatibility runtimes and VM-backed file access

Security considerations

• namespace-aware mount permissions
• immutable and verified system partitions in hardened modes
• per-filesystem policy hooks
• brokered access for sandboxed applications

Current implementation snapshot

• VFS runtime supports mount, unmount, open, close, and secure-open policy checks.
• mount observability is available through active-mount counters.
• unmounted filesystems are rejected by open paths, improving lifecycle correctness.
• the kernel path is block device -> block cache -> filesystem driver -> mount, with the syscall layer naming none of the five drivers.
• a write-ahead journal recovers at attach and is swept against power loss, but no driver stages its metadata through it yet: the mechanism is verified, the volume is not. See docs/implementation_progress/filesystem_layer.md.

Networking Stack

Goals

• modern TCP/IP capability
• modular protocol evolution
• low latency and good multicore throughput
• clean socket semantics for native and compatibility applications

Stack structure

Kernel responsibilities

• packet ingress or egress primitives
• network buffer management fast path
• interface event delivery
• low-level filtering hooks

User-space or service responsibilities

• control plane
• configuration management
• policy enforcement
• advanced routing
• firewall management
• network namespaces or tenant policies in future phases

Protocol roadmap

Early support

• Ethernet
• IPv4
• IPv6
• ARP or neighbor discovery
• ICMP
• UDP
• TCP

Later support

• TLS acceleration hooks
• QUIC-friendly interfaces
• virtual switching
• container networking

Socket model

The native socket layer should be expressive enough to support:

• POSIX-like compatibility
• Windows socket compatibility through subsystem translation
• event-driven high-performance servers

Current runtime prototype status

• vibeos_socket_create, vibeos_socket_bind, vibeos_socket_send, and vibeos_socket_close are available in the host test runtime.
• vibeos_socket_bind_secure enforces policy-gated bind authorization using security-token capabilities (net_bind_required_capability_bit).
• Policy capability updates are now runtime-configurable through syscall control paths (POLICY_CAPABILITY_SET for kernel callers).
• receive-side simulation (vibeos_socket_receive) and aggregate runtime socket statistics are available for observability tests.
• runtime bind path rejects port collisions across active sockets.

Performance direction

• per-CPU queues
• RSS-friendly receive flow steering
• zero-copy or reduced-copy buffers where safe
• future support for polling rings or submission queues if justified

Security

• namespace-aware network access
• brokered raw socket access
• firewall and policy hooks
• sandbox integration for compatibility runtimes

Device Drivers

Design intent, written before the code. What is actually built, and how, is in devices/ and implementation_progress/driver_framework.md.

Driver model goals

• isolate faults from the kernel whenever practical
• standardize device discovery and lifecycle
• support high-performance paths for networking and storage
• keep hardware-specific logic out of generic subsystems

Driver architecture

Driver manager

A dedicated driver manager service is responsible for:

• device enumeration
• driver matching and loading
• lifecycle supervision
• permission brokerage for driver-host processes

Driver hosts

Preferred model:

• user-space driver hosts for most devices
• specialized privileged drivers only for boot-critical or ultra-low-latency hardware paths

Device classes

• storage
• network
• display
• input
• USB and bus controllers
• audio
• virtual devices

Hardware abstraction

The kernel exposes safe primitives for:

• interrupt delivery
• MMIO mapping
• DMA setup through mediated interfaces
• device memory objects
• event notification

This keeps the kernel in control of trust boundaries even when drivers live in user space.

Initial priorities

• APIC or interrupt controller support
• timer devices
• serial console
• framebuffer or simple display output
• AHCI or NVMe storage
• PCIe enumeration
• basic network interface

Reliability model

• supervised restart for user-space drivers
• versioned driver-service protocols
• structured fault and telemetry reporting

Current implementation snapshot

• driver framework now enforces unique driver registration IDs.
• runtime supports driver unregister and driver-state queries for service health checks.
• driver-host probe path remains service-state aware and integrates with device discovery counters.

Graphics

This file records the existing framebuffer desktop and its current verification limits. The target desktop/window-system architecture, visual language, UX requirements and implementation stages are specified in ui-design/. The target is not yet implemented merely because the current kernel desktop draws a terminal window.

What exists on screen, how it gets there, and - the part worth stating plainly

• how little of it any gate would catch if it broke.

The path

The bootloader asks UEFI's Graphics Output Protocol for a linear framebuffer and passes its address, dimensions, pitch and pixel format to the kernel in the boot info structure. Nothing later re-negotiates the mode: the resolution the firmware chose is the resolution VibeOS runs at, for the whole boot.

Everything above that is software drawing into that one buffer. There is no GPU driver, no acceleration and no second buffer. A pixel is written by computing its address from the pitch and storing to it.

The desktop is composed in the order a painter would: background, then window frames, then their contents, then the pointer last so it is never covered by what was drawn after it. Redraw is by region rather than whole-screen where the region is known, because at these resolutions a full repaint per mouse move is visible as a smear.

Input

Two PS/2 devices, both on the legacy controller:

• Keyboard, IRQ1. Scan codes are translated in the handler and pushed into a ring buffer that read() drains. The ring holds 2048 bytes; it held 512 until a paste-sized burst of input during a BusyBox pipeline overran it and dropped characters, which looked like the shell mis-parsing its input rather than like a full buffer.
• Mouse, IRQ12. Three-byte packets carrying button state and signed X/Y deltas. Y is inverted relative to screen coordinates, and the deltas are sign-extended out of a flags byte rather than being signed on the wire, which is the detail that turns "the pointer only moves down and right" into a working pointer.

The on-screen terminal

The desktop hosts a terminal window that shares the shell with the serial console rather than running a second one. It is a view onto the same session: the same ring buffer, the same process. A character typed on the PS/2 keyboard and a character arriving on the serial line are the same event by the time anything above the driver sees them.

What is verified, and what is not

This is the honest part. The GUI is not gated.

The boot smoke test asserts state rather than markers - a DHCP lease, four cores online, a TCP round trip, a Linux binary that ran - and it can assert that the graphics stack initialised and that the desktop reports itself ready, because those are serial-visible. It cannot assert that anything appeared. A framebuffer full of black pixels and a correctly drawn desktop produce the same serial output.

So the pixels are checked by hand, with scripts/dev/screenshot.py, which boots under QEMU and captures the framebuffer to a PPM file. Nothing runs it automatically. A change that draws the desktop entirely off-screen, or in the wrong pixel format, or not at all, would pass CI.

That is a deliberate gap and not an oversight - a pixel-comparison gate is brittle in a way that costs more than it catches, this early - but it means "the GUI works" is a claim resting on somebody having looked recently, and it should be read that way.

Limits worth knowing before extending this

• One mode, chosen by firmware. No mode setting, so no resolution change at runtime and no response to a monitor being swapped.
• One buffer. Drawing is visible as it happens. Anything large enough to be slow will be seen being drawn.
• No clipping discipline in depth. Windows are drawn in order; there is no general clip-rectangle stack, so a new kind of overlapping element needs its own thinking rather than inheriting one.
• Pixel format is read from boot info, not assumed. Code that hardcodes BGRA will work on QEMU and fail on hardware that reports RGBA.

Process semantics

How a process is created, replaced, signalled and reaped here, and the places where matching Linux turned out to mean something other than what the code first assumed.

Two user windows

VibeOS's own programs link at 0x8000000000. Linux programs link at 0x400000, which is inside the kernel's identity map - so the physical range behind the low window is reserved out of the allocator, and nothing of the kernel's can live where a process would shadow it. Which addresses a process may use is decided in one place, hw_user_addr_ok.

This is not a stylistic split. An unmodified static Linux binary has its load address baked in, and refusing it would mean refusing the whole point.

Starting a program

execve builds a System V startup stack: argc, the argv pointers, the envp pointers, then the auxiliary vector. A C runtime reads more of that vector than its name suggests it must:

• AT_PHDR, AT_PHNUM, AT_PHENT - glibc walks its own program headers.
• AT_ENTRY, AT_BASE.
• AT_RANDOM - sixteen bytes used to seed the stack canary. When it was absent, the pointer was null and the process dereferenced it during startup, before main. getrandom is deliberately still ENOSYS; that is a separate promise and this one had to be kept first.

The entry rsp must be 16-byte aligned, which is why _start cannot be C.

argv[0] is not the path. BusyBox is twenty commands in one binary and decides which it is by the name it was invoked under; FAT stores names upper case with an extension. The shell supplies the name, the path only opens the file.

/proc/self/exe is stored absolute even when the caller used a relative path. glibc does not merely prefer that - it asserts on it during startup and aborts.

fork

Copy-on-write. The page tables are shared with the writable bit cleared and PTE_COW (bit 9) set, and a frame refcount table says how many address spaces hold each frame.

Three places have to agree, and they do not look related:

• The fault handler must accept kernel-mode writes. The kernel writes user buffers with CR0.WP set, so a read() into a COW page faults from ring 0.
• hw_user_range_ok must treat a COW page as writable. It is writable; it just needs a copy first. Rejecting it makes a valid buffer look invalid.
• A second fork must preserve the COW bit rather than treating the page as plain read-only, or the third process shares a page nobody will copy.

The refcount table is indexed from the region base. Indexing it from the end of the table instead freed pages that were still in use - a bug that presents as unrelated memory corruption much later.

Signals

Delivered on the return path to user space, never mid-syscall. The frame is built below the red zone, and return goes through the user library's own SA_RESTORER trampoline rather than anything the kernel supplies.

Linux sigset_t bits are numbered from zero: bit 0 is signal 1. This kernel numbers them by signal number. The conversion happens only at the boundary, in hw_sigset_from_user and hw_sigset_to_user. Doing it anywhere else means two conventions in the same code path and an off-by-one that only shows up for whichever signal happens to be tested last.

Exit and wait

A wait status is not an exit code. The exit code lives in the high byte and the signal number in the low seven bits. 128 + sig is what a shell prints, not what the kernel stores - copying the shell's arithmetic into the kernel produces a status that looks right in one test and is wrong everywhere else.

Descriptors are inherited across fork and released on exit, pipe ends included. Exit that did not release pipe ends left readers waiting on a writer that no longer existed, which is a hang rather than an error.

Pipes

pipe2, dup, dup2, inheritance across fork, and SIGPIPE for a write with no reader. The boot self-test runs ls /EFI/BOOT | wc -l in BusyBox's shell and the gate fails if the pipeline does not complete - a pipeline that deadlocks and a pipeline that returns the wrong number are both caught, because the count is asserted and not merely printed.

Scheduling and locks, where processes meet them

Spinlocks mask interrupts, so anything slow under one is slow with the timer off - and under emulation that is indistinguishable from a hang. execve is the long one: two megabytes loaded, hundreds of pages mapped, an address space torn down. It therefore takes g_exec_lock preemptibly, with interrupts left on, which is safe only because no interrupt handler ever takes that lock.

That choice has a consequence recorded in CLAUDE.md and not yet resolved: a lock whose holder can be preempted must not be waited on by a core that has interrupts masked, because such a core never reaches the scheduler and can never hand the holder a CPU to finish on.

What is verified

The boot gate asserts behaviour rather than log lines: an unmodified static Linux binary ran, BusyBox dispatched an applet and did file work, the interactive shell ran, signals were delivered, fork produced a child that was reaped with the status the parent expected.

Ctrl-C becoming a real SIGINT is implemented but not gated - it is checked by hand.

Security

Security model

VibeOS uses a layered security model combining isolation, rights-based access, system policy, and hardening.

Core principles

• least privilege by default
• small trusted computing base
• explicit privilege transitions
• defense in depth
• auditable security decisions

Trust domains

• kernel core
• privileged system services
• standard system services
• compatibility runtimes
• sandboxed applications
• guest or VM environments

Access control

Baseline mechanism

• handles with rights masks
• capability-aware object access
• service-mediated access to sensitive resources
• per-process security tokens (uid, gid, capability_mask) with token inheritance on process spawn

Policy layer

The system should support a mandatory policy engine for:

• filesystem access
• device access
• network permissions
• process interaction rules
• compatibility subsystem restrictions

This policy layer can evolve toward a MAC framework.

Current implementation status:

• policy checks implemented for filesystem open, network bind, and process spawn.
• policy required-capability bits are runtime-readable and kernel-mutable.
• process spawn authorization evaluates the calling process token (or kernel token in kernel context), not a fixed global mask.
• process entries expose security labels with inheritance on spawn and scoped mutation controls.
• process interaction checks support label-based allow rules with capability-based override.
• thread entries now keep a token snapshot inherited from their owner process, and token updates propagate to live threads.
• policy runtime now includes an enforceable MAC interaction gate (mac_enforced) layered on top of label and capability checks.

Sandboxing

Application sandboxes may restrict:

• filesystem view
• network access
• device classes
• IPC peers
• memory execution permissions

Compatibility runtimes should run inside restricted containers unless explicitly trusted.

Hardening

• kernel ASLR where supported
• W^X and executable mapping controls
• stack canaries and compiler hardening
• structured syscall validation
• guarded kernel memory regions
• control-flow protection where toolchains allow

Identity and authentication

Early phases should support local user and service identities with secure credential storage. Network and enterprise identity integration is explicitly deferred.

Secure boot and integrity

The design should permit:

• measured boot
• signed kernel and core service images
• verified system partitions
• runtime attestation experiments in later phases

Observability and audit

• auditable permission denials
• security event logging
• crash and tamper diagnostics
• trace correlation for compatibility subsystem behavior

Current implementation status:

• kernel security-audit ring buffer tracks privileged security-relevant operations.
• audited operations currently include process spawn authorization outcomes, process token updates, and policy capability mutations.
• non-kernel callers can only inspect their own security-audit events through caller-scoped syscall views.

Compatibility Strategy

Objective

VibeOS must support applications from Linux, Windows, and macOS without compromising kernel integrity or forcing the native kernel ABI to mimic every foreign operating system.

Strategy overview

The compatibility approach is layered:

• native VibeOS ABI for first-party software
• subsystem runtimes for translated execution
• containers and personalities for compatible environments
• lightweight virtualization for workloads requiring stronger fidelity

Support tiers

Compatibility promises are intentionally tiered:

• Tier 0: native VibeOS applications using the native ABI
• Tier 1: Linux command-line and service workloads through translation
• Tier 2: Linux containerized workloads with stronger environment fidelity
• Tier 3: Windows console and service-style workloads through subsystem services
• Tier 4: selected Windows GUI workloads once graphics and input stacks mature
• Tier 5: selective Darwin-oriented and macOS-adjacent runtime experiments, not broad parity

Linux compatibility

Priority

Linux is the first compatibility target because:

• it unlocks developer tooling quickly
• POSIX ecosystems are large and well documented
• container-oriented workflows align well with the system design

Proposed approach

• Linux personality runtime in user space
• syscall translation to native kernel objects and services
• ELF loader support
• POSIX-compatible libc strategy in the compatibility environment
• container and namespace model for isolating Linux workloads

What exists today

Ahead of the user-space personality, the x86-64 port serves the Linux ABI directly from the kernel, which is what makes it possible to run real programs now rather than after the full stack is built:

• static ET_EXEC ELF64 images are loaded by a portable, host-tested parser; ET_DYN and anything needing an interpreter are refused clearly rather than loaded and left to fault at a puzzling address
• programs start on a real System V stack with argc, argv, envp and an auxiliary vector, so a C runtime can find the program headers it was loaded from
• thread-local storage works through arch_prctl, per task and preserved across context switches
• an unmodified static BusyBox runs: it dispatches on its own name, reads files through openat/fstat/read, lists directories through getdents64, and its shell parses scripts, searches PATH, forks and execs. All of that is gated - the boot fails on busybox_did_not_run, busybox_applet_dispatch_failed, busybox_file_operations_failed or interactive_shell_did_not_run
• process semantics a real program assumes are present: fork is copy-on-write, signals are raised, masked, queued and delivered on the way back to user space, and wait4 reports a status with the exit code in the high byte and a killing signal in the low seven bits
• pipelines work. pipe2, dup, dup2, descriptor inheritance across fork, descriptors released on exit and SIGPIPE when the reader is gone are all implemented; the gate runs ls /EFI/BOOT | wc -l in BusyBox's shell and fails on pipeline_did_not_complete if the pipeline stalls
• the syscall surface is listed in syscalls.md

What is still missing is the part that begins where a single static program ends. ET_DYN and PT_INTERP are refused, so "runs Linux programs" means static ones. clone with CLONE_VM or CLONE_THREAD returns -ENOSYS and futexes are answered honestly rather than implemented, so a threaded program does not run. There is no entropy source, so getrandom refuses. There is one working directory - every path resolves against the volume root, so getcwd says / and openat accepts only AT_FDCWD - one identity, and no terminal device. Stubbing the full Linux table is explicitly not the plan - a program that receives a fabricated success dies later and less legibly than one that receives -ENOSYS.

Fallback

For software requiring tight kernel semantic fidelity, provide lightweight VM execution with shared filesystem and graphics bridges.

Windows compatibility

Proposed approach

• Windows subsystem service implementing Win32 and NT-oriented user-mode behaviors incrementally
• PE loader
• registry-like service abstraction
• object and handle semantic translation where possible
• graphics and multimedia support deferred after core process and file APIs

Key challenge

Windows compatibility requires significant semantic mapping around process creation, handles, synchronization, and filesystem expectations. This should remain outside the kernel core.

macOS compatibility

Proposed approach

macOS compatibility is the most constrained and should be phased carefully:

• Mach-like messaging semantics can be emulated in user space where needed
• selected Unix and userland tooling may run via POSIX compatibility
• native app compatibility may require a managed runtime, translation environment, or guest-backed execution depending on legal and technical constraints

Policy

Early phases should not promise broad unmodified macOS binary support. The architecture should remain open to targeted support without overcommitting the kernel.

Legal and ecosystem constraint

macOS compatibility must be evaluated not only as a technical problem but also as an ecosystem and legal one. The project should treat guest-backed execution, POSIX compatibility, and developer-tool portability as the realistic early focus rather than broad claims of native macOS application support.

Shared enabling technologies

• unified object and handle translation layer
• filesystem path semantics adapters
• signal or exception translation
• environment and process image loaders
• graphics and input broker services
• sandboxed compatibility domains

Current runtime prototype status

• compatibility runtime state machine is implemented for Linux, Windows, and macOS targets (enable, translate, stats).
• initial syscall translation probes are available per target to exercise end-to-end ABI bridging paths in host tests.
• translation statistics expose translated vs denied syscall counts for observability and safety gating.

Recommended compatibility rollout

1. Native toolchain and minimal userland
2. Linux userspace and CLI compatibility
3. Linux container runtime
4. Windows basic console and service-process compatibility
5. Windows GUI-oriented expansion
6. Selective Darwin and macOS-adjacent runtime experiments

Userland

Goals

• minimal but practical base system
• service-oriented architecture aligned with the kernel model
• strong tooling for bring-up, diagnostics, and automation

Core userland components

Init and service manager

• boots essential services
• enforces dependency ordering
• restarts supervised services
• exposes health and status APIs

Early phases should keep init and the long-lived service manager separate so that bootstrap concerns do not hard-code later supervision policy into the first process.

System services

• device manager
• filesystem manager
• network manager
• security policy service
• session manager
• logging and tracing services
• compatibility subsystem hosts

Command-line environment

• native shell
• standard utilities
• process inspection tools
• filesystem and networking tools
• tracing and crash-debug tools

Library strategy

• small native C runtime and system library
• C++ support for selected user-space components
• stable userspace API layered over the native syscall ABI

Desktop and GUI direction

GUI is not part of the earliest milestones, but the architecture should anticipate:

• compositor service
• display server or protocol layer
• sandbox-friendly application model
• remote and virtual display support

The detailed desktop architecture, interaction/visual specification, security boundaries and staged implementation plan are in ui-design/. The current framebuffer desktop is a bring-up surface, not the production window-system target; see graphics.md for its verified scope.

Developer experience priorities

• cross-toolchain support
• deterministic builds
• emulator-friendly boot flows
• serial and structured logs
• conformance and regression test harnesses

Current implementation snapshot

• service lifecycle now includes start and stop paths across init, devmgr, vfs, and net services.
• service manager exposes a health aggregation helper that reports currently running critical services.
• runtime supervision counters are exercised by host tests to keep orchestration behavior regression-safe.
• compatibility runtime core now includes per-target enablement and early syscall translation probes for Linux, Windows, and macOS layers.
• user API now includes wrappers for process security label get/set and interaction checks over native syscall ABI helpers.
• service manager now exposes restart-budget controls and failure reporting hooks to support stricter supervision policy behavior.
• service IPC runtime now validates service identifiers/message types and supports reply correlation/status fields for ACK/ERROR flows.

Toolchain and Build Strategy

Goals

• deterministic and reproducible builds
• a clear split between host tools and target artifacts
• support for kernel-grade debugging and tracing
• a sustainable language strategy for C and C++

Language

The project is C and assembly. There is no C++ anywhere in the tree, and the CMake project declares only C ASM.

That started as a plan for C++ in the higher-level subsystems and did not survive contact with the work. The kernel runs freestanding, with no runtime, no allocator during early boot and no unwinder; every C++ feature worth having there would have had to be disabled, and what remained would have been C with different syntax. Assembly is used only where nothing else can express the job: the AP trampoline, the syscall and interrupt entry stubs, and the program entry point in user/prog/crt0.S.

Rules:

• minimize dynamic allocation during early boot
• keep the freestanding kernel environment separate from hosted user-space components; the hosted TLS adapter lives in its own target precisely so it cannot be dragged into the kernel image by a future reference
• put portable logic in portable files - the ELF parser, the TCP/IP stack and the syscall translation model are all host-tested because they were written without touching hardware

Compilers

GCC and Clang are both first-class and both gated in CI, in Debug and Release. Neither is the primary one.

This is not even-handedness for its own sake. The two disagree about enough to have caught real bugs that the other missed: an entry stack misaligned by eight bytes faults on the aligned SSE store Clang emits and not on the code GCC generates; a page of SSE spills at -O2 triple-faulted a core that GCC at -O0 started cleanly. Two compilers are a cheap second opinion about undefined behaviour.

Linking follows the same split: the GCC path builds an ELF and converts it to PE, the Clang path links PE natively with LLD. Both produce a bootable image and both are boot-gated.

Build system

CMake 3.21+ with Ninja. Targets are separated by what they are allowed to assume about their environment:

The source list lives in cmake/core_sources.cmake and is read by both CMake and scripts/run-tests.ps1. It is a single file because it used to be two, and the copies drifted three times - each time breaking CI on Windows only, after the change had already been declared verified on Linux.

The build system should produce:

• kernel ELF or PE image as required by the boot path
• bootable disk image
• symbol files for debugging
• emulator launch targets

Cross-compilation model

• host builds run on Linux, macOS, or Windows development machines
• target triples are explicit and never inferred from the host
• freestanding kernel and hosted user-space builds use separate compiler flags and runtime assumptions

Debug and observability tooling

The concrete list, with the reason for each, is in development_tools.md.

• QEMU as the first emulator target
• GDB and LLDB support from the start
• serial logging as the first diagnostic channel
• symbolized crash output for kernel panics in debug builds

Build variants

• debug for bring-up and diagnostics
• release for performance profiling
• hardened for security validation once the base system matures

Early deliverables for phase 2

M1: Toolchain and Build Skeleton (completed)

The following are available:

Build System

• CMake 3.21+ with Ninja support (primary generator)
• GCC fallback for environments without CMake/Ninja
• Reproducible host-to-target build for kernel core and user-space components
• Modular target separation: vibeos_kernel_core, vibeos_user_core, vibeos_image

Commands

# One-command configuration and build
cmake -S . -B build -G Ninja -DVIBEOS_BUILD_TESTS=ON -DVIBEOS_BUILD_KERNEL_IMAGE=ON

# Build all targets (kernel, user-space, boot image, tests)
cmake --build build

# Run host-side tests
powershell ./scripts/run-tests.ps1 -BuildDir build

# Run tests with QEMU smoke test (if available)
powershell ./scripts/run-tests.ps1 -BuildDir build -RunQemu

# Standalone QEMU boot test
powershell ./scripts/run-qemu.ps1 -BuildDir build -ImagePath build/artifacts/vibeos_boot.img

Artifacts Generated

• build/artifacts/vibeos_kernel.elf kernel ELF image (loadable by bootloader)
• build/artifacts/efi_root/ bootable EFI media, including the ring-3 programs staged as EFI/BOOT/*.ELF
• build/artifacts/vibeos_esp.img, vibeos.iso, vibeos.vdi, vibeos.vmdk importable images (see the README)
• build/artifacts/boot_manifest.txt manifest of boot artifacts
• build/vibeos_kernel_tests.exe host-side unit test executable
• artifacts/test-summary.json structured test results for CI/agents
• artifacts/qemu-serial.log serial output from QEMU (if run)

Verified Configuration

• CMake generator availability detection
• Automatic fallback to manual GCC compilation if CMake/Ninja unavailable
• Toolchain version capture (cmake, gcc, qemu, ninja)
• Build artifact validation before test execution

M2/M3: Boot and Early Kernel (completed)

• one-command QEMU boot path (scripts/qemu-cli-smoke-linux.py), which boots four vCPUs under pure TCG and asserts state rather than grepping for a token
• image packaging pipeline producing UEFI media and importable disk images

Dependencies

third_party/mbedtls is the only external dependency, pinned as a submodule and fetched recursively - since 4.x it carries nested submodules of its own. It is optional: without it the build simply has no TLS, unless VIBEOS_REQUIRE_TLS is set, which the Linux CI matrix does so that a missing submodule fails loudly there instead of silently degrading.

Debugging a hang

Serial output is the first channel, but a hung guest has stopped producing it. The QEMU monitor is the second: info registers -a gives every core's RIP, and resolving those against nm on the kernel ELF turns "it froze" into a function name. Two intermittent hangs were diagnosed this way that no amount of added logging would have found, because the hang was in code holding the lock the logger needed.

Development Tools

What a development machine needs, and what each thing is actually for. Nothing here is required to build VibeOS beyond the first section - the rest exists to answer questions that are otherwise answered by guessing.

Install

On Ubuntu or WSL:

# build and boot
sudo apt install -y cmake ninja-build build-essential clang python3 \
                    qemu-system-x86 qemu-utils ovmf xorriso

# diagnosis and compatibility work
sudo apt install -y strace gdb musl-tools busybox-static gcovr lcov

Build and boot

Run everything through scripts/; see the README for the commands.

Diagnosis

Compatibility targets

What a static musl binary actually asks for

Recorded with strace on Linux, in order, for a printf and malloc program:

execve  arch_prctl  set_tid_address  brk  brk  mmap  mmap
ioctl  writev  munmap  writev  exit_group

Every one of those is implemented. That list is the reason the startup syscall work targeted what it did, and it is worth re-recording whenever a new target binary is chosen: the set is a property of the libc, not of the kernel, and guessing at it produces stubs nobody needs alongside gaps that stop everything.

The remaining blocker is not a syscall. A Linux executable is linked at 0x400000, which falls in the first 512 GiB of the address space - the region VibeOS currently maps as the supervisor-only kernel identity map, with user memory living in the next PML4 slot instead. Loading a real binary means being able to map user pages at the address it was linked for.

Testing Strategy

Goals

• catch regressions before they reach low-level integration work
• validate contracts between kernel and services
• measure compatibility progress with repeatable suites
• keep bring-up fast enough for daily development

See also scripts/dev/README.md, which lists what each development script does and why it exists. (The April test-automation specification and its feedback profiles were never built; they are in archive/.)

What runs on every push

• Build matrix: gcc and clang, Debug and Release. Two compilers disagree about enough - alignment assumptions, optimisation of inline assembly, PE linking - that one of them alone has repeatedly been insufficient.
• Host suites (ctest), plus the same suites again under AddressSanitizer and UndefinedBehaviorSanitizer. The protocol code parses attacker-chosen input, and the sanitizer run is the only gate that sees memory errors at all.
• UEFI boot gate under OVMF, and a boot-to-CLI gate that boots four vCPUs under pure TCG, asserts state invariants (DHCP lease non-zero, all cores online, no unexpected fault, no panic) and completes a TCP round trip to a host echo server.
• CodeQL static analysis.
• libFuzzer over the network receive path.
• Nightly: repeated boots and a longer fuzz run. Dependabot tracks the actions and the submodules.

Two lessons are built into the above, both learned the expensive way:

• The boot gate must assert state, not the presence of a token. A kernel can print BOOT_OK and still have failed to get a DHCP lease or bring up three of its four cores.
• Local verification must use the same configuration as CI. Roughly twenty clean local runs once validated a hardware-accelerated setup while CI ran pure emulation; forcing -accel tcg locally reproduced the CI hang in two runs out of three.

Test layers

Unit tests

For pure logic that can run on the host:

• allocators where host execution is possible
• parser code
• protocol encoders and decoders
• compatibility translation helpers

Kernel subsystem tests

For logic requiring the target environment:

• paging and address-space operations
• scheduler invariants
• IPC semantics
• timer behavior
• handle-rights enforcement

Service integration tests

• init and service manager lifecycle
• driver host restart behavior
• filesystem service contracts
• network stack control-plane flows

System boot tests

• boot image loads in emulator
• kernel reaches known checkpoints
• basic user-space services start in order

Compatibility tests

• Linux syscall and libc behavior subsets
• Windows process, file, and console behavior subsets
• selected Darwin and POSIX semantic checks where applicable

Execution environments

• host-native tests for portable libraries
• QEMU for deterministic bring-up and CI
• optional hardware validation later for timing and device realism

Release gates

No milestone should be considered complete without automated validation for its core claims. In early phases this means emulator-based smoke tests at minimum; later phases require subsystem-specific regression suites.

Required early artifacts

• test harness runner
• boot smoke test
• serial log assertions
• golden compatibility samples for Linux-first milestones

Debugging expectations

• failures should capture build variant, git revision, emulator configuration, and log excerpts
• kernel failures should preserve a structured panic signature where practical
• compatibility failures should distinguish loader, translation, and runtime-service faults

Implementation Progress (Macro Areas)

Last review: 2026-09-29

One row per area, the state in a sentence or two. How each got there is in the linked files, which keep the full history - including the long status cells this table used to carry, moved there verbatim on 2026-09-29.

Notes

• Status reflects code currently present in repository, not only planned milestones.
• A file existing under user/compat/ is not progress. The Windows and macOS translators are twenty-four lines each, know two syscall numbers, and nothing calls them; they are tracked as not started for that reason. The Linux compatibility that works is the kernel syscall layer, which is a different piece of code entirely.
• "Verified" here means a gate fails if it regresses, unless the entry says otherwise. The framebuffer desktop is the standing exception: its serial-visible state is gated, its pixels are checked by hand with scripts/dev/screenshot.py.
• Each macro-area file contains:
  • implemented items verified in code
  • pending items
  • next execution checkpoint

Subsystem Rewrites: Order and Scope

What is planned, what is deliberately sketched rather than planned, and why.

The memory manager is being rebuilt to a written plan with layers, invariants, host tests and sabotage cases. That treatment came from one decision - stopping to plan before writing code - and it is the only part of this kernel that has it. Everything else lives in kernel/arch/x86_64/arch_hw.c: 8312 lines, 267 static functions, holding the scheduler, syscalls, program loading, pipes, signals, the network glue, the interrupt controllers and the console, with no boundary between any of them.

Order

After the Linux ABI's L7 (decided 2026-10-12)

L1 to L7 of docs/abi/ are closed. Before L8 (system administration), in this order:

1. The Windows system calls - the second personality, over the same include/vibeos/ksvc.h every Linux handler reaches the kernel through. Planned in abi/windows.md: our own ntdll, an object manager in the kernel, Wine's conformance tests as the oracle.
2. The filesystem's hierarchy - what lives where, from the boot volume to /tmp, /proc and /dev, decided rather than accumulated.
3. The user interface - designed, not grown from the boot console.
4. Security, all of it - isolation, privilege, sandboxing; L9's capabilities, seccomp and Landlock are its Linux-facing part.
5. The applications that manage the system.
6. The rest of networking.
7. System administration (L8), last, once what it administers is defined.

Implementation sequencing is refined when a subsystem is next, for the reason the following section gives. By maintainer request on 2026-10-17, the filesystem namespace and desktop/UI architecture have been designed ahead of their implementation slot: see filesystem-design/ and ui-design/. This is planning-only work; it does not reorder the active runtime milestones or authorize a format/ABI freeze.

Why 4 and 5 are sketched and not planned

A plan written for work that starts in a month is a prediction, not a design. The memory plan has already been corrected twice at contact with reality - the ownership bit it specified was already taken by PTE_COW, and its completion criterion measured a pre-existing flakiness rather than the phase. Both were found by executing, not by planning harder.

So the two furthest subsystems get their objective, their invariants and their boundaries recorded now, while the knowledge is fresh, and the phase-level detail when they are next.

4. Syscalls and the Linux ABI

Planned in full on 2026-09-29 - docs/abi/. The objective and invariants below are carried into it unchanged; they are kept here as the sketch it started from.

Objective. One dispatch table, one place that validates arguments, and a translation layer that says what it does not implement.

Invariants worth writing down now

1. Every syscall argument that names user memory is validated in one place, and the reason for a refusal is reported (hw_user_range_why exists for this).
2. An int argument arrives zero-extended; comparisons happen through VIBEOS_ARG_INT and never against all 64 bits. This has bitten and is recorded in CLAUDE.md.
3. A sigset_t is converted at the boundary and nowhere else.
4. An unimplemented syscall is refused and counted, never silently succeeded.
5. A wait status carries the signal in the low seven bits and the exit code in the high byte - and every producer and consumer agrees.

Boundaries. Dispatch and validation are portable; the register ABI and the syscall entry are not.

5. Network and pipes

Objective. The receive path stops being reachable from two contexts without a stated rule.

Invariants worth writing down now

1. The stack is entered from syscalls and from the timer interrupt; exactly one lock covers both, and nothing slow happens under it.
2. A pipe's end count is a refcount, not a flag: a descriptor can be duplicated and inherited, and end-of-file depends on getting that right.
3. Buffers handed to the device are owned by exactly one side at a time.

The rule that applies to all of them

Check a criterion against the baseline before using it to judge a change. Written here because it cost two days on the memory manager: a phase was declared unfinished for a day and a half against a boot count that no revision of this project has ever met.

Closed: the second syscall layer (deferred 2026-09-02, deleted in C3)

Settled by the core plan's C3: kernel/core/syscall.c was deleted and its vocabulary with it (2026-09-20); what remains of the question - kernel/proc/process.c - is recorded in scripts/dev/cases/core-dispatcher.txt. The text below is the deferral as it was written.

kernel/core/syscall.c and kernel/proc/process.c are a complete syscall dispatcher and process table that nothing in ring 3 reaches. The real path is vibeos_x86_64_syscall_entry, wired through MSR_LSTAR into the hw_sys_* functions in arch_hw.c; the portable dispatcher is called only from user/lib/user_api.c, which nothing else in user/ uses, and from the host tests.

An external review found three real defects in it, all latent for that reason:

• vibeos_thread_create takes a raw pid with no caller/target relationship check, unlike PROCESS_TERMINATE beside it - a thread created that way inherits the target process's security token.
• vibeos_proc_terminate marks a slot TERMINATED and never clears in_use, so after 32 process creations every further one fails permanently.
• The caller id used for every privilege check comes from frame->arg2, supplied by the caller: passing 0 impersonates the kernel.

Deferred until the memory-manager plan is finished, deliberately. The question is not "are these bugs" - they are - but whether that layer should exist at all, and that depends on what the memory manager ends up exposing. Deciding now means deciding with less information than we will have in two phases.

The risk of deferring is bounded and worth stating plainly: none of it is reachable from ring 3 today, so this is a decision about architecture rather than an open hole. The risk of not writing the deferral down is the real one - a month from now this is simply code that is there, and nobody remembers it was a choice.

When it is taken, the options are: remove it, wire it and fix it first, or keep it as the host-tested model it currently is with a comment saying so. What must not happen is that it becomes reachable before the three defects above are fixed.

Splitting arch_hw.c

Status: two cuts done. 9088 → 8359 lines. Last review: 2026-09-02

Why

kernel/arch/x86_64/arch_hw.c reached 9088 lines. Worse than the number is how it got there: during a session spent explicitly on "reducing the monolith" it grew by 633 lines, and nobody noticed until the person paying for the work asked why a file being reduced had gone from seven thousand to nine.

The growth was not careless. Every addition was a diagnostic or a fix that earned its place — hw_ctx_check, hw_cache_audit, hw_exec_refuse, the panic that parks every core. The problem is that the plans which were supposed to shrink the file only ever added portable code beside it. The task state machine became portable; g_tasks[], hw_task_alloc and hw_pick_next stayed exactly where they were.

So this plan has one criterion the others lacked: the line count of arch_hw.c is a completion condition, not a side effect.

Why it was hard to start

Everything in that file is static over shared file-scope globals. Nothing can move until somebody decides what the rest of the file is allowed to see. That decision is now kernel/arch/x86_64/arch_hw_internal.h, and it is deliberately not a public API: nothing outside kernel/arch/x86_64/ includes it, and a declaration arriving there should be read as a cost — a thing two files must now agree about — rather than as progress.

Cut 1 — the Linux socket syscalls (done, 2026-09-02)

kernel/arch/x86_64/linux_socket.c. None of what it does is architecture: reading a sockaddr out of user memory, allocating a descriptor, blocking until a connection arrives is Linux ABI translation over the portable TCP/IP stack in kernel/net/inet.c. It sat beside the GDT because that is where the file started.

The numbers, including the part that is not flattering:

The monolith lost 544 lines and the tree gained 130. That 130 is the seam, and it is the right thing to watch: a cut that costs more header than it removes source is a rename.

The seam is ten functions and six globals wide — and it is wider than the socket code alone needed, which is worth saying out loud. The socket file wants hw_task_t; a task holds a saved register frame, an address space and a descriptor table, so moving the task moved vibeos_x86_64_isr_frame_t, hw_proc_t, vibeos_hw_aspace_t, the Linux errno values and five constants with it. That is the honest cost of the first cut, and most of it is paid once: the next files to leave will find those types already on the far side.

One deliberate narrowing: g_current_task is a macro over per-CPU state. Exporting it would have put hw_cpu_t on the header for the sake of one integer, so the seam has hw_current_task() instead. A file that has been lifted out has no business knowing how this kernel finds the current core.

Cut 2 — signal delivery (done, 2026-09-02)

kernel/arch/x86_64/linux_signal.c. Building a frame on a user stack, calling a handler on it, and taking the frame back when the handler returns is Linux ABI, not x86. What is architectural about it - the selectors, the trap frame layout - is named in the seam header and nothing else in the file needs to know.

The two halves were four hundred lines apart, with the crash dumper and half the syscall table between them. That is the more useful thing this cut fixed: hw_signal_deliver and hw_sys_rt_sigreturn are one subject and now sit together.

A correction to this plan's own estimate. The table below called this section 915 lines. It is not: the banner "delivering a signal" covers signals, the memory-diagnostic walk, the panic summary, the crash dumper and the whole Linux syscall table. The signal code proper is 185 lines. Section banners in that file describe where somebody stopped writing, not what follows.

The diagnostics group was measured and deliberately left. hw_walk_step, hw_frame_still_mapped, hw_panic_cpu_summary, hw_dump_vanished and vibeos_x86_64_crash_dump are ~427 cohesive lines and would make a good file - but they touch eleven globals including g_cpus, which would put hw_cpu_t on the seam. That is exactly the widening avoided in cut 1 with hw_current_task(). It needs an accessor pass first, so it waits rather than being taken at the wrong price.

Cut 3 — the storage and I/O bring-ups (done, 2026-09-07)

11166 -> 9995 lines. And the first number is the point of this section.

Between cut 2 and cut 3 the file went from 8359 to 11166 lines. Not because anybody decided to grow it: the I5 and I5b work - filesystem images, the log sink, the scratch device, the volume scan, the mount report - was written straight into it, one bring-up at a time, over three days in which this document sat here saying the length of the file is the completion criterion.

That is the same failure this plan already records once ("a session dedicated to reducing the monolith grew it by 633 lines"), at four times the size, and by the person who had read the note. Writing it down again rather than quietly fixing the number, because the lesson is evidently not learned by being written once: new code goes to its own file on the day it is written, not after.

What moved: hw_swap_bringup, hw_write_proof, the log sink bring-up and its console tail, hw_fsimages_bringup and the filesystem-image table, hw_scratch_bringup, hw_volumes_bringup, hw_mount_report. All of it runs once from the boot path and none of it is reachable from a syscall, which is why it separates cleanly.

The seam measured eight names in and seven out - narrow for a monolith, and narrow because the code was new. It had not yet grown the incidental couplings that make the older sections hard to separate. That is an argument for cutting recent additions first: the seam is cheapest on the day the code lands and gets more expensive every week it sits there.

Six statics had to stop being static (g_rootfs, g_swap_bitmap, hw_alloc_page, hw_free_page_why, hw_frame_identity_map, and the swap-slot constant moved to the header beside the array it sizes). They are grouped under one banner in arch_hw_internal.h so the next cut can see what this one cost: every line there is encapsulation given up to buy separation.

Verified by the boot, not by the compiler: all six mounts, all four filesystem images and the log sink read back exactly as before.

Next cuts, in the order they look worth doing

Measured, not estimated from section banners - which is what cut 2 taught:

And one that is not a move at all: X-P2 steps 3 and 4. Demand paging removes the eager read, and with it g_exec_elf, g_interp_elf, the staging cache and the copy loop around them - several hundred lines that leave without needing a seam, because they stop existing.

The log is the only one that can become genuinely portable rather than merely a separate file in the same layer. The others stay architecture-adjacent, and that is fine: a 700-line file that does one thing is not the problem this plan exists to solve.

Boot Repeatability Progress

Status: 24 local boots clean out of 24 - but CI still reproduces the copy-on-write stress defect on a build containing every fix below, so this number is not the whole picture. See the correction dated 2026-09-02, from a long-standing ~1 in 8.

Six defects fixed. The first three were in the diagnostics built to hunt the failure rather than in the kernel they were watching. The last three came from CI and nightly logs rather than from another local sweep: a copy-on-write fast path deciding on a fact its compare-exchange could not guard, a kernel address handed to ring 3 as AT_BASE, and - the one that explains the rest - a panic that stopped one core instead of the machine.

24/24 is a good number and not a proof. At the rate this measured immediately before (23/24), a clean run of 24 happens about a third of the time by luck alone. What is stronger than the count is that two of the three new fixes are asserted deterministically - a host test for the copy-on-write window, a ring-3 assertion for AT_BASE - and the third turns any future kernel fault from a silence into a named panic. Last review: 2026-09-01

What fails

Two signatures, both intermittent, on an otherwise green build:

• An instruction fetch from a page that is not present, with cr2 equal to rip, inside the same page the process was already executing from. Seen in svc-flap, a service whose whole body is a write and an exit - so the page vanished under a running process rather than the program jumping somewhere wrong. The boot gate reports it as deliberate_ring3_faults=2_expected=1,unexpected_cpu_fault.
• A wedge, at varying phases, reported as missing:CLI_READY after 45 seconds of silence.

Why it is filed separately

It was found while trying to certify phase P2 of the memory-manager rewrite, and for a day it was assumed to be that phase's debt. It is not, and the evidence is unambiguous in two independent directions.

Locally, the same 24-boot measurement was taken at three revisions:

In CI, the nightly Boot Smoke x5 (flakiness gate) job - five boots, all of which must pass, which is this same criterion in miniature - has failed 27 times out of 31 since the workflow was created on 2026-08-02, including nineteen consecutive nights on 19ebeb74, a commit that predates any of this work.

So the failure is older than the subsystem it was being blamed on, and older than the gate that reports it.

What it is not

Not the premature-free family. Across these runs the free-while-mapped detector is silent, the stress service reports no defect, and frames_leaked, frames_double_put and poison_hits are all zero. Those were the symptoms of the three concurrency defects fixed during P2 (e02d9dd, 6510827), and they are gone: the boot rate went from 27/48 while those were live back to the ~90% that every revision measured before them.

What this cost, and the lesson

Phase P2's completion criterion was written as "48 boots with no failure". With a background failure rate near 8% per boot, the probability of 48 consecutive clean boots is about 0.02% - so that criterion could never have been met, by this revision or by any revision in the project's history. It was measuring the background, not the phase.

Two days were spent treating an unreachable number as a verdict on the work in front of it. The rule worth keeping: a criterion has to be checked against the baseline before it is used to judge a change. One measurement of the parent commit would have said so immediately, and it was not taken until somebody asked for it.

The number was not wasted, though, and that is the other half of the lesson. Insisting on 48 boots surfaced three genuine concurrency defects that a 16-boot gate would have passed over. The mistake was in what the number was allowed to conclude, not in running it.

What the walk dump found (2026-08-31)

A temporary probe printed the four entries of the page-table walk on any fatal not-present user fault. It answered the question the trap dump cannot:

va=0x8000001243 cr3=0x231f000 pml4e=0x040326e0 pdpte=0 pde=0 pte=0
stopped_at_level=1

The leaf is not missing - PML4 slot 1 is, so the whole user window of a running process is gone. And the value sitting in that slot is not anything this code writes: the present bit is clear and bit 7 (PS) is set, which is illegal at that level. Read as data rather than as an entry, 0x040326e0 is a pointer into the kernel image. The same shape appeared at three different cr3 values across boots (0x040326e0, 0x040336c0, 0x040336f0).

So a process page table is being freed and handed to some kernel allocation that writes a pointer into it, while a task still runs on that CR3.

This also explains why every memory detector stayed silent through the hunt: they watch frames mapped as leaves, and a page table is not a leaf. The free-while-mapped check could not have caught this by construction.

One candidate was fixed and was not it. execve destroyed the outgoing address space unconditionally, while hw_task_exit has asked hw_aspace_still_shared since the wedge it was written for - so a threaded process that execs freed tables its siblings were still running on. That is a real defect and the fix is in (hw_aspace_shared_by_other, asked by address space so exec and exit cannot answer differently), together with a leak in fork's error paths, which published a task slot as free without destroying the address space it had already created. Neither closed this signature.

What it actually was (2026-08-31)

Three defects, found in one afternoon by reading failure logs instead of re-running boots. Every one of them was in the instrumentation.

1. The "who freed it" tag was a use-after-free. hw_free_page_why released a frame and then wrote the freeing function's name into word 1 of the page. Between the release and that store another core can allocate the frame - and word 1 of a page is slot 1 of a PML4, the user window. A diagnostic meant to say who let go of a page was reaching into a live address space and replacing its entire user half with a pointer to a string literal.

That is the signature recorded above and never explained: a ring-3 instruction fetch faulting inside the page the program was already executing from, the walk stopping at level one, a kernel pointer where a page-directory pointer belonged. The dump that finally caught it printed the missing half - cr3_state=page-table, cr3_owners=1: the frame was not free at all. A live, owned PML4 with garbage in one slot.

The comment that had justified the write is worth keeping in mind. It reasoned carefully about the poison check never probing word 1, and not at all about the frame being reallocated in between. Being careful about the wrong hazard reads exactly like being careful.

2. The free-while-mapped walk was panicking the kernel. It reads every live task's page tables without the scheduler lock - deliberately, because it runs on the frame layer's release path - so it can read a table another core has just freed. A freed frame handed out again holds arbitrary bytes, some with the present bit set and an address field pointing anywhere. Following one faulted the machine, twice in twenty-four boots, and those failures were being counted as the defect it was hunting. Every step is bounded now.

3. The region pool had no lock. Eight refused inserts in a boot whose peak usage was twenty-nine descriptors out of two thousand - a pool nowhere near full that had shredded its own free list. Two allocations racing both take the head and both advance it. fork then failed with ENOMEM and the stress service reported "fork for cow". The same mistake the frame layer had already made and fixed, repeated in a layer written the day before.

What remains

One wedge in twenty-four boots, and it has a lead rather than a mystery:

#GP at vibeos_x86_64_task_enter (isr.S:294)
then #GP at rip=0xe4e4e4e4e4e4e4e4

A task's saved register context contains a repeated fill byte, so restoring it faults - and the panic handler then runs on the broken state and faults again. 0xe4 appears nowhere in the source as a constant, so the next question is what writes it: an uninitialised context, a recycled slot scheduled before its creator finished filling it in, or a kernel stack being used after it was freed. The task state machine's SETUP state and its tenancy counter exist for exactly this shape and should be the first things consulted.

The remaining wedge was virtio-net transmitting without a lock (2026-09-01)

Named by the wedge report rather than guessed at, which is what that tool is for. A boot that went quiet at busybox_cat left this:

CPU#0 rip=... vibeos_x86_64_virtio_net_send virtio_net.c:276
CPU#2 rip=... hw_spin_lock  <- from hw_sys_munmap
CPU#3 idle

and QEMU said the rest on its own stderr:

qemu-system-x86_64: Guest says index 65535 is available

virtio_net.c had no lock on the transmit path. Every send uses one staging buffer, one descriptor - g_tx.desc[0] - and one g_tx.last_used, and publishes with a plain g_tx.avail->idx++ on a 16-bit field.

This is the same defect virtio-blk had, in the same shape, never applied here. Two cores sending at once do not race over a window, they overwrite each other: one core's frame lands in the other's descriptor, the available index skips or repeats - 65535 is what a lost increment on a uint16_t produces - and whichever core reads the used index first leaves the other spinning on a completion that has already been consumed. The spin has a bound, but 50 million pauses is far longer than the gate's quiet budget, so it presents as a wedge rather than as the timeout it eventually becomes.

Interrupts stay on, as in the block driver: nothing in an interrupt handler transmits, so this lock can never be wanted from one. The timeout path releases it before returning, because holding it there would turn one late frame into a permanently dead network.

Fifth layer in this project to have shipped without a lock, after the frame allocator, the region pool, the page cache and the block driver.

Worth separating from it: the crash record that appears in every boot is svc-crash dereferencing null on purpose, to prove a ring-3 fault kills the task and not the machine. It is a gate, not a defect, and its absence would be the failure.

The copy-on-write failure is a copy that was replaced (2026-09-03)

Deduced from four CI logs, without a new run, and it narrows the search from three causes to one.

The child always reads exactly the parent's value, never garbage: found 0xd7 expected 0x28 with after = 0x28 means before = 0xd7. Four logs, four times, the same relationship.

And op_cow checks the parent's page separately, after reaping the child - "the child's writes reached the parent". That check has never fired.

Put together: the parent's page is intact, so the child was not writing into it, so the child did have a private frame. And the private frame holds a clean copy of the original, so the child's writes are gone from it.

That is not "the copy never happened". It is "the copy was made and then replaced." One of the three causes, chosen by evidence already in hand.

What that implicates: only clone_one - fork - sets the copy-on-write bit, and the child of op_cow never forks. So something is putting that bit back on a page that had already been made private, and the next fault copies the original over the child's work.

vibeos_pageinfo answers this directly: svc-stress now samples the frame before the fork, after it, after the child's write and at the check, and prints which of the three cases it was. That output needs a push to reach CI - the artifacts analysed here predate it.

The 0xe4 fault is not attributed to anything (2026-09-02)

Nothing in this file explains it, and three attempts to say otherwise were wrong. Recorded plainly so the next attempt does not start from a conclusion.

rip=0x57da77  cr2=0xe4  err=0x5   (user read, present, supervisor-only)

What is known:

• It appears in two different programs, BUSYBOX.ELF and THREADS.ELF, at the same rip. Both are static musl binaries, so that address is almost certainly a musl internal function rather than program code - which is why the same number turns up in unrelated programs.
• The faulting access is a read of a near-null pointer plus 0xe4. So a pointer that should have been valid came back as zero, or nearly.
• It is deterministic in its path - the same rip, the same offset, every time - and rare in occurrence, a few times in twenty-four boots.
• It appears with the X-P2 cache mapping on and off.

What is not known: anything about the cause.

The three wrong conclusions, kept because the pattern is the lesson:

1. "The signature is gone" - from grepping the rip in a boot that had wedged and had no crash record at all, so the rip could not have appeared.
2. "The cache mapping causes it" - from 21/24 twice against a baseline reported as better than it was.
3. "Turning the mapping off removes it" - from one clean run of twelve, against a defect that appears a few times in twenty-four.

Every one of them read an absence over too short a run as proof. The next attempt needs the faulting instruction disassembled out of the binary the task was running, not another ratio.

A panic stopped a core, not the machine (2026-09-01)

This is the explanation for the silent-wedge family, and it had been visible in every log all along.

hw_panic ended with for (;;) { cli; hlt; } - which stops the calling core. Its own message said so: "halting on cpu 2". For weeks that line was read as though it said "halting".

The other three cores carried on. The log kept moving. The machine went quiet some seconds later, at a place with no connection to the fault, and every investigation started from that place. That is why so many of them ended at a plausible-looking pointer with no mechanism behind it: the evidence and the failure were separated by however long it took the survivors to need the core that had died.

A nightly log showed it plainly once the question was asked: a ring-0 #GP on cpu 2 with action=PANIC, followed by four hundred more lines of healthy boot, then silence.

The fix. A panic sets a flag and every core parks itself on its next interrupt. Deliberately not an IPI: every core already takes a timer interrupt a hundred times a second, so this needs no new vector, no acknowledgement protocol and no timeout to get wrong. A core inside a syscall with interrupts masked parks when it returns to ring 3; a core that never returns was stuck either way.

Proved by causing one. cpu 3 panics, and cpus 1, 2 and 3 report parking.

The gate now calls it a panic, not a wedge, and carries the reason:

reason=missing:<why> (waiting for CLI_READY) verdict=guest_panicked

Calling a panic a wedge sent the next person looking for a hang. That mattered much more than it sounds, for exactly as long as a panic left three cores running.

A kernel address handed to ring 3 as AT_BASE (2026-09-01)

Found from the nightly's artifacts, which carry the kernel ELF and the guest binaries - so a faulting address could be symbolised against the binary the task was actually running, which is the rule this file has been repeating without being able to follow it.

PIE.ELF faulted at 0x4046220 in _start_c (rcrt1.c:139), musl's self-relocation for a static position-independent binary. nm on the kernel places that address inside g_kernel_log.

p->interp_base was written in exactly one place - the branch that maps an interpreter - and read unconditionally when the startup block was built. A program without an interpreter therefore shipped whatever was already in that field to ring 3 as AT_BASE: uninitialised kernel stack for an execve (hw_proc_t np is a local), or the previous tenant's value for a recycled task slot. A static PIE relocates itself against AT_BASE, so musl took a stray kernel pointer as its load address and dereferenced it.

Intermittent for the honest reason that it depends on what was left on the stack - which is why it read as "position_independent_binary_did_not_run" some nights and nothing at all on others. It is also a kernel address disclosure to ring 3 whatever the program does with it.

Zeroed in hw_proc_create, which owns the contract - "every caller must remember to clear a field" holds until somebody adds a caller. The ring-3 ABI self-test now asserts AT_BASE is absent for a program with no interpreter, every boot, deterministically.

The copy-on-write defect: one window closed, the defect still open (2026-09-02)

Correction. This section previously said "found and closed". It was not.

A nightly on a build that contains the fix - its exec line carries cache_audit_checked, which only exists from d9c0049 - failed again with the same signature:

STRESS_FAIL: the child's own copy-on-write page at offset 0: found 0x07 expected 0xf8

after is 0xf8, so before is 0x07: the child read the parent's value after writing its own across the whole page. And COW_STATS reported exclusive_lost=0, so the window fixed below was never even entered in that boot.

The window was real - the host test proves it deterministically, and it stays - but it was not this one.

"Closed" was inferred from 24 boots with no stress failure. That is an inference from an absence, on a defect this same file records as appearing about once in twenty-four. This document exists largely to record what that habit costs, and it happened again here.

What the evidence says now, across three occurrences: the child writes after to all 4096 bytes and then reads before back at offset 0. That is not a lost write - it is the page being replaced by a fresh copy of the original after the child had already written into it. So the question for the next attempt is not "which write was lost" but what resolves a fault on that page a second time, and how the entry still looks copy-on-write when it does.

Replay seeds recorded: 76419299086, 97300336535.

The window that was closed (2026-09-01)

Closed by CI logs, not by another boot sweep. The nightly's clang/Release job had failed with

STRESS_FAIL: the child's own copy-on-write page at offset 0: found 0xf3 expected 0x0c
STRESS_FAIL: replay with EFI/BOOT/SVC_STRS.ELF 5498867...

on a build that predates all of this session's work, which settled that it was pre-existing rather than a regression. Decoding the two numbers is what pointed at the mechanism: the stress service writes after to every byte of the page and reads it back, and found=0xf3 is exactly before - the parent's value. The child was reading the parent's frame after writing its own.

Two defects, one page of code

1. The fault handler's exclusivity check rests on a fact its compare-exchange cannot guard. vibeos_vmspace_fault has a fast path: if the frame has one owner, take the write permission back in place rather than copying. It reads vibeos_frame_owners(phys), then compare-exchanges the page-table entry.

The exchange guards the entry. The decision depends on the reference count. The entry does not encode the count, so the two are unrelated, and a fork on another core can take a reference in the window while leaving the entry byte for byte identical.

2. clone_one is what walks into that window. Its already-copy-on-write branch does no compare-exchange at all - it has nothing to change, since the entry is already marked - so it takes a reference on the frame and maps it into the child without touching the source entry. There is nothing for the fault handler's exchange to notice. It also read the entry with a plain load, in a file whose entire design is that every page-table word is read once and acted on atomically.

The result is a process holding a writable mapping of a frame another address space holds copy-on-write: one side's writes landing in the other's private page. When the frame is later reused, the same defect shows up instead as a page holding a value from a completely different round - which is the local failure, found 0x5b, a before value from another iteration.

The fix, and why it can stay fast

The fast path keeps its optimisation and re-checks after the store: if the frame gained an owner while the entry was being widened, the entry is put back and the copy path taken instead. Undoing is safe precisely because no TLB has seen the writable form - it is installed and withdrawn before any invlpg, and the faulting instruction has not been retried. clone_one now reads its entry atomically. cow_exclusive_lost counts the window being hit, because it was silently common and must never become unobservable again.

It is asserted deterministically, not through boots

This is the part worth keeping. A race that appears once in some number of boots cannot be gated by a boot, and every earlier claim in this file that such a thing was "fixed" rested on a handful of green runs.

vibeos_vmspace_set_race_hook is a seam that lets a host test occupy the window on purpose: it fires between the ownership decision and the store, and the test takes exactly the reference clone_one would. The assertion is that the frame shared during the fault is not the frame the address space can afterwards write. Removing the re-check turns it red with

FAIL:a frame shared during the fault was made writable in place

every time, on the host, in under a second.

Rate after the fix: 23/24, with no stress failure in any of them.

Superseded: the copy-on-write path (2026-08-31)

Separate from the two signatures above, and the more tractable of everything here because it has a detector that names it:

[MM] FREE_WHILE_MAPPED frame=0x237d000 still mapped by pid=0x5a
     during cow-fault mappers=0x2 owners=0x1

Two address spaces hold the frame and one reference is counted, so a get was lost rather than a put duplicated. Three concurrency defects in this path were found and fixed during P2 - publication order, release order, and two cores resolving one fault with a compare-exchange - and the rate improved from 27/48 to the background. This one is not closed. It appears roughly once in twenty-four boots, and it was reported as fixed once already on the strength of a clean 48-boot run, which at this rate proves little.

The detector is trustworthy now: it compares mappings against references after the release, so it is indifferent to a frame being reallocated under it - the two predicates it had before were wrong in opposite directions.

Next

• Establish when this started. The nightly has never been reliably green, so the search goes back before 2026-08-02; scripts/dev/bisect-boot.sh takes a revision and a count and always restores the tree.
• The svc-flap signature is the more tractable of the two: a page disappearing under a running process is a narrow claim, and the crash records (crash on the kernel console) already keep the registers and the executable name at the moment of the fault.
• repeat-boot.sh keeps the serial log of every failed boot, so a run leaves evidence rather than a count.

A second intermittent family, found on 2026-09-11: the kernel runs garbage during THREADS

Recorded apart from the signatures above because it is not one of them, and mixing two intermittent failures into one rate is how this file once spent a day on the wrong defect.

What the failing boot showed

Boot 7 of a twelve-boot series, reason=missing:unrecoverable. Read from the kept log rather than counted:

• A kernel-mode trap on cpu 2 with a frame that is not a frame: rip=0xffffffff cs=0, and rsp/ss that decode as ASCII - TMP. and ES.TXT, file names from the boot's own self-test script. The core took an exception on a kernel stack holding the contents of a file-name buffer.
• A second trap executing at rip=0x3030303030303030: the string 00000000. A return address overwritten with text.
• Three cores on THREADS.ELF, one address space. THREADS_STAGE1_OK printed, THREADS_OK not - so it died in the stage where four workers contend a mutex and exit, and the last lines before the panic are munmap releasing their thread stacks.
• The ring-3 fault at rip=0x800000016b earlier in the same log is svc-crash faulting on purpose. It is in every boot, green ones included, and is not the cause. It was mistaken for one once already today.

Why it is recorded as pre-existing

argv-hunt/serial-9.log, dated 2026-09-08 - three days before the process-state change and everything after it - has the same shape: a kernel-mode fault executing a garbage address (rip=0x44), three cores on THREADS.ELF sharing one cr3, THREADS_STAGE1_OK reached and THREADS_OK not. The stage it dies in exercises neither wait4 nor tkill, which were the change under test.

What is not known

The mechanism. The shape - a kernel stack whose contents became file data, in a stage full of thread exits and stack unmaps - is the shape of a kernel stack page reused while still in use, which is the family dead_kstack_base closed once already. That is a direction to instrument, not a finding. Rate: one in twelve on this series; the three-day-old log says it was there before, not how often.

A user-side sign, found later the same day

The twelve boots after the futex change failed twice, and both logs carry a line the first reading passed over, a user write the fault handler refused just before the trouble starts:

COW_FAULT va=0x406d10 rip=0x405982 err=0x7 NOT-handled   (THREADS.ELF)

Boot 9 stopped there - the thread was killed, THREADS_OK still printed, and the boot ended missing:CLI_READY after a POISON_BROKEN report. Boot 1 went on to the kernel garbage above. fail-7.log, from before the futex change, has the same line at va=0x4069f0 rip=0x405662: both addresses exactly 0x320 lower, the size of the stage added in between. One instruction, three failures.

Resolved against the binary that ran (scripts/dev/.resolve-threads.sh):

• rip is musl's start in pthread_create, lock cmpxchg %edx,0x10(%rdi) - the new thread's first touch of the argument block its creator placed on the new stack. So rdi was 0x406d00.
• 0x406d00 is inside __clone: the instruction after call *%r9. __clone hands the child rdi with pop %rdi off the new stack top.

So the child popped a return address - one pushed by a thread that had already started on that same stack and called its start function. When this thread began, the frame at its stack top was not the block its creator wrote but one another thread had left there.

That is a finding about the user side and a direction for the kernel side, not yet a mechanism: a thread stack mapped over memory still in use (an mmap range handed out twice, or a physical frame behind it reclaimed early - the POISON_BROKEN line in boot 9 points at the second) would produce it. What it does establish is that the kernel stack garbage is downstream: the first thing to go wrong is visible in ring 3, one instruction into a new thread.

Two probes for the user-side sign, and what they did not find

Both lived in the tree only for the measurement; the second is kept as .boot-evidence/probe-thread-stack-v2.diff.

• Is a new thread's stack top a frame a live sibling also uses? Recorded at clone and compared across the thread group. Zero hits. One lesson from the first run of it: a probe line at WARN makes the gate fail every boot as kernel_reported_problems - eleven of twelve "failures" in that run were the probe's own lines. Probe at DEBUG or at ERROR only for what should fail.
• Is a thread entered from its initial context after it has already run? Checked in hw_task_load_cpu_state: rsp and rip still the clone values, and the word at the stack top already the return address __clone pushes. Ten boots (probe-20260911-130736, every log kept): one hit, boot 5, pid 0x55 on its second entry. That thread did not crash and exited 0 - a thread truly restarted there would have taken the return address as its argument and faulted exactly as the signature does. So that load was most likely never returned to, and the mechanism is still not known. ctx is written in only three places: preemption in hw_schedule, and fork and clone.

The family recurred once more in the H-007 series with the same instruction (0x405b72 in that build, the same start as before) and the same panic.

The exit switch ran with interrupts on (fixed 2026-09-11)

What the probes above were circling. hw_task_exit chooses next, sets it RUNNING, marks it on_cpu and makes it the core's current task - and then keeps running the dying task's code for a while: address-space teardown, the process reference, the locks those take and release. Only after that does it jump into next.

If a timer interrupt lands in that stretch, hw_schedule sees next as the current task and does what it does for any preempted task: saves the interrupted frame as next's context, marks it READY and on_cpu = 0. That frame is the dying task's, on a kernel stack already parked for release. Another core then picks next up and resumes the dying task's exit code on that stack, while the first core's drain frees it. Every piece of the four-worker family fits: "this task's stack is the free-page poison", kernel frames made of ASCII, a core whose current task is a slot already reclaimed as SETUP, and - once - a running -> running transition by hw_task_exit.

The one question was whether interrupts could be on there, since syscall clears IF. They can: a task killed out of a wait that did sti; hlt reaches the exit with the flag still set. A probe at the switch counted 4 per boot, every one a process ended by SIGKILL or exit_group while blocked.

Gated as a mechanism, because the crash cannot be produced on demand: a must-be-zero counter, exit_switch_irq_on, on the [TASKS] MUSTBEZERO line and asserted by the gate. Red first - task_exit_switch_irq_on=4 on the unchanged kernel. The fix is one cli before the choice; nothing below turns interrupts back on, and the iretq into next restores its own flags. Counter 0, check.sh all green, twelve boots 12/12.

What is not yet shown: that this was the cause of the four-worker family. That family ran about one boot in eight to ten, so twelve clean boots is consistent with it and proves nothing about it. The counter proves the window is closed and will say so if it reopens; the series from here on will say whether the crashes stopped.

One slip on the way, recorded because the file already warns about it: the first build of the probe had a syntax error, .c5red.sh printed build-rc=1 and booted anyway, and twelve boots measured the previous kernel. It stops on a failed build now, and checks that the kernel image is newer than arch_hw.c.

The four-worker family recurred after the exit-window fix (2026-09-11)

The section above said the exit-window fix was not yet shown to end this family. It did not end it. Boot 7 of the series that verified H-009 (.boot-evidence/fail-20260911-154006-boot7.log) has the whole signature: THREADS after THREADS_STAGE1_OK, the unhandled write at rip=0x405b72 in musl's start, then "this task's stack is the free-page poison" and the machine stopped. exit_switch_irq_on was zero on that kernel.

So the window was a real defect and stays closed, and it was not the cause of this family - or not the only cause. What is still known about the mechanism: a new thread's first instruction finds a return address where its argument should be; no live sibling shares its stack frame; once, an initial context was re-entered without the thread crashing. The family is open again in the review tracker.

The gate that hung for 48 minutes (fixed 2026-09-11)

A boot in a probe run held the whole series for 48 minutes on a guest that had panicked. The wedge report taken from the still-running emulator had every core in the panic, fault or serial path. wait_for and the wedge report are both bounded, which is why the cause took a second reading to find: it was the loop underneath them.

The serial pump read the socket until recv raised BlockingIOError - until the guest went quiet. A guest faulting inside its own panic path reprints trap lines as fast as the port carries them, so the pump never returned, and the deadline and the silence budget, both checked by its caller, never ran.

drain_available hands chunks on for at most 0.25 s and returns; what is still waiting is read on the next call. A module-level self-test feeds it a socket that is never empty with a clock that moves 0.1 s per read, and it must stop after a few chunks. Validated three ways: the gate compiles, its self-tests pass, and a copy with the budget check removed hangs at import (killed after ten seconds). The series that verified it included a crashed boot (.boot-evidence/fail-20260911-162643-boot12.log) that the gate ended in about a minute.

The probe that hid the defect it was looking for (2026-09-11)

A probe for the four-worker family recorded, at clone, the frame behind each new thread's stack top; counted how often a thread was loaded from its initial context; and printed one line at a probed thread's ring-3 fault saying which of three stories it was - the stack page replaced after clone, the thread started twice, or another thread writing its stack.

It never printed that line, because with it in the kernel the crash did not happen: 24 boots, then 36 more with a quieter version that logged nothing on the normal path. Without it, on the same kernel, 36 boots gave two crashes with the full signature (probe-20260911-174620-boot1 and -boot35: rip=0x405b72, va=0x406f00). Seventy clean boots at a rate of one in eighteen would happen by luck about 2% of the time - (17/18)^70.

That is a result rather than a failure. The quiet probe did two things on the path a crash needs: it added 28 bytes to every task, and - when a thread was loaded with its initial context - it walked the page tables to read the word at the stack top. Logging was not the perturbation. Slowing a thread's first start is enough to close the window, which puts the defect there and not in exit or in reclaim.

Code in the kernel cannot observe this without changing it. The next step is to look from outside: have the gate ask the QEMU monitor for every core's state at the moment a THREADS fault is reported, the way wedge_report.py already does for a silent guest.

Sharpened, and why in-kernel probing stopped (2026-09-11)

A probe that runs only at the ring-3 fault - so it cannot touch the window before it - reproduced the family (four in thirty-six) and printed nothing: the faulting thread never reaches hw_fault_kill_current_user. Reading the two traps that arrive together settles what is happening.

• The thread's fault is a write to a text page: COW_FAULT va=0x406f00 rip=0x405b72, musl's start doing lock cmpxchg %edx,0x10(%rdi) with rdi pointing inside __clone (0x406cd1). A new thread's argument pointer is a code address, not its stack - the sign recorded above.
• On another core, at the same moment, task 0x8 is entered with a garbage context: rip=0xffffffff, cs=0, and rsp/ss that decode as ASCII (TMP., ES.TXT) - file-name-buffer bytes. A task's saved registers, or the kernel stack they sit on, were freed and handed out as a file buffer and then scheduled. That is the halting free-page poison panic.

Both point at the same window: a thread's first schedule. That is exactly where the earlier probe did its one piece of work (a page walk when a task is loaded from its initial context), and slowing it there was enough to make the family vanish for seventy boots - so the defect is in context save/restore around a thread starting, not in exit (the interrupt-window fix, real, did not touch it) or in reclaim.

Why the investigation stops here rather than guessing. Every in-kernel probe tried changes the timing enough to hide the defect - the family runs about one boot in twelve to eighteen and disappears under any added work on that path. A fix written without a confirmed mechanism would be indistinguishable from the probe: it would make the crash rarer and prove nothing. The next tool is external: have the gate ask the QEMU monitor for every core's registers and stack at the instant a THREADS fault is reported, the way wedge_report.py already does for a silent guest - observation that adds no guest-side work. Kept apart from the review findings, which are all closed; this one is not.

Observing the four-worker family from outside (2026-09-11)

Since every in-guest probe masks this family, the gate now watches the serial stream for its marker - free-page poison, or the frame-level POISON_BROKEN, which appear only when a page was reused while still mapped, and never on a healthy boot (the null-deref svc-crash fault every boot carries is deliberately not a trigger). The instant the marker appears, and once per run, it asks the QEMU monitor for every core's registers and frame walk - the same wedge_report.py used for a silent guest - and files them in the summary's wedge_report= field, tagged THREAD-FAULT.

Because the poison panic parks every core, the snapshot is each core essentially at the fault, not the parked hlt state 45 seconds later that a timeout-driven report would show. It adds nothing to the guest: the one thing that reliably changes this family's timing is guest-side work on the thread-load path, and a monitor read is outside the guest entirely.

thread_fault_signature is a pure function with self-tests, including one that a detector keyed on the benign fault would trip. Verified: 24 boots through the changed gate were all green (no crash this run), so the snapshot has not yet fired on a real fault; the detector's self-tests are the standing proof, and it captures on the next crash.

Next, when a snapshot is in hand: the faulting thread's registers, and which task each core was running, at the fault - enough to say whether a sibling was mid-context-switch on the freed stack, without a single guest-side instruction.

The four-worker family, found and fixed (2026-09-17)

Closed at last, and the shape of it was not where three sessions of reading had looked. It is not the exit teardown freeing a stack, not the kstack drain, not reclaim. It is a task that runs on a core while its scheduler state says READY.

The reproducer that broke the stalemate. Every in-kernel probe masked this family because any added work on the thread-load path widened the window shut. The way past that was not another probe but a reproducer: musl_threads.c wraps its four-worker create/join round in a loop, THR_4WORKER_REPS (one by default, so the boot gate is unchanged; built at 30 for the hunt). Repeating the crashing path faithfully - not adding unrelated work - took the rate from about one boot in fifteen, and maskable, to two in five. From there the mechanism was caught in an afternoon instead of chased for a session.

The three detectors, and what each said. A guard in hw_free_kstack_pages that panics if any core's syscall_kstack_top/rsp0 is inside the range being freed; a guard in hw_task_release that panics if any core still has the slot as current_task; and the pre-existing hw_task_load_cpu_state cr3 guard (address space freed while still schedulable). All three fired on the same event: a core running a thread whose slot was being released and torn down under it, consistently ready_by=futex_wake. The clean caller, printed on the cores-quiesced path in hw_panic_cpu_summary rather than the interleaved raw one, was hw_task_exit releasing the dying slot while next == dying - the scheduler had picked the exiting task as the next to run.

The mechanism. A task blocked in hw_futex_wait is BLOCKED and still on_cpu until its first reschedule. A FUTEX_WAKE in that window sets it READY, and because it is still on its core it resumes in place - the hlt loop breaks and it keeps running - without going back through hw_schedule, which is the only thing that would have set it RUNNING again. So it runs with state READY. When it then calls hw_task_exit, the exit clears its on_cpu before it switches away (it keeps executing on its own stack until task_enter), and a READY, !on_cpu task is exactly what hw_pick_next returns - to this core as next == dying, or to another core outright. Two cores on one task, one of them freeing its stack, its address space and its slot. That is every signature this family ever produced.

The fix. One invariant, reasserted where it was broken: a task running on a core is RUNNING, never READY. hw_task_exit sets the exiting task RUNNING under g_sched_lock at entry, so it is never a scheduling candidate while it tears itself down. Verified with the reproducer: at THR_4WORKER_REPS=30, before the fix the family hit most boots and the guards fired; after it, 48 boots, zero crashes, zero guard fires - the guards going silent is mechanism-level proof, not a ratio. The hw_task_release guard is kept as a permanent gate: it is a cheap eight-core scan, it never fires on a healthy boot, and this class had just failed the gcc/Release CI smoke (address space freed while still schedulable, 2026-09-17), so a regression of it should stop the machine with the culprit named rather than surface as a one-in-fifteen wedge again.

Found in passing, fixed separately: the futex waiter table had a slot-index ABA of its own (H-007's class). A waiter records its task's slot; hw_futex_wake woke g_tasks[slot] after only a state == BLOCKED check, so a waiter reaped and its slot reused could have a wake land on the new tenant. Waiters now record alloc_seq and a wake requires it to still match. Not the four-worker cause - that was the READY-while-running invariant above - but a real defect the hunt surfaced.

Status history

Moved verbatim from the status cell of docs/implementation_progress.md on 2026-09-29, when that table was compacted to one or two sentences per area. The table says where things stand; this is how they got there.

Boot Repeatability (as of 2026-09-29)

24 boots clean out of 24, from a long-standing 1 in 8. Six defects fixed: three were in the diagnostics rather than the kernel they watched, and three came from CI and nightly logs - a copy-on-write fast path deciding on a fact its compare-exchange could not guard, a kernel address handed to ring 3 as AT_BASE, and a panic that stopped one core instead of the machine, which is what separated every silent wedge from its cause. 24/24 is a good number and not a proof; what is stronger is that two of the three are asserted deterministically and the third turns a silence into a named panic

Bootloader Progress

Status: Completed (Phase 4 boot-to-CLI verified) Last review: 2026-08-01

Implemented

• UEFI entry path and protocol wrappers in boot/uefi_main.c and boot/uefi_protocol.c.
• Firmware discovery helpers (ACPI/SMBIOS and boot metadata) in boot/uefi_firmware.c.
• Memory map normalization and ExitBootServices retry hardening in boot/uefi_memory.c and boot/uefi_boot_handoff.c.
• Boot structure allocation fallback (AllocateAddress -> AllocateAnyPages) with cleanup-aware error handling.
• Kernel image planning with ELF64 primary parser and PE32+ fallback (include/vibeos/bootloader.h, boot/bootloader_core.c, boot/uefi_pe_loader.c).
• Real kernel load path from EFI filesystem (boot/uefi_file_io.c, boot/uefi_main.c) with primary/fallback file paths.
• Segment layout validation before load (file range, size consistency, overlap checks) in boot/uefi_pe_loader.c.
• Strict freestanding UEFI build path:
  • bootloader no longer links libc or embedded kernel objects
  • PE32+ fixup validates Subsystem=10, x86_64 machine type, non-stripped relocations, stack/heap reserve, and .reloc directory
  • BOOTX64.EFI is accepted and started by OVMF.
• Real EFI media pipeline in build artifacts:
  • artifacts/efi_root/EFI/BOOT/BOOTX64.EFI
  • artifacts/efi_root/EFI/BOOT/VIBEOSKR.ELF
  • manifest + SHA256 integrity entries (cmake/create_boot_image.cmake).
• Boot diagnostics expose phase tokens: BL_EFI_OK, BL_FS_OK, BL_PLAN_OK, BL_LOAD_OK, BL_EBS_OK, BOOT_OK, CLI_READY.
• OVMF smoke automation:
  • Linux required gate (scripts/qemu-smoke-ovmf-linux.sh)
  • Linux/WSL boot-to-CLI gate (scripts/qemu-smoke-cli-linux.sh)
  • Windows smoke runner (scripts/run-qemu-ovmf.ps1).
• CI gate model:
  • required: host tests + OVMF boot smoke + boot-to-CLI smoke
  • informational: direct-loader probe (-kernel) for compatibility telemetry.
• Host-side parser regression coverage (PE + ELF) in tests/kernel/kernel_tests.c.
• May 2 (commit 630d94c): Fixed serial I/O privilege detection for Clang inline asm (changed uint16_t cs → unsigned long, constraint "=r" → "=&r" with memory clobber) in kernel/arch/x86_64/serial.c.
• May 3 (commit 0d4ba7f): Phase 4 security discovery infrastructure:
  • uefi_firmware_discover_security_settings() in boot/uefi_firmware.c discovers Secure Boot and Measured Boot capabilities
  • Firmware tags (types 3-4) created with Phase 4 default values
  • Integration in PHASE 2 (discovery) and PHASE 4 (application) boot stages
  • Security telemetry logged before kernel handoff
• May 10 (commit 6391147, 29b81db): Fixed UEFI bootloader generation for Clang on Linux:
  • Added -fPIE and -fno-strict-aliasing compile flags for UEFI compatibility
  • Linked against libc and clang_rt.builtins-x86_64 on Linux targets
  • Removed unsupported --subsystem=10 flag from GNU ld (objcopy handles PE subsystem during conversion)
  • Added fallback support in objcopy conversion: efi-app-x86_64 (primary) → pei-x86-64 (fallback 1) → pe-i386 (fallback 2)
  • BOOTX64.EFI now generates correctly with Clang Release builds on Linux CI

Final Bootloader Checklist

• Build pipeline emits bootloader.efi, vibeos_kernel.elf, legacy vibeos_boot.img, and EFI media root.
• EFI media contains canonical fallback path EFI/BOOT/BOOTX64.EFI and kernel payload VIBEOSKR.ELF.
• Bootloader loads kernel from filesystem (no fixed hardcoded load-address dependency).
• Segment plan enforces structural safety checks before memory copy/load.
• OVMF smoke path and logs are integrated in CI artifacts.

Verified Evidence

• ctest --test-dir build-wsl --output-on-failure: 2/2 host tests passed.
• ./scripts/qemu-smoke-ovmf-linux.sh build-wsl BOOT_OK 60: passed via OVMF primary profile.
• bash scripts/qemu-smoke-cli-linux.sh build-wsl 90: passed, verified help, status, echo vibeos, and halt through the serial CLI.

Toolchain notes

• Clang UEFI images: resolved (2026-07-22). Previously the Clang bootloader.efi, produced by the ELF→PE objcopy path, was rejected by OVMF at LoadImage (EFI_UNSUPPORTED, last_phase=none) — Clang's .data.rel.ro/.rela.data.rel.ro layout did not survive the objcopy conversion. Fixed by giving Clang a native PE link path: compile the bootloader with --target=x86_64-unknown-windows-msvc (MS x64 ABI matches UEFI) and link with -fuse-ld=lld -Wl,-subsystem:efi_application -Wl,-entry:efi_main -nostdlib, emitting bootloader.efi directly (no objcopy). Also removed a spurious <stdio.h> include from boot/uefi_serial.h so the bootloader is fully freestanding. GCC keeps the ELF→objcopy path unchanged. Both toolchains are now verified booting to CLI under QEMU+OVMF and both are boot-gated in CI.

Future Hardening

• Phase 4.1: Secure Boot and Measured Boot policy path discovery via EFI GetVariable
  • Currently creates firmware tags with Phase 4 defaults (SecureBoot=0, MeasuredBoot=0)
  • TODO: Implement actual GetVariable calls to detect real firmware capabilities
  • Target: May 2026 sprint close
• Phase 4.2: Richer fault telemetry around boot failures (handoff errors, security policy rejections).

Next checkpoint

• Implement GetVariable integration for real Secure Boot detection in Phase 4.1.
• Start the next kernel/userland milestone on top of the verified boot-to-CLI baseline.

The console lock, and why the machine goes quiet

Status: the bound is in and the counter is gated. The svc-press failure is now understood well enough to describe, and is not yet fixed.

The one lock that cannot report itself

Every other lock in this kernel panics when its bound fires. This one cannot: a panic prints, and printing goes through the very lock whose state is in question. So it takes the lock anyway, records that it did and who was holding it, and lets the machine carry on talking.

That trades a correct line for a possibly interleaved one, and it is the right trade twice over. Interleaving is detected — interleaved_lines is the boot gate's first check, precisely so a garbled line is caught and named. Silence is not detectable at all, and it is the failure where every piece of evidence is missing rather than wrong.

[CONSOLE] MUSTBEZERO bad_unlocks=… stuck=… stuck_owner=… is the line; the gate fails on a non-zero count and on the line being absent.

What it explained

svc-press allocates 256 KiB at a time and touches every page. At a hundred and twelve blocks — twenty-eight megabytes, not the twenty this was written up as — the machine goes completely quiet.

Four explanations were excluded first: not a deadlock on hw_spin_lock (the bound was lowered to twenty million and still did not fire), not memory exhaustion (104,572 free frames down to 98,735 of 107,485, with reclaim never running), not reverse-map exhaustion (seven thousand nodes against two hundred and fifteen thousand), and no fault of its own.

Lowering this bound to ten million changed the machine from silent to talkative, and what came out was a hw_ctx_check report — cr3_by=, exe=, rip=0x0, cs=0x0, rflags=0x0 — a task whose saved context is zeroed, refused entry by the guard that exists to catch exactly that.

It came out interleaved, because taking a held lock mid-line is what this bound does. That is the cost, and it bought the first piece of evidence this failure has produced in its existence.

So the shape is: a task acquires a zeroed context, hw_ctx_check refuses to enter it and reports under the console lock, and the machine stops there — with the console lock held. Everything else then piles up behind it, which is why the symptom is silence rather than a panic.

The original wedge report said this and was not believed. It put CPU#2 and CPU#3 in hw_ctx_check and CPU#0 and CPU#1 at an address whose nearest preceding symbol was hw_task_slots — a function that returns a constant. hw_ctx_check was right; the other two are almost certainly the pause loop in vibeos_x86_64_serial_lock, which links early and therefore sits at a low address. The lesson CLAUDE.md draws about nearest-preceding-symbol naming cuts both ways: a name that looks absurd is worth discarding, and a name that looks plausible is worth checking rather than dismissing wholesale.

What is not done

Why a task's context is zeroed under heavy anonymous mmap. That is the actual defect and it is untouched.

And hw_ctx_check prints a dozen fields from the task table, including exe_path and vibeos_task_last_why(slot), while holding the console lock with interrupts masked. If any of those reads faults — plausible, since the task it is describing is already corrupt — the machine stops inside the critical section, which is exactly the observed state. Making the report safe to run against a task that is known to be broken is the next step, before the cause is chased.

The reporter that could not report

Written after the bound above found its first real failure, and after the tool built to explain it turned out to have the same defect it was looking for.

hw_lock_deadlock announced a stuck spinlock by calling serial_puts, which takes the console lock. Under svc-press the console lock is one of the jammed ones, so the core that had detected the deadlock sat down in vibeos_x86_64_serial_lock and the message never arrived. The wedge report caught it in the act: CPU#3 rip=0x4000cb5 hw_lock_deadlock.

A lock reporter that can only speak while the locks are healthy reports nothing on exactly the boots it exists for. It writes raw bytes now, taking nothing. The output can interleave, which is the correct trade for the same reason the console bound takes the lock rather than waiting: interleaving is caught by the gate's first check, and silence is not caught by anything.

What svc-press actually does

Not a wedge, or not only one. With the reporting unjammed the boot gate reports guest_still_talking for thirty-nine minutes with quiet_for=0: the machine emits 7.5 MB of hw_ctx_check dumps and never stops. Both verdicts have been seen from the same workload, and which one appears depends on whether the console lock jams before or after the flood starts. That is why this failure was written up for so long as "the serial log fills with binary" - it is not binary, it is one diagnostic repeating for ever, cut into fragments by cores writing over each other.

The repeated fragments are the tail of that dump, and they are not random: rax=0x10a030c050e07000, rbp=0x10a030c010e07200, rax=0x60f08010a030c050. The high nibbles step by 0x20 - 10, 30, 50, 70, 90, a0, c0, e0 - so whatever the failing context is being read from holds structured data, not the leftovers of a freed page. That is a different question from "a context was zeroed", which is what the earlier, garbled capture suggested, and both readings are recorded here because the difference decides where to look next.

Where this stands

The characterisation is much sharper than it was and the instruments now work, which is the whole of what this stretch bought:

• the console lock cannot silence the machine any more, and says when it was taken by force;
• the spinlock bound fires and can speak while the locks are jammed;
• the trap dump reports what it did rather than what the model proposed;
• an execve that fails names its reason.

The defect itself is not fixed, and it predates all of this. It is outside the memory-manager plan - it is not any of P0 through P7 - and what it blocks is narrow and stated in mm_swap_file.md: freed_anon stays zero because nothing else runs this machine short enough of memory to make reclaim evict a page.

C1's last two checks, and what measuring cost the plan

check-subsystem.py and check-blast-radius.py are the two C1 asked for and nobody had written. Both are wired into check.sh all, both are ratcheted at today's measurement, and both have been broken on purpose and seen red (scripts/dev/cases/core-contract.txt).

The interesting part is not that they exist. It is that each one contradicted the document that asked for it, on its first run.

check-blast-radius.py: the plan's progress metric was folklore

docs/core/ says, in three separate files, that blast radius is the real measure of this refactor — chosen precisely because line count had been the stated criterion twice and failed twice. And the table it gave was:

a filesystem — 1, vibeos_storage_register a block driver — 1, vibeos_blk_register everything else — arch_hw.c

That table was written from the existence of two registries, not from a measurement. Here is the measurement:

Nothing is 1. The floor is 2.

The four filesystems were never evidence of anything

The claim rested on "four filesystems arrived without their layers being touched". They did not. ext2, ntfs, exfat and iso9660 are named directly in g_probes[] in kernel/fs/storage.c, each with a mount wrapper beside it and a member in vibeos_volume_t. vibeos_storage_register has one caller in the whole tree, and it is FAT.

And the registry buys nothing yet, which is the finding worth keeping

FAT — the one driver that does use the seam — measures 4 as well. Somebody still calls the register function from arch_hw.c, declares it in arch_x86_64.h, and mounts through it in io_bringup.c.

A registry whose members still need a bring-up call has the same blast radius as no registry at all.

That is a much sharper target for C6 than "move code out of arch_hw.c", and it was not sayable before the number existed.

The check corrected its author too

FAT was hand-measured at 2 while the check was being written, by grepping vibeos_x86_64_fat_vfs — which misses _ops and _register_driver, the two symbols that are the seam. The first run said 4 and the declared number was wrong. The same run also caught a matcher bug: a shared symbol prefix is not a module, and vibeos_x86_64_fat_ matches both the VFS driver and the raw FAT reader, two different things, giving a radius of 7 for a module whose answer is 4. The matcher is a regex per point now.

check-subsystem.py: one property was already perfect, and three are debts

50 modules, four mechanical properties out of the seven in docs/core/architecture.md.

exported_state=0 is worth stating rather than assuming. It is the one part of the module contract this tree satisfies everywhere without having been told to, and it is the property the other three rest on. It is also measured with nm rather than a regex — lowercase symbol class is a static, uppercase is not, and the linker's opinion is the only one that counts. That is why its sabotage case is the one worth having: a property green across the board is indistinguishable from a property nothing measures.

The lock property had to be narrowed, and the first version was noise

It began as "does the module register a lock", which is what architecture.md lists. That reported 29 of 50, including blkdev.c — which holds its own lock. A detector that flags a module doing the right thing is a detector people learn to ignore, and this file has already recorded one that reported 3,019 use-after-frees in a boot with none.

Narrowed to the shape that actually cost months — mutable file-scope state and no mention of a lock anywhere in the file — it reports 3:

• kernel/fs/vfs.c — the mount table
• kernel/mm/anon.c — a clock hand
• kernel/sched/forkguard.c — the fork budget

None of these is claimed to be a defect; each may be correct under a caller's lock. They are three places where "is this serialised?" has no answer in the file. backing.c was exactly this shape, was correct for months on the accident of having one caller, and the second caller returned one file's pages under another file's key.

Two of the seven parts are deliberately absent

The must-be-zero counter is C2's step 3, which adds the counters before the check that demands them. Writing it now would ship a check red against thirty modules, and this project already knows what that produces: check-mm-layering.sh sat failing and unread for a phase. An init that names its reason stays in review, and the script says so instead of implying coverage.

What this does to the plan

Three documents were corrected rather than appended to: README.md, architecture.md and invariants.md all claimed a radius of 1, and phases.md's C1 step 2 asked for a baseline it had already guessed wrong.

The pattern is the one this project keeps producing and has now caught in its own planning documents: a number that is written and never read. The plan named blast radius the progress metric, gave it a value, and nothing measured it for the entire time it was the metric.

C1: the checks that watch the contract

First instalment of the core plan's C1. Two checks now run in check.sh all that did not, and the first finding was about the plan's own author.

check-reachable.py was written and never wired in

It was committed two days before this entry and check.sh never called it. That is "configured and consulted by nobody" — the defect docs/core/ names as the one this project produces most often, committed inside the document that names it, by the person who wrote that sentence down.

A check nothing runs and a check that passes are the same thing from outside. This is the fourth instance recorded here and the first where the mechanism was a check rather than a kernel feature, which makes it worse: the whole value of a ratchet is that somebody would notice it going red.

It reports unreached=12 baseline=27 and runs on every check.sh all now.

check-chokepoints.py, and how measuring changed its design

The plan specified it as: each security check declares how many call sites it has, so that a second one is noticed — the failure where a handler is copied, its guard is copied, and the two drift. C4 moves 4,169 lines of syscall handlers out of arch_hw.c, which is exactly that operation.

Counting the real numbers changed the shape of the check:

hw_user_range_ok has forty-four because every syscall taking a user pointer validates through it. For that guard the dangerous direction is the count going down: a syscall that quietly stops validating is a hole, and it reads like a simplification. Nothing else in the tree would see it.

So the check asserts the declared number in both directions. It is not a prohibition — adding a syscall legitimately moves the count, and the fix is to edit the number in the same commit. Same rule this project already applies to the mm-layering allowance: raise a limit as a decision, not as a reflex.

It caught its author first

The declared counts were set from grep over kernel/arch/x86_64/*.c; the check walks all of kernel/. Two of the five numbers were wrong on the first run — hw_user_range_ok also has sites in linux_socket.c and linux_signal.c, and hw_task_alloc_guarded had one fewer than assumed. The numbers are the measurement now.

Sabotage, both directions

unmodified                              chokepoints=ok watched=5
one hw_user_range_ok site removed       FEWER than declared   → red
a second hw_signal_permitted site       more than declared    → red
restored                                chokepoints=ok watched=5

Cases in scripts/dev/cases/core-chokepoints.txt, including the honest failure mode of every ratchet here: editing the declared number to match instead of looking at what moved, which turns the check off for that guard and looks green.

What it cannot judge

It counts textual occurrences, not calls: a name in a comment counts, a call through a function pointer does not. Every guard here is called by name today. Stated rather than worked around, for the same reason check-reachable.py asks "is this named anywhere" instead of building a call graph it would have to fake: a confidently wrong answer is worse than a coarse one.

Still to come in C1

• check-subsystem.py — the seven parts of a module, ratcheted.
• check-blast-radius.py — files touched to add a filesystem (1), a block driver (1), a character device, an input device, a network interface, a display, a syscall, an ABI (arch_hw.c for all six). That table is the plan's real progress metric and it does not exist yet.

C2 opens by finding that its own strongest word meant nothing

C2's objective is that every module says whether it is broken. Step 1 is to enumerate what exists, and the enumeration produced a defect before it produced a list.

The count

MUSTBEZERO is the strongest claim this kernel makes about itself. The word means the boot gate fails if the number is not zero — that is the whole contract, and it is why a reader trusts the word instead of checking.

[GUI] MUSTBEZERO guard_broken= did not have it. Printed on every boot for the whole of C0, read by nobody.

Who wrote it, and why that is the point

It was added during C0's GUI work, in the session that had just quoted CLAUDE.md's rule at it:

A line in the serial log is not a check. The ring-3 ABI self-test printed "abi: mmap/mprotect/munmap wrong" for an entire session while the boot gate stayed green.

Knowing the rule, having just written it down, and walking into it anyway is the argument for mechanising it. Judgement did not survive one session.

Why neither existing check-on-checks saw it

Two already watch the checks, and this fell exactly between them:

• check-counters-produced.py asks whether anything can move a reported counter. g_gui_guard_broken has a ++, so it was satisfied. It exists because VIBEOS_BLK_TIMEOUT was defined, printed, asserted and produced by no driver — the mirror image of this defect.
• check-assertions-covered.py matches every reason= the gate can emit against the sabotage cases. guard_broken never appeared in a reason=, because that is precisely what was missing, so there was nothing to match.

A counter that is produced and never asserted satisfies both. That is the third axis, and check-mustbezero-asserted.py is it: every MUSTBEZERO <name>= string literal under kernel/, against every such pattern the gate searches for. It reported unread=1 on its first run against the real tree — not a simulation, the state the repository was already in.

It cannot tell whether the gate, having matched a name, compares it to zero. That is one line below the regex and stays in review; the file says so rather than implying coverage.

What was fixed, and what was recorded instead of fixed

The gate asserts gui_guard_broken now, and both cases in gui-guard.txt have been run. Writing one guard word of the back buffer as zero took the boot from status=pass to reason=invariant_failed:gui_guard_broken=1 - red for the right reason, and counting the one word that was broken rather than the whole buffer. Deleting the assertion again, with the kernel still printing the line, takes check-mustbezero-asserted.py red; that case did not need simulating, because it was the state the repository was already in.

Recorded and not fixed: the report line is assembled from twelve separate serial_puts calls with no serial_lock around them. By this project's own rule that is twelve critical sections, not one line, and CLAUDE.md records what it costs — a hex field cut off after its 0x, and two investigations into crashes that were a marker cut in half. It has not misread yet because the report runs late, when little else is printing. That is an accident of timing, not a property; it is the same sentence already written here about a page cache with one caller. Bracketing it is a change to the log path and belongs with the rest of C2, not with an assertion fix.

What C2 still has to do

The 33 tags against 6 must-be-zero lines is the real gap, and step 2 is unchanged: for each module with none, name the harm, add the counter, print it on the module's tag, assert it, and demonstrate it can be non-zero before concluding anything from a zero. check-subsystem.py gains the must-be-zero property at the end of that, not before it — a check shipped red against thirty modules is the state check-mm-layering.sh sat in for a phase.

Second finding, and this one had a comment vouching for it

hw_cache_audit compares every resident page-cache page against the bytes its file actually holds, and reports cache_audit_checked / cache_audit_changed on the [EXEC] line. It runs on every boot. On the boot this was found it compared 1821 pages.

The boot gate did not read the result — and the comment above the function said:

"Reported as a count, and the boot gate asserts it is zero."

A guarantee documented in the source and provided by nobody is worse than an undocumented gap, because the sentence is what the next reader trusts instead of checking. That is a different defect from the GUI counter found an hour earlier: that one was silent, this one was vouched for.

Why the check added an hour earlier could not see it

check-mustbezero-asserted.py knows counters that carry the word MUSTBEZERO. This one did not carry it. So the check written specifically for this shape, against a tree that contained a second instance of the shape, reported ok.

That is worth stating plainly rather than filing as bad luck: the check mechanises a word, not a property. A counter opts into the guarantee by spelling it, and one that never spells it is exactly as unwatched as before. The fix for this instance is to spell it — cache_audit_changed carries the word now, so both the check and the gate hold it — but the general gap remains, and naming it is more useful than pretending the check closed it.

Why the harm is the worst class this project has had

Once a read-only image page is mapped from the cache instead of copied, one frame is the text of every process running that program. A stray write reaches all of them, and surfaces as an unrelated program misbehaving far from whatever wrote. That is the family that took four attempts and produced three confident wrong answers.

The audit compares against the file, not a checksum taken at fill time — a checksum only proves the bytes have not changed since the kernel last looked.

What was asserted, and the second assertion that matters more

Two, not one:

• cache_audit_changed must be zero.
• cache_audit_checked must be non-zero.

The second is the one this project has been taught to add. An audit that examined nothing reports changed=0, which is byte-for-byte the healthy answer; VIBEOS_BLK_TIMEOUT was asserted for months in exactly that state. Both were sabotaged and both went red on metal:

The third is the interesting one. The check does not fail when a counter leaves its view — it just stops counting it. The gate is what covers that here, and that asymmetry is recorded in exec-cache-audit.txt rather than smoothed over.

And a note on writing this file

The case file was first written with ran: yes on all four cases before any of them had been run. They were then run, and two of the four descriptions turned out to be wrong: case 3 does not fail the way it was written, and case 4 proves something narrower than claimed. Both are corrected in place. The sequence is the one this project keeps insisting on and it keeps being necessary: write the sabotage first, run it, then write the sentence it justifies.

Step 2 begins: the keyboard, and a counter that cannot report its own worst case

The sweep before this one is worth recording because it came out negative. 254 name=0x fields are printed under kernel/; 100 of them are not read by the gate. That looks like a hundred defects and is not. Most are witness fields - rax, pml4, fault_addr, freed_by, oor_lba - which exist to say what when a count says how often, and asserting them is meaningless. Several others carry comments stating deliberately that they are not must-be-zero: rmap_untracked (a frame outside its region is legitimately unmapped), rmap_audit_torn (a fact about concurrency, not a defect).

Building a check on that list would have repeated the mistake the lock property made an hour earlier, at three times the scale. A check whose first run reports a hundred things is reporting its own design.

One idea from that sweep died on inspection, which is the better outcome than dying after being committed. The gate detects a TLB shootdown timeout by matching a log string, not the counter, and log_dropped is printed and unread — so "a dropped log line can hide a real timeout" looked like a strong finding. It is false: hw_log_emit writes straight to the serial port and the portable ring is a separate copy, so a drop there hides nothing from the gate. And a ring that overwrites when full is behaving correctly, so asserting log_dropped == 0 would have been wrong twice over.

The keyboard, which had no counter of any kind

Two bare returns dropped keystrokes: the IRQ path when the ring is full, and vibeos_x86_64_keyboard_inject when the boot self-test's script does not fit.

They are different harms and are counted differently.

kbd_dropped — reported, not must-be-zero. A full ring under a fast typist is how a ring behaves. It is printed because nobody types on a CI boot, so a non-zero value there means something is injecting into the console.

kbd_inject_truncated — must-be-zero, and the reason is already in the source. The comment above KBD_RING records this happening: the ring was 512, the self-test script outgrew it, and the symptom was the last command silently never running, which looked like the shell hanging rather than like input being dropped. The ring was enlarged. Nothing was added that would say so next time.

A truncated injection means the self-test checks a prefix of what it meant to check and passes — the seventh instance of this project's "right about the outcome, wrong about the mechanism", arriving through the one path where the input is the test fixture.

And the honest limit, which is the part worth keeping

The plan says: demonstrate the counter can be non-zero before concluding anything from a zero. Two demonstrations were run and they establish different things.

Forcing the accessor to return a non-zero value took the boot to reason=invariant_failed:kbd_inject_truncated=3, with the value 3 carried intact through accessor, report line, regex, assertion and reason. That proves the plumbing.

Shrinking the ring to 4 — the real harm at full strength — did not produce a non-zero counter. The boot failed earlier with reason=missing:CLI_READY, and none of the late report lines printed at all. With no input the machine never reaches the point where it reports.

So: this counter is printed by a path that a working console is a precondition for. That bounds what it can catch, precisely:

• a partial truncation, where enough script survives to reach the report — the case that once looked like a hanging shell, and the case the counter exists for — is caught.
• a total loss of input is caught by CLI_READY instead, loudly.
• the gap between them is untested, because the script length and ring size are both fixed and every ring small enough to truncate is small enough to break the boot first.

That last line is recorded as untested rather than counted as covered. It is the same distinction the AHCI cases already carry between "no case exists" and "the case exists and this environment cannot tell".

The keyboard counters made the plan's headline metric worse, and the check said so

check-blast-radius.py, written the same day, went red on the keyboard commit.

input device: 2 -> 4. Giving the keyboard its first must-be-zero counter cost two files that have nothing to do with keyboards: an accessor declared in arch_x86_64.h, and a print in kmain.c. Total across six points: 21 -> 23.

That is a structural regression caused by an observability change, caught within hours by a check written to measure exactly that, in the one direction nobody would have looked — the change made things better by C2's measure and worse by C1's.

The finding underneath it

This is not a keyboard problem, and it does not go away by being careful.

Observability itself has a blast radius here, and it is 2 per module.

There is no seam a module registers its statistics into. Every counter C2 adds — and there are roughly thirty modules left — pays the same two files, so C2 as planned would raise the total by about sixty and hand C6 a worse tree than it found.

The number is raised to 4 with that argument recorded in the check, which is what the plan asks for: a radius going up needs an argument, not an edit. A stats registration seam takes this row back to 2 and takes the next thirty counters with it, and that now has a measured justification rather than being a matter of taste.

And a defect in all four checks of this family

The failure arrived as VERDICT=RED with no reason beside it: the blast-radius= line was missing from the summary entirely.

check.sh reads each check with | tail -1, and all four of these checks printed their advice line after the verdict. So on failure the summary got the advice and the verdict vanished — the line that matters printed and not read, for the fourth time today, this time in the tooling built to stop that.

check-chokepoints.py had the same order from the day it was written and had never shown it, because it has never gone red inside check.sh. Fixed in all four: advice first, verdict last, and confirmed by breaking a baseline and watching tail -1 produce subsystem=FAIL.

C4 - one operation vocabulary, and the Linux ABI leaves arch_hw.c

Status, 2026-09-21: stages 1, 3, 2a and 2b done. The plan (docs/core/phases.md) is the authority on intent; this file records what was built, what it measured, and what it found on the way.

Stage 1: the vocabulary, its declarations, and their enforcement

• include/vibeos/abi.h declares every kernel operation once, with the checks that apply to it, in an X-macro list. The enum, the name table and the check table cannot drift, and a line without its checks does not compile. It is named op, not syscall: the dispatcher C3 deleted had left its own vocabulary behind (syscall.h, syscall_abi.h, syscall_policy.h, 1,023 lines nothing used), which was removed on 2026-09-20 - one vocabulary now.
• kernel/abi/abi_linux.c is the Linux ABI as a translator: a constant number -> operation table plus clone()'s decision by flags (which is why classify takes the first argument). The ABI is bound to a task in hw_task_alloc, the one place a slot is claimed, and read from the task.
• scripts/dev/check-syscall-checks.py holds each declaration against the handlers' call graph, in both directions. It is reachability, not proof: it catches a check that disappears, not a check applied to the wrong pointer. Its first run corrected three of my own declarations (exit, exit_group, prctl touch user memory).
• Found and removed on the way: vibeos_linux_translate_syscall was called on every syscall and its result stored in a variable nothing read, and a [COMPAT] translated= counter printed a number that meant nothing.

Stage 3: 4,000 lines leave arch_hw.c

arch_hw.c went from 12,174 to about 7,800 lines. Its Linux-facing handlers and the helpers only they use now live in kernel/abi/linux/:

How it was cut. Not by line range: the stretch was interleaved with architecture that has nothing to do with Linux - the copy-on-write fault handler, the TLB shootdown, the crash dumper, task lookup. A throwaway tool parsed the file into top-level items, built the reference graph, and moved a handler together with every helper only handlers reference (an item moves iff everything that references it moves). Everything else stayed and became a named dependency in arch_hw_internal.h - 67 declarations and 29 macros and types, which is the honest size of the seam. Being driven by the compiler, the first pass turned up four mistakes in the tool itself (types named by shared declarations, static inline helpers, prototypes of moved symbols, and section banners that travelled with the first item after them); all four are fixed and none is in the product.

Two metrics moved, both honestly.

• input device went 4 to 5 the moment the handlers moved, because fs.c named the keyboard and framebuffer directly - a dependency that had been invisible inside one file. It is 4 again: the console is now two functions the architecture supplies (hw_console_getc, hw_console_echo).
• syscall is 6 (1 before C4, 4 after stage 1). The case and the handler are now two files and the handler needs a declaration between them. That is the price of the cut and it is meant to be temporary; stage 2 exists to remove it.

The check this phase added, and what it found

scripts/dev/check-sabotage-anchors.py verifies that every sabotage case still has an anchor to break. Moving 4,000 lines makes stale anchors certain, and sabotage.py only reports one when somebody runs it. First run: 20 cases with nothing left to break. Four were this phase's (two anchors that moved, two written against names renamed in the same change and never run - now run and red). Sixteen were stale before C4 began - and are repaired: mm-vmspace (seven), threads (two), tlb-shootdown, stress, journal, ahci, ring3-fault, services, storage. Each was re-run, which found three that mattered more than their anchors (a shootdown counter that stopped isolating fork, an untested stale-TLB guard, an AHCI sabotage OVMF had already defeated); see check-sabotage-anchors.py. Unresolved is now ratcheted at zero.

Not done

• The linkage from linux_internal.h to arch_hw_internal.h is a relative include. The Linux layer still reaches x86-64 objects (a task, its address space, its descriptor table) directly; abstracting that is the day a second architecture exists, not before. (Done earlier than that, on 2026-09-29, for a different reason: host tests and a second personality. The include is gone; see docs/abi/ phase A2 and include/vibeos/ksvc.h.)

Stage 2b: the pointer arguments are declared in the row (2026-09-21)

• A row's fourth column is NOPTR or PTRS(...): which arguments are user pointers, how long, read or write, optional, and - for a request code that decides whether the argument is a pointer at all (ioctl, prctl, arch_prctl, netctl) - the value of the argument it depends on. vibeos_ptr_t (abi.h) holds it; the constructors (OUT, IN, OUT_BUF, IN_VEC, *_OPT, *_IF) are in linux_internal.h.
• The dispatcher's check_pointers validates them before the handler runs and answers -EFAULT. 22 rows carry descriptors and about 30 handler checks are gone. The registry refuses a descriptor that names an argument the call does not have.
• hw_user_range_ok has one call site (linux_user_ok, dispatch.c); it was 46. check-chokepoints.py reports 4 for it (definition, two declarations, that call) and watches linux_user_ok at 15, where the old "a syscall stopped checking" alarm lives now.
• What stays in the handlers (12 sites), and why each is not a descriptor. Each was weighed for moving; futex was the one that could, and did (a descriptor can carry its own error and a mask on the argument that selects it). The rest:
  • an iovec element's own base (2): the descriptor would validate the array up front and the handler would read it again later; a sibling thread can change or unmap it in between (H-020). The check has to be next to the use, so it stays.
  • readlink's length (1): it is min(buffer, link target), known only after the lookup. Declaring the whole buffer would answer EFAULT to a call Linux allows.
  • clone's stack (1): it is thread-creation policy with a diagnostic line, at an offset from the argument (child_stack - 8), only when the flags ask for a thread.
  • clone's two tid words and wait's status word (3): optional stores that are skipped silently when invalid, not refused. A descriptor refuses; these must not.
  • the signal frame and sigreturn (2): a stack pointer taken from the trapframe, not from an argument.
  • the kernel's own reads (3): a user string, the crash dump's two probes. No syscall names them.
• Error precedence changed, deliberately, and this is the price. A call that has a bad pointer and another error now reports EFAULT where the handler used to report the other one first: read on a bad fd with a bad buffer (was EBADF), getdents on a non-directory (was ENOTDIR), getcwd with size 1 (was ERANGE), pipe2 with a bad pointer and bad flags, sigaction with a bad signal number and a bad pointer, the ioctl cases for descriptors above 2. Linux itself mostly reports EBADF first; no program here depends on the order and the boot's ABI self-test passes, but it is a behaviour change and is recorded as one.
• Decision (2026-09-21): EFAULT-first stays; Linux's EBADF-first is not reproduced. Doing it would make the engine look up file descriptors - a filesystem dependency (the console's fd < 3, sockets) inside the one generic place - and would make every future row declare which check precedes its pointer. That is permanent surface for an order nothing here depends on. It is reversible: the choice lives only in check_pointers and in this note. Revisit if a real program relies on the order.
• The engine is gated for the first time. The ring-3 program writes from a kernel address and prints a line only if it was refused; nothing asserted that line until now, so an engine that validated nothing would have booted green. The gate has kernel_pointer_not_rejected, and cases/core-ptr-engine.txt shows both engine sabotages turn the boot red with that reason.
• Sabotage: core-ptr-engine.txt (2, boot), core-ptr-descriptors.txt (4), core-syscall-hoist.txt (3), core-user-check.txt (2, chokepoints).

Stage 2a: rows registered by the file that holds the handler (2026-09-21)

• Each of fs/proc/mm/sig/misc/net.c ends with an X-macro list of rows (number, name, operation, call) and LINUX_DEFINE_SYSCALLS, which generates the adapters and the table. dispatch.c looks the number up in the registry; the central switch is gone.
• The registry (abi_linux.c) validates a whole table before taking it and refuses a duplicate number, a NULL handler and an operation NONE or out of range.
• "Add a syscall" is 2 files (abi.h and the file that holds the handler), from 6. The number is stated a second time in scripts/dev/linux-syscall-numbers.txt on purpose, and check-syscall-checks.py holds every row against it. (Since 2026-09-29 that second statement is the registry of every Linux number, kernel/abi/linux_syscalls.def - docs/abi/ phase A1 - and the file is gone.)
• Sabotage: cases/core-syscall-rows.txt (wrong number, duplicate number, deleted row, row that no longer validates memory) and four registry cases in abi-abi_linux.txt; all red. Full check green, 3/3 boots, clang and gcc warnings 0.

C5 - pipes as a module

Status, 2026-09-21: done. This is the detector core_c5_task_identity.md said the descriptor work was waiting for.

What it was

hw_pipe_t, g_pipes[] and g_pipe_lock were globals of the architecture layer, touched from twelve places in the Linux ABI: read, write, pipe creation and its two rollbacks, dup2 (twice), fork, clone, close and exit each adjusted the readers and writers counts or the ring by hand. That is the classic hung-pipeline defect - a count that is wrong on one path - with no place to check it.

What it is now

include/vibeos/pipe.h, kernel/ipc/pipe.c: portable, no globals outside the module.

• One attempt, then the caller decides. vibeos_pipe_read / _write move what they can and return a status - OK, EMPTY, EOF, FULL, NO_READER, FAULT - and never sleep, raise a signal or touch user memory. The waiting, SIGPIPE and the wake-ups stay in fs.c, which knows about the scheduler. The copy to and from user memory is a function the caller passes (vibeos_uaccess_copy has the shape).
• Serialised by its own lock, registered by the architecture (vibeos_pipe_set_lock; a registration, not a weak symbol - that does not resolve on the Windows build). The fourth layer in this project that needed one, and this time it was written in from the start.
• Ends are acquired and released through the module: vibeos_pipe_end_acquire and _end_release (which detaches the descriptor, so it cannot release twice). dup2, fork/clone and close use them; the three copies of "increment the right count under the lock" are gone.
• Two must-be-zero counters, gated. pipe_end_underflow: an end released with none held - the old code clamped it at zero and carried on, which is exactly how a wrong count stays invisible until a pipeline hangs. pipe_bad_slot: a descriptor named a pipe that is free or does not exist. The boot gate already asserts the registry total is zero, so both are gated from the first boot; the host test drives each on purpose (test_mbz_all_demonstrated requires that).

What the first boots said

All three boots read zero for both counters: no double release and no dangling slot anywhere in the boot script, including the pipelines, fork and the threads test. That is a measurement, not an assumption - the clamp used to make it unknowable.

Gates

Host test pipe_tests.c (about 50 checks: the ring across its wrap, EOF versus EMPTY, a drain after the last writer closes, a fault that consumes nothing, a duplicated end needing a second release, the module lock taken and never nested), and cases/ipc-pipe.txt: end of file without asking about writers, a pipe freed when either end goes, an underflow clamped instead of counted, a write accepted with no reader - each red on a named check. ipc/pipe is the first module of this phase with a real must-be-zero, so mustbezero_exempt stays at 23 and is not raised.

Not done

hw_fds_inherit now acquires each pipe end separately, where the old code held the pipe lock across all of them; another core cannot observe a half-inherited table because the child is not runnable yet, but the property is argued, not tested.

C5, first step: threads are one process

C5 in docs/core/phases.md was "one owner for what a task is": move the task table, keep only what a context switch needs in the arch layer. It was planned after C4. It came first, and it came in a different shape, because five external findings in two days turned out to be one defect in the structure C5 exists to fix - and moving a structure with the wrong ownership model only relocates the defect.

The defect

hw_sys_clone_thread created a thread with

child->proc = parent->proc;

which copies hw_proc_t by value. Everything in it that belongs to a process became a private copy per thread. The address space survived that, because what was copied was a pointer to the page tables and exit counts who still holds them. Nothing else did:

The sigaction row is the one worth remembering. The copying loop in clone_thread sat directly under the comment "Signal dispositions are the process's, so a thread inherits them." The sentence described the intent and the loop beneath it contradicted it.

The mapping cursor was not in any review. It came from asking, for each field in hw_proc_t, "who writes this, and do the writers agree on which copy?" - the answer for mmap_cur was two syscalls writing whichever copy the calling thread happened to own.

Why the existing tests were green

musl_threads.c created every thread from main, and no worker touched process state. A kernel that gives each thread a private copy of the process passes that test exactly, because each child copies an up-to-date value at the moment of its creation and never changes it.

Tests first, run against the unchanged kernel

Three stages were added to tests/linux/musl_threads.c and asserted by the boot gate before any kernel code changed. Each was run against the old kernel and failed for the reason it was written for:

THREADS_C5_MMAP_FAIL: main was given the thread's base 0x80040d2000
THREADS_C5_SIGACTION_FAIL: killed by signal 10
THREADS_C5_EXIT_GROUP_FAIL: exited 7, expected 42

On the same boot the three older stages stayed OK, which is the point.

Two things were checked before the stages were trusted to be able to fail at all. SIGUSR1's default action here is to kill - hw_signal_default_kills - and a default of "ignore" would have made the sigaction stage pass on the defect. And the exit_group stage requires the code 42, not merely that the process ended: waitpid builds the status from the leader's exit_code and exit_signal, so an exit_group implemented by SIGKILLing the siblings would report "killed by signal 9" for the leader. Requiring 42 means that implementation cannot pass.

The boot that established the red was guarded against the traps this project already knows: the gate compiled, the build returned 0, and both the test binary and the serial log were newer than the source. A stale THREADS.ELF prints no C5 lines at all and would have read as three did_not_report failures that proved nothing.

The change

hw_procstate_t, referenced rather than copied. It holds the program break, the mapping cursor, the region list, the four disposition arrays and the exit_group state. hw_task_t points at one. fork and exec create one, a thread takes a reference, exit gives it back. The pool is sized for every task plus one exec in flight per core, because exec builds the new process before it lets go of the old one.

The last reference empties the region list before the slot is published free, so a concurrent allocation never inherits a list that is still being cleared. That ordering is safe because the only thing that raises a count is clone, which runs on a live thread of the same process - and the holder of the last reference is the thread that is exiting.

The mapping cursor is claimed with a compare-exchange. Sharing it turned a deterministic defect into a race: two threads reading and advancing one cursor at once can still get the same base. A lock around the mapping would have held thousands of pages with the timer off, so the range is claimed first and mapped afterwards, and nobody holds a lock across the mapping. A range whose mapping fails stays a hole in address space.

brk runs one at a time per process. A thread shrinking the break while another grows it would unmap pages the other has just mapped. Claimed with a compare-exchange on a busy flag rather than a spinlock, for the same reason as above. A C library already serialises its own brk calls, so it is almost never contended; it has to be correct, not fast.

exit_group records the group's code, then SIGKILLs every sibling - which also wakes one that is blocked - and exits. Delivery of that SIGKILL consults the recorded code, so the leader reports 42 rather than "killed by 9". The first caller's code wins, as on Linux. It does not hold g_sched_lock while raising, because hw_signal_raise can take it through hw_task_set_state - the same reason kill() already iterates without it.

exec gets a new process. Its dispositions are derived from the outgoing one - caught signals revert to default, ignored stays ignored, masks carry over - and they are derived before the reference to the outgoing process is given back. Once the last one goes, the slot can be handed to an exec or a fork on another core, and reading it afterwards could copy a stranger's dispositions.

What was deliberately not done

• exec in a multi-threaded process does not end the siblings. Linux does; here the exec'ing task moves to a new process and its siblings keep running the old image on the old one. That is exactly what happened before this change, so it is no worse - and exec is the path that once produced the cr2 == rip defect, so it was changed as little as possible. It is the next step, and it can use hw_task_exit_group for the siblings.

• A leader that exits while its threads run becomes a zombie the parent can reap early. Linux waits for the whole group. Not changed, not tested.

• Descriptors stay per thread. The source already said so, and it is the next row of the same table. Closed 2026-09-27 (M-072).

• fork is not atomic against its own process's other threads. This was first written down as "fork reads the break without holding it - three lines", and the estimate was wrong in scope, found while writing those three lines. fork copies the pages (hw_aspace_copy_user) well before it clones the regions and copies the break, and no address-space lock covers that stretch - so a sibling running mmap, munmap, mprotect or brk during a fork can leave the child with pages and regions that disagree, not just a stale break. A guard on brk alone would be a partial fix presented as a whole one. Linux holds one address-space lock across fork and all of those calls; that is the shape of the fix, and it is larger than a line.

• exit_group cannot end a sibling that is blocked in the kernel. Found while preparing the next step, after this change was already green. SIGKILL is delivered on the way back to ring 3, and no blocking wait in this kernel reads sig_pending: hw_futex_wait loops on while (!woken) hlt, and the pipe and waitpid waits have the same shape. hw_signal_raise moves a blocked task to READY, the scheduler runs it, and it goes straight back into the loop. So exit_group ends a sibling running in user space, and one blocked in pthread_join on the exiting thread - that one is woken by the exiting thread's own clear_child_tid - but not one waiting on an unrelated condition variable, a pipe or a child. The process then never ends. That is not a regression - the sibling stayed blocked before as well - and it is not about threads: kill -9 cannot end a process blocked on a pipe today either. It is the prerequisite for finishing exit_group and for exec ending its siblings, so it goes first.

  There are four such waits, not three. Console read() sets wait_input, and hw_signal_raise clears it - but the only code that reads the flag is the keyboard's wakeup, and the read loop itself just tries the keyboard again and re-blocks. scripts/dev/cases/ctrl-c.txt already records why nobody saw this: the Ctrl-C delivery case was written, run, and came back not red, because by the time the kernel CLI runs there is no foreground process left to reach. Delivery of a signal to a process blocked in the kernel has never been observed by any test here.

  And the test that would observe it cannot be written with the obvious bound: case LSYS_wait4 calls hw_sys_waitpid(a1, a2) and the options argument never arrives, so WNOHANG is ignored and a "bounded" poll blocks exactly like an unbounded wait. A shell reaping background jobs depends on that option too, so it is a defect in its own right, and it goes first of all.

  Closed, with tkill, in the next commit. WNOHANG is honoured; WUNTRACED, WCONTINUED and Linux's __W bits are accepted and have no effect - refusing them would break BusyBox's shell - and unknown bits are refused. hw_task_by_tid had been return hw_task_by_pid(tid); under a comment saying a thread id and a process id were the same number, which stopped being true when clone(CLONE_THREAD) gave threads their own ids: a non-leader's id matched nothing and tkill answered ESRCH, and raise() - which a C library implements as tkill(gettid()) - failed in every thread but the first. Both had red stages first (waited for the child to exit, pthread_kill on a live thread returned 3); both green on the first build; twelve boots: 11 pass, 1 fail.

  And the four waits, closed after that. Every blocking wait asks hw_signal_interrupts now. Three decisions carry it, each forced by something read rather than assumed. hw_task_set_state takes no lock and hw_signal_raise wakes a task without g_sched_lock, so each wait sets BLOCKED first and asks second - the other order has an interleaving in which the signal lands between the question and the block, raise sees a running task and wakes nothing, and the task parks with the signal pending. futex_wait decides "woken or interrupted" under g_futex_lock, or a concurrent FUTEX_WAKE would be counted as delivered to a waiter that returned EINTR and the thread it was meant for would never be told. And a signal that would be discarded - ignored, or a default that ignores - interrupts nothing, because the native shell ignores wait4's result and a spurious EINTR would stop it waiting for its child; SIGCHLD is never raised today, which is exactly why that cannot be left to chance. Red first (THREADS_C5_EXIT_GROUP_BLOCKED_FAIL: the process never ended), green after; twelve boots: 11 pass, 1 fail.

  A futex word has an owner too. Found while reading hw_futex_wake to explain a crash it turned out not to explain: the waiter table was keyed by user virtual address alone, and a virtual address means nothing without its process - every Linux program here links at 0x400000, and a forked child has its parent's layout exactly. A wake in one process could end a wait in another. Not claimed as the cause of the stack-poison crash in the four-worker stage: musl re-checks its condition after every wakeup, so a spurious one alone does not return pthread_join early. Waiters now record the hw_procstate_t they belong to, and a wake matches the process and the address; there are no shared mappings in this kernel, so the process is the whole key. The exit path's wake of clear_child_tid passes the dying thread's process, which is still attached there because that block runs before hw_procstate_put - an ordering the comment beside it now defends, because the other order would hang every pthread_join with nothing failing to compile. Red first (THREADS_C5_FUTEX_XPROC_FAIL: a wake in this process woke 1 waiter(s) in another), green after; twelve boots: 10 pass, 2 (both the known four-worker family: the same unhandled write inside THREADS as fail-7 before the fix, shifted by the new stage's 0x320 bytes) fail.

  An exec from a thread ends the process's other threads, and the caller becomes the process (H-006, verified). Neither happened: the siblings kept running the old image, and a thread that was not the leader kept its own id and is_thread = 1, so the program it loaded ran as a thread - released at exit instead of left as a zombie, its exit code unreachable by the parent. Now, only once the new image has loaded (a failed exec must leave every thread in place): the leader is marked a thread under g_sched_lock, so its exit is decided quietly; every sibling, found by thread-group id rather than by process reference because an already-exited leader has given its reference back, gets SIGKILL; exec sleeps until they are gone, releasing a leader that was already a zombie; then takes pid = tgid and clears is_thread. If a signal must be acted on during that wait, the uncommitted image is destroyed and exec returns EINTR. The wait is unbounded on purpose: waits notice signals now, so a hang there names a wait that ignored one. Exec also clears clear_child_tid - the address belongs to the image that set it, and was left for the new image's exit to zero, on every exec. Red first (THREADS_C5_EXEC_FAIL: exited 7, expected 23 - the leader outlived the exec), green after; twelve boots: 12 pass, 0 fail.

  The shared process block cannot be given back twice. hw_procstate_t is refcounted - threads share it, fork and exec make new ones, and exit gives one back - so a reference returned that nobody held is the process-state analogue of a double free of a frame. hw_procstate_put counts that case (procstate_double_put) on the [TASKS] MUSTBEZERO line, and the boot gate fails if it is not zero. It closes the C5 step-0 item that asked for a must-be-zero here. Proved able to fire: with a deliberate second put of every dying process's state, the gate reported reason=invariant_failed:task_procstate_double_put=119 and went red; reverted, the restored tree is green.

  A slot index is not a reference (H-007, verified). The syscalls that name a task by id - kill, tkill, tgkill, setpgid, getsid, setsid - resolved it to a g_tasks index and then used the index without a lock, and so did the sibling loops of exit_group and exec. A slot is reused as soon as its task is reaped, so between the two a fork could take it: kill(old_pid, SIGKILL) would land on the new tenant, whose permission check was the one made. pids are never reused, so the index is safe exactly while g_sched_lock is held - every allocation and every publish to FREE (thread exit, waitpid's reap, exec releasing a zombie leader) happens under it - and lookup, check and act are now one critical section. exit_group's loop matched on ps, which does not help: the hw_procstate_t pool is reused too.

  A second half turned up while reading it: allocation clears the address space, descriptors and thread flags but leaves is_user, pid, tgid, sid and pgid until fork or clone rewrites them, so a slot still being built answered to a dead process's id. Lookups skip RESERVED now.

  Two comments said hw_signal_raise could not run under g_sched_lock because it reaches hw_task_set_state. That function takes no lock, and hw_schedule already calls it under this one; one of the two comments was written for H-006 earlier the same day and repeated the other without checking.

  No red test, and that is a statement rather than an omission: the window is a few instructions between two cores, and a stage that cannot fail would prove nothing. The existing signal stages are the regression. check.sh all green; twelve boots: 11 pass, 1 fail - the four-worker THREADS family, same unhandled write at the same instruction (0x405b72 in this build), ending in the free-page-poison panic.

• No must-be-zero counter for the new structure. One was designed - a reference dropped below zero - and not added, because a counter nothing reads is this project's most repeated defect, and reading it means touching the portable stats struct, its printer and the gate in the same change. A leaked process would show today through vmas_live, which the gate already asserts returns to zero. Recorded as debt, not as coverage.

Found on the way

Rewriting hw_sys_mmap for the claimed cursor exposed that this morning's fix for the review's M-002 had covered one of two allocation loops - the reservation branch - and missed the ordinary anonymous path that malloc reaches. The note in that commit saying the leftover pages were unreachable from ring 3 was true only of the loop it fixed. Both loops unwind now, and mm_brk_mmap_leaks.md carries the correction.

Verification

The three older THREADS stages stayed OK throughout, as they did on the red run - they were never able to see this.

C5 residue: mprotect against fork, and one descriptor table per process

C5 closed with two items written down as out of its scope (phases.md, "Still open"). Both are closed here (2026-09-27), together with a third defect found while proving the second.

mprotect held the address-space lock for half the call (M-071)

hw_sys_mprotect took hw_mm_lock around the region-list update and released it before narrowing the page tables. The reason was real when it was written: narrowing does a TLB shootdown, and a sibling spinning in hw_mm_lock with interrupts off could not acknowledge the IPI, so the shootdown timed out and panicked. So a fork on another thread - which walks the page tables under the same lock - could copy an entry mprotect was halfway through changing.

The reason has gone. The lock's spin opens an interrupt window every turn, and since M-065 a waiting core answers flush requests itself. mprotect now holds the lock from the range check to the last entry, with a single exit.

Reading the function for that found the other half. The range check and the page-table pass both asked hw_pte_lookup, which answers only for a present entry - so mprotect on a page in swap was refused with EFAULT, although a swapped entry keeps its permissions (M-063) and vibeos_vmspace_protect already knew how to change them. The check now accepts present or swapped, and the pass hands every page to vibeos_vmspace_protect.

Proof. svc-reclaim now makes every block read-only before reading it back; by then most of the oldest are on disk. With the check put back to "present only" (scripts/dev/cases/mm-mprotect.txt) the boot goes red with reclaim_load_failed - RECLAIM_FAIL: mprotect refused block 0 - for the right reason, and green without the sabotage. The lock itself has no case: a fork has to read an entry in the few instructions between the list update and the narrowing, which one boot does not arrange. Recorded as untested.

The ABI self-test's case that mprotect refuses an unmapped page (linux-abi.txt) had its anchor re-pointed at the new check, found by check-sabotage-anchors.py on the first check.sh all.

Descriptors were copied per thread (M-072)

clone(CLONE_VM|CLONE_THREAD) gave the new thread a copy of its creator's table, and the source said so in a comment. So a descriptor one thread opened did not exist in the others, and a close in one left the rest holding it - the last of the five process-state copies core_c5_process_state.md lists.

The table moved into hw_procstate_t, beside the dispositions and the region list, and a thread shares it by holding the same reference. fork and exec take a copy (hw_fds_copy, every pipe end in it gaining an owner); a thread takes nothing.

Sharing the table made two things true that were not:

• Two threads can open at once. open looked for a free slot, then read the disk, then marked the slot used - a sibling opening meanwhile found the same slot free. Claiming now goes through files_lock and happens before the lookup; a failed lookup gives the slot back. pipe claims its two ends the same way instead of scanning by hand. close takes the entry out of the table in one step under the lock and finishes with its own copy, so a second close of the same descriptor from another thread gets EBADF instead of releasing a pipe end twice. dup2 reads, replaces and re-references in one critical section. The lock is not held across I/O: two threads reading one descriptor at the same moment share its position without ordering, a difference from Linux recorded in the structure's comment.
• Who closes the table. Every exit closed its own copy. Now the table goes with the last thread to leave it, counted by files_users - apart from the process reference, because exit gives that back only after it has switched away, and closing a pipe has to happen before. The same change fixed a defect nobody had reported: each thread's exit released all of the process's sockets by thread-group id, so a worker that finished closed the connections its process was still using. They now go with the last thread too.

Proof. THREADS_C5_FILES in tests/linux/musl_threads.c: a thread makes a pipe and main reads from it; then main closes the write end while another thread waits to write through it, and that write must fail. The gate asserts it (thread_descriptors_not_shared, threads_c5_files_did_not_report). Run against the kernel before this change - the test first, the fix stashed - it printed THREADS_C5_FILES_FAIL: a pipe a thread opened is not open in main. Sabotage (scripts/dev/cases/fd-shared.txt): a clone that does not count itself as a user of the table, and an exec that does not copy it. The lock has no case, for the same reason as mprotect's.

The first of those went NOT RED at first, and the reason is worth more than the case. With the increment gone, the first thread the threads test ever creates takes the count to zero on exit - closing a table that held nothing of interest yet - and every exit after that wrapped it below zero, so by the time THREADS_C5_FILES ran nothing closed anything and the test passed. The symptom appears once, wherever the first exit happens to fall; the underflow happens on every exit after it. So the leave refuses to go below zero and counts the attempt as files_double_leave, on the [TASKS] MUSTBEZERO line the gate already asserts - the mechanism gated, not one lucky symptom.

check-task-identity.py asserted the table was embedded in hw_task_t; it now asserts the opposite and that hw_procstate_t holds it, and its ratchet on lines that index the table directly went from 17 to 12.

rmap_missing_remove was an eviction finishing inside a teardown (M-073)

Running the new threads test against the old kernel was supposed to show one failure. It showed three, and one of them was mm_rmap_missing_remove=1 - the rare counter that had fired once in about fifty boots and had been instrumented since. The instrumentation named it at once: RMAP_MISSING with a caller in vibeos_vmspace_swap_out, and a virtual address inside svc-reclaim's blocks.

That boot's svc-reclaim had exited early - the old mprotect refused its first block - with some 1,400 blocks still mapped, so its teardown ran while the clock was evicting from it. vibeos_vmspace_destroy calls vibeos_rmap_forget_root, which removes every holder recorded for the root first and only then waits for reclaim's claims on it (M-056). A reclaimer that claimed a page before the teardown finishes its swap-out afterwards: the entry is still there, the commit succeeds, and its vibeos_rmap_remove finds nothing, because the teardown took it. Nothing is wrong - the frame is released once, by the eviction, and the teardown frees the slot the entry now names - but the must-be-zero counter said otherwise.

forget_root now marks the claims it waits on, and a remove that finds nothing for a root with a marked claim outstanding is counted as removed_after_forget, which is printed and is not a must-be-zero. A remove that finds nothing anywhere else is still missing_remove. The host test test_eviction_during_teardown plays the reclaimer from the wait's relax hook, and the sabotage that stops marking (mm-rmap-claims.txt) turns it red. Clearing the mark when the last claim goes was tried as a case too and went NOT RED: the mark is read only while a claim is outstanding and a new claim clears it, so the clearing was redundant and was removed rather than tuned.

Lesson worth keeping from the order of events: the rare defect was not found by hunting for it. It appeared when a load that normally runs to completion stopped early and left a large teardown to race the clock - an arrangement no test had set up on purpose.

The arrangement, made on purpose

That arrangement is also where the two defects still open were seen: M-070 (a page lost and a slot freed twice) in a boot where svc-press exited beside the load, and M-068 in the boot where the load's first version outlived init. Twenty-four boots with the clock's second chance disabled - the thrash in which M-070 first appeared, rebuilt in a separate worktree - were all clean, and all had rmap_claim_waits=0: not one teardown ever met an eviction in progress. Thrash alone does not produce it.

So svc-reclaim has a second half. After RECLAIM_OK, a child fills memory past the low mark as the main load did, tells the parent through a pipe, and exits with everything still mapped; the parent allocates at once, below the low mark, so every page it takes goes through reclaim, and the clock lands mostly on the child's frames. The first version had the child exit immediately and the race still did not happen: every page it owned had just been written, so the clock's first pass only cleared accessed bits, and the teardown was over before it came round again. The child now waits until swap has taken 64 more pages - until reclaim is evicting - before it exits. The first boot of that version reported rmap_claim_waits=1 rmap_removed_after_forget=1: exactly the event that had been rmap_missing_remove=1, now arranged and classified. The gate asserts RECLAIM_ABANDON_OK (reclaim_abandon_did_not_finish); what the race must not produce - a slot freed twice or left allocated, a frame lost - is caught by counters it already asserts.

C5 - what a task is, apart from what a CPU needs to run it

Status, 2026-09-21: steps 1 (identity) and 2 (descriptors) done; the phase is not finished. Step 0 (process state referenced, not copied) is core_c5_process_state.md.

What moved

hw_task_t was one structure holding everything about a task: the saved registers, the kernel stack, the address space and descriptors and who it is. Seventeen fields of identity are now vibeos_task_t (include/vibeos/task_ident.h, code in kernel/sched/task_ident.c), embedded in hw_task_t as id:

pid tgid ppid pgid sid service_id is_thread is_user is_idle wait_input signal_stopped exit_code exit_signal clear_child_tid comm sig_pending sig_blocked

The portable type has host tests and functions, and the arch layer uses them:

• vibeos_task_identity_reset - the one place identity is cleared, called from hw_task_alloc. Before it, alloc reset three of these fields (is_thread, service_id, clear_child_tid) and a recycled slot kept the previous tenant's pending signals, exit status, pgid and name until each creator overwrote them - the shape of interp_base again. It clears the whole object byte by byte, so a field added later is cleared without anyone remembering to say so. The host test fills the structure with 0xA5 and needs every byte back to zero; its first version caught the reset missing padding.
• vibeos_task_accountable_to - the fork guard's "does this parent answer for this task" (child, or a thread of its group), replacing an inline condition.
• vibeos_task_set_comm - bounded and always terminated, replacing a loop in prctl that left the tail of the previous name.
• vibeos_task_is_group_leader.

How the ~180 call sites were moved

Not by search-and-replace: pid and ppid also name fields of other structures. The fields were removed from hw_task_t and the compiler then named every access - file, line and column - which a small tool rewrote in place (.pid to .id.pid), round after round until the build had no such error. Only accesses to hw_task_t can fail that way, so nothing else was touched.

Step 2: the descriptors

hw_fd_t was already plain data (a pipe or socket is an index, not a pointer), so it moved as it was: vibeos_fd_t and vibeos_fdtable_t (include/vibeos/fdtable.h, kernel/fs/fdtable.c), embedded in hw_task_t as files; hw_fd_t remains as an alias so the ~60 places that name it are not renamed. The table states the ABI's split once - fds[] is descriptor 3 onwards, std[] is what 0, 1 and 2 have been redirected to - and provides reset, get, redirect, free_index, claim, copy and an index walk. What it replaced:

• fork and clone each copied the table by hand and then walked it to give every pipe end an owner - two copies of about twenty lines. It is hw_fds_inherit now, once. A change to how inheritance counts a pipe end used to need making twice, and the case that is missed hangs a pipeline.
• the reset in hw_task_alloc (two loops) is vibeos_fdtable_reset; exit walks every entry once instead of the table and the redirections separately; hw_fd_alloc, hw_fd_get, open and dup use claim, get and free_index.
• a latent sign mismatch surfaced when VIBEOS_HW_MAX_FDS became unsigned (gcc -Wsign-compare in pipe); fixed by keeping the constant an int.

Sabotage cases/fs-fdtable.txt: an off-by-one bound, a claim that does not clear, a copy that skips the redirections - each red on a named host test. The first version of the bound test would not have caught the off-by-one (in the real structure the entry past the last is std[0], which is unused, so it answered NULL by luck); the test now marks it used first. That is this project's usual lesson, met again.

What this does not finish

The phase's done-condition is that arch_hw.c names no task field that is not part of a context switch. It is not met: arch_hw.c reaches into identity on 92 lines and the Linux layer on ~126. check-task-identity.py states the two properties that can be stated - hw_task_t may not declare an identity field again, and the 92 may only go down - and is in check.sh. The process pointer (ps), state, on_cpu, the scheduling timestamps and the fork of a whole task are still hw_task_t's. 17 lines still index the table by hand (pipe, dup2 and socket code that arithmetics on fd - 3); check-task-identity.py ratchets them.

Gates: host test (task_ident_tests.c), check-task-identity.py, sabotage cases/core-task-identity.txt (a second pid) and core-task-identity-reset.txt (a reset that clears half) - both red.

Two things found on the way

• PTR_ in linux_internal.h did not initialise the two fields C4's futex descriptor added, so gcc reported -Wmissing-field-initializers on every row. The futex commit was reported green on a run whose head I had cut off with tail - the trap this project's notes describe. Fixed here; the clean run reads warnings=0.
• check-subsystem.py's mustbezero_exempt went 21 to 22 with sched/task_ident (pure functions over a caller's struct; no state to be wrong). That baseline "may only go down", so it is recorded as a decision beside the number rather than edited.

Decision: exemptions, not counters (2026-09-21)

mustbezero_exempt rose 21 to 23 (sched/task_ident, fs/fdtable). A real must-be-zero was weighed and declined: both modules are pure functions over a struct the caller owns, so a counter inside them could only report on its own arguments, and the defects that live here (a field the reset forgot, an off-by-one bound, a copy that skips the redirections) are what the host tests and the fill-with-a-pattern check catch deterministically. A counter earns its place where state is shared and mutated at runtime. The one such place this phase touches is the pipe-end count that hw_fds_inherit, close and exit all adjust; the pipe table is not a module yet, and its detector (a writers/readers count that goes negative or disagrees with the descriptors that name it) belongs with it when it becomes one. Done: see core_c5_pipes.md - the pipe table is a module now with two real counters. The two exemptions stay, since they were about pure functions, and the baseline is not raised again.

C5 - the task's state has one owner

Status, 2026-09-21: done.

What it was

The task layer (kernel/sched/task.c) already owned the transition table - the one place that says which state changes are legal - and hw_task_t kept a second copy of the state, written after each transition. Two opinions about what READY means is how two cores once ran one task, and the copy was also read from 52 places, so every reader trusted whichever the code near it happened to use.

What it is now

• hw_task_t has no state. hw_slot_state(slot) / hw_task_state(task) ask the task layer, and the only writer is hw_task_set_state, which calls the transition. The 52 readers were rewritten from the compiler's own error positions (g_tasks[i].state became hw_slot_state(i), t->state became hw_task_state(t)), not by search and replace. The state array is volatile inside the task layer: other cores read it while a transition writes it, which the old field's volatile said and the new one must.
• ready_at moved with it. The tick a task became runnable was stamped by hw_task_set_state when the target was READY, on the argument that this is the only writer so no path can forget. That argument belongs to the transition, so it is stamped there now (vibeos_task_ready_at), and a new tenancy starts at zero.
• ran_once became vibeos_task_first_run: true once per tenancy, atomically, and reset when a slot is claimed. It was a flag the arch layer set by hand.
• on_cpu stays where it is: it is a fact about a CPU executing the task and only the context switch reads it.

Gates

Host test (the stamp on READY and not on RUNNING, restamped on each return to READY, a new tenancy starting unrun with no ready time, an out-of-range slot answering "no"); cases/sched-task-state.txt (three sabotages, each red on a named check) and a fourth core-task-identity.txt case (a second state in hw_task_t). The five existing sched-task.txt cases still go red.

Measured, because the state read became a function call

The syscall and scheduling paths now call the task layer to read a state. syscall_min under TCG, three boots each: c6efd0a (before this session's work) 887-980, ebe9fae 793-934, f1e2b76 489-560, this tree 776-949. Nothing regressed, and that is all it shows: the spread between builds of the same logic on the same host is wider than any effect here, so the number cannot resolve a state read. The 229 quoted earlier in this work came from another machine state and is not comparable. The ceiling (5000) holds with a wide margin.

Not done, as of the previous entry

arch_hw.c still names identity on 92 lines, and the fork of a whole task (allocation, the child's registers and stack) is still the arch's - it needs the context and the kernel stack, which are what the arch layer is for. The phase's done-condition is about fields, and what remains in hw_task_t is now: the register frame, the address space, the kernel stack, on_cpu, the FPU area, fs_base, the process pointer, the ABI pointer and the diagnostic markers. Those are the context switch's.

Closing the phase: the lifecycle leaves arch_hw.c (2026-09-22)

The 92 lines were not fields left in hw_task_t - they were code, spread through arch_hw.c, that names identity while doing something that is not switching a context: creating a task, describing it for a diagnostic, ending it, delivering a signal, killing a faulted one. That code moved, whole, to a new file, kernel/arch/x86_64/task_life.c - the same tool C4 stage 3 used (parse into top-level items, build the reference graph, move a function iff everything that references it moves too), pointed at fourteen roots (hw_task_exit, hw_task_spawn_user, hw_task_create_idle, hw_signal_raise, the console interrupt, the ring-3 fault killer, ...) instead of at the syscall handlers. 37 items, 1,605 lines.

What stayed, and the line that says so is now a check. Five functions are the context switch - vibeos_x86_64_isr_handler, hw_task_runnable, hw_task_load_cpu_state, hw_ctx_check, hw_schedule - and only they may still name .id.. check-task-identity.py reads arch_hw.c function by function: identity named anywhere else is a failure by itself, not just a count; the 12 lines those five carry are the new ratchet, down from 92. cases/core-task-identity-arch.txt puts one back in the slot allocator and confirms it is caught, named.

Twelve of the remaining lines were file-scope reads/writes of pid, pgid, is_user and service_id from code that stayed (the diagnostics, the fault path, the console handoff at boot) - not moved, because moving them would have meant moving their callers too, which are switch-adjacent. They go through four small accessors instead (hw_task_pid_of, hw_task_pgid_of, hw_task_is_user_of, hw_task_set_service, defined with the lifecycle in task_life.c), the same shape as hw_slot_state / hw_task_state for the state field itself.

hw_fd_alloc moved too - it is part of a task's lifecycle (claiming its first descriptor), not part of switching to it.

Two checks were found broken while working nearby it, both fixed, both given a case:

• check-chokepoints.py's count for hw_task_alloc_guarded needed one more site: crossing into task_life.c cost it its static, so it gained a header declaration - the fourth of what was three. Recorded as the decision it is.
• check-exec-layering.sh (X-P4, kernel/exec/) named arch_hw.c by path and would have failed silently the moment the interpreter substitution moved with the lifecycle. Repointing it at task_life.c surfaced a second, older bug: it flagged a comment two thousand lines away that quotes a boot-log line containing LDMUSL.SO as an example - confirmed already red at HEAD, before any of today's work, by running the unmodified script against a clean worktree. Nobody had run it in a context where its exit code mattered, because it also always exit 0, so check.sh (which reads its printed text) never noticed and nothing else ever checked its return code. Both are fixed - comment lines are skipped, and it exits 1 on failure - and cases/core-exec-layering.txt is its first sabotage case, proving both a real second path is still caught and the log-example comment is not.

Done

C5 is closed: one definition of a task's identity, one table of its state, one module for its descriptors, one module for pipes, and arch_hw.c naming a task's fields only where it switches between them. arch_hw.c is 6,220 lines (was 12,174 before C4); task_life.c is 1,643.

Full check green (clang and gcc, 3/3 boots, host tests, all sabotage cases including the two written today). syscall_min not re-measured after this move - it touches no hot path (creation, exit, signal delivery, diagnostics), and C0's ratchet would have caught a regression in what it does touch.

C6 - diagnostics become a module

Status, 2026-09-22: done. The kernel log and the crash records live in kernel/diag; the UART and the disk are registered sinks; the arch layer keeps the mechanisms that are different on another machine.

The plan (docs/core/phases.md) called this the one move that can invalidate its own evidence: these two are what every other phase is verified with. So the order of work was the plan's own - verify the inherited tree green first, write the module and its tests, break the tests, then boot - and three things that moving it found are recorded below because they were defects, not tidying.

What was there

In arch_hw.c, under a banner that said "the kernel log":

• g_kernel_log, a vibeos_log_t ring, written by hw_log from every core;
• hw_log_format, hw_log_emit (serial), hw_log_to_sink (disk) and its per-core reentrancy flags, hw_log_dump (panic) and vibeos_x86_64_log_dump_recent (the console's log);
• the crash ring g_crashes[4], g_crash_next, g_crash_count, written from task_life.c and printed by vibeos_x86_64_crash_dump.

The plan's 724 and 56 lines were measured before C4/C5 had already moved some of it; what was actually left was about 470 lines of log section plus the crash ring. arch_hw.c is 6,031 lines after this phase (6,231 before it).

What it is now

include/vibeos/klog.h, kernel/diag/klog.c:

• The ring has its own lock (vibeos_klog_set_lock, registered by the arch as hw_spin_lock_named(..., "vibeos_klog")). The lock covers the ring only; sinks are written outside it.
• A sink is a registration: a name, the quietest level it wants, an optional prefix, whether its lines are numbered and newline-terminated, and write(ctx, line, len) that takes one complete line and says whether it took it. The serial port ("serial", INFO and up, [LOG], numbered) is registered by hw_klog_init; the disk ("disk", every level) by hw_logsink_bringup, and only once the medium has taken its boot mark - before that it would refuse every line, and every refusal is a must-be-zero.
• One line, one call. The module formats the whole line and hands it to each sink once; the serial sink passes it to one serial_puts, which is one critical section on the console lock. The "multi-part message left unbracketed" defect is not guarded against here, it is not expressible: there are no parts.
• A refused line is counted: per sink (lost) and in the registry as klog_line_lost, which the boot gate asserts through [MBZ] MUSTBEZERO total.
• A line the device lost while saying it had not is the half no counter inside the kernel can see. Every serial line carries ln=0x..., one sequence per sink; the [KLOG] line reports how many were given out; the gate requires every number from one to that count to be in the log (klog_line_missing, klog_counters_missing, klog_serial_unproven).
• Reentrancy is the module's, for the sinks that ask for it and keyed by execution context (see "The limits it shipped with", below): an event raised inside a sink's own write (the block layer logs when it refuses a request) is recorded and reaches the other sinks, is not offered back to the sink that raised it, and is counted as reentered.
• vibeos_klog_panic(why) writes "[FATAL] PANIC: why" to every sink with no lock and no level; vibeos_klog_dump_unlocked replays the ring for a panic with no lock; vibeos_klog_dump_recent is the console's log, one event per critical section.

include/vibeos/crash.h, kernel/diag/crash.c: the ring of four, its own lock, a record copied whole in and out, registers as name/value pairs the architecture fills, and a portable dump that prints exactly what crash printed before. The capture - reading the trap frame, and the user stack through vibeos_uaccess_copy

• stays in task_life.c, because that is what a trap frame is.

What stayed in the arch layer, deliberately: the UART itself, the frame-pointer walk (hw_backtrace), parking every core on a panic, the raw deadlock reporter that must not take the console lock, and the [HW][TRAP] line.

What moving it found

1. The ring was never locked. hw_log called vibeos_log_record from every core with no lock, then asked the ring for vibeos_log_latest to decide what to print. With two cores logging at once, "the latest" is whichever landed second: one line printed twice, the other never, and both could claim the same slot. The event printed now is the copy taken inside the same critical section as the record. Same shape as backing.c in CLAUDE.md - a layer serialised by accident - and the fifth layer in this project to need its own lock.

2. The crash ring was not locked either. The recorder read the cursor, filled the slot and advanced the cursor as three steps; two processes faulting on two cores (which is what a broken library does to everything linked against it) wrote one record over the other and advanced past a slot nobody filled.

3. The ring held a false FATAL every boot. The trap model was handed the ring directly, so it wrote behind the lock and past every sink - and, asked with pid 0 and knowing nothing of privilege, it recorded kernel_fault_panic at FATAL for every ring-3 fault, including svc-crash's deliberate one on every boot. A panic dump would have shown a FATAL for a fault the machine had survived. The model is now given no log; the arch logs kernel_fault_panic itself, only on the path that actually panics, with the same code (TTFK) and a1 = rip that the gate's poison-executed detector reads.

And one the new torture found in the new code on its first run: the panic path had its own copy of the line builder, and that copy dropped the newline when a line had to be cut. Unreachable with today's [LOG] prefix, and still two copies of one rule already disagreeing. There is one builder now.

How it is proved

• Host tests (tests/kernel/klog_tests.c, crash_tests.c): one write per event per sink with the exact text; the ring locked exactly once per event and a sink never written under it; a second core simulated at the unlock, so "print the latest" is caught deterministically; levels; refusals counted with the witness naming the sink; reentrancy; truncation keeping its newline; both dumps; panic; a full table; lock balance across the whole test. Crash: the exact dump, ring of four, clamping of a record that lies about its sizes, one critical section per record.
• Torture (tests/kernel/diag_torture.c, nightly job diagnostics-torture, # module: diag): random sinks, levels, refusals, nested reentry, a simulated second core, panics, dumps and crash records, every line checked against a model that formats with snprintf and shares no code with the module; long runs must wrap the 2048-event ring (the first version never did - a reset every hundred rounds kept it under capacity, and the torture now fails a long run that did not wrap).
• Sabotage, all red by name:
  • diag-klog.txt (8 cases: an unmatched unlock; a line in two writes; a refusal ignored; the ring unlocked; "latest" read after the unlock; sinks written under the lock; no reentrancy guard; one line counter shared by all sinks) - red under the host tests and under the torture alone.
  • diag-crash.txt (4 cases) - red under both. The register-count case first went red under the torture as a segfault with no message: the model had named it, and the buffered line died with the process. The torture flushes on failure and stops dumping a record it already knows is wrong.
  • diag-sink.txt (4 boot cases: the serial sink drops its fifth line and reports success; the [KLOG] line disappears; the sink is offered nothing; the sink logs from inside its own write) and crash-recorder.txt (re-pointed: its first case targeted the arch's own ring, which no longer exists) - red under the boot gate. The dropped-line case first dropped one line in sixteen and went NOT RED: a boot hands the serial sink about a dozen live lines, and the sixteenth call was a replay from the console's crash/log dump, which carries no ln=. That is the detector's real limit and is recorded in the case file rather than tuned away: ln= covers live lines; a lost replay line is seen only by the markers the gate waits for on those commands.
• check-subsystem.py covers kernel/diag (diag/klog reports through the registry; diag/crash is exempt with its reason, the exemption count raised from 23 to 24 as a decision).

The plan names the file core-diag.txt; check-subsystem.py pairs a module with its cases by area, so they are diag-klog.txt, diag-crash.txt and diag-sink.txt.

The limits it shipped with, closed (2026-09-23)

The first version of this file listed three limits as open. All three are closed; closing them found one more defect.

• The reentrancy guard was per core, and a task can move. Between the module setting a sink's busy flag and the sink's write, interrupts are on, and kernel tasks are preempted and migrated; a task moved there left the flag set on the core it had left, and every other context on that core had its lines to that sink skipped as reentered. Masking interrupts across a disk write was not an option - a core with IF clear cannot answer a TLB shootdown. Two changes instead: the guard is opt-in per sink (guard_reentry: on for the disk, whose block layer logs; off for the serial port, which cannot recurse - so nothing can ever skip a serial line), and it is keyed by execution context (vibeos_klog_set_context): the arch answers with the running task's slot, read through the per-CPU block only once GS.base is installed, and one number per core before that. A migrated task takes its flag with it; an interrupt nested in a task is that task, so a nested write is still caught. The gate still asserts the serial sink's reentered is zero.
• Replays had no detector. ln= covers live lines only. Each replay now states its length - log and the panic dump already did in their header; crash now ends [CRASH] end lines=0x.. - and the gate's replay_incomplete counts the lines against it (diag-sink.txt drops one line of the crash dump: red as replay_incomplete=crash_dump).
• There were two logs. kmain kept a ring of its own for its boot stages, so status counted one log, log printed both, and a panic dump never showed a boot stage. kmain now logs into klog, which on the machine the architecture has already created (entry.s runs hw_early_init, whose "log" stage creates it, before vibeos_kmain); kmain only creates it when it is missing, which is the host tests. vibeos_kernel_t.log is gone. The host boot test logs one event "as the architecture" first and fails if kmain throws it away (diag-kmain.txt).

Found while closing them: the console's log showed the wrong events under load. dump_recent fixed what to show as a range of ring indices and re-read them one lock at a time. With the ring full - every boot past 2,048 events - each event another core logged during the dump pushed the oldest out and moved every index by one, so the dump showed a neighbour instead: the same event twice, one skipped, nothing said. It now fixes a range of sequence numbers under one lock and fetches each by number; an event overwritten before its turn prints as [LOG] #<seq> overwritten before it could be shown, so the line count is still the one the header announced. A host test fills the ring and logs during the dump; the torture does the same with bursts large enough to overwrite announced events, and requires a long run to have done so.

Code scanning

The nightly torture's first version built its expected lines with n += snprintf(buf + n, cap - n, ...), three alerts at high severity. The analysis was right about the mechanism: snprintf returns the length it would have written, so after one truncation n passes cap and the next cap - n wraps to an enormous size_t. No expected line came near its buffer, so it never fired - and nothing stopped the next longer dump from overwriting the torture's stack. One bounded app() helper replaces every such call, and a model text that does not fit is a test failure rather than a silent cut.

Triaged in the same pass: the ABI registry test registered stack arrays with a registry that keeps the pointer (the tables are static now, and abi.h states the lifetime contract); ntfs.c named $INDEX_ALLOCATION's length attr_len inside a function whose outer attr_len is $INDEX_ROOT's - renamed alloc_len, because in a parser that is how one attribute's bound gets checked against the other's.

Still open

• The panic line reaches every sink, so the serial log carries [LOG][FATAL] PANIC: <why> just before the existing FATAL: <why>, halting line. The gate reads the second; the first is what the disk has always received. Recorded, not a defect.

C7 - the registries the next refactor needs

Status, 2026-09-23: done - the registry, proved on the input devices; the network interface; the disk drivers and the registered filesystem; the display. The "done when" - the GUI registered with its own lock, counters, a must-be-zero and a case file - is met. The blast-radius objective is met for every device row and not for two others; see the table at the end.

The plan (docs/core/phases.md): character, input, network and display devices register the way block devices do, check-blast-radius.py reports 1 for every row, and the GUI is registered rather than wired in, with its own lock, counters, a must-be-zero and a case file.

Where it started

check-blast-radius.py measured every driver kind at 3 or 4: adding one meant editing, besides its own file and its line in the build,

• an init call in arch_hw.c (or io_bringup.c),
• a declaration in arch_x86_64.h,
• a branch in the interrupt handler naming its vector,
• and a print of its counters in kmain.c, with a weak default beside it.

Block devices had a registry (vibeos_blk_register) and it bought nothing measurable: everything around it named each driver. include/vibeos/drivers.h had a portable "driver framework" that no running code consulted.

Step 1: the registry, proved on the input devices

include/vibeos/device.h, kernel/io/device.c.

• A driver is a descriptor in its own file: name, class, legacy interrupt line, probe, irq, selftest, report, and its class's operations. VIBEOS_DEVICE(desc) places a pointer to it in the vibeos_devices linker section; kernel.ld collects the section between two symbols and arch_hw.c hands the table to the registry. Nothing names a driver.
• The registry does what arch_hw.c and kmain.c did by name: routes every declared legacy line (before any probe - a probe raises its line, and the mouse's acknowledgements were exactly that), probes, dispatches an interrupt to every device registered on its line (present or not - a PS/2 mouse that failed its probe still has to take its byte off the port), runs self-tests and prints each driver's counters on a line of its own, and serves the input class: vibeos_input_getc, vibeos_input_inject, vibeos_input_pointer. The console reads a character and the display reads the pointer without knowing either is PS/2.
• Set once, probed once, then sealed. The readers - interrupt dispatch among them - take no lock, because the data no longer changes; a second table or a second probe is refused and counted (VIBEOS_MBZ_DEVICE_AFTER_SEAL). The report takes the module's own lock for the self-tests.
• Probes run outside the lock. The lock masks interrupts, and the keyboard's probe waits for one (below). A host test fails if a probe ever sees the lock held.

The keyboard and the mouse moved onto it. Every symbol either exported is gone; the keyboard's counters left the middle of a kmain.c line for a [KBD] line of their own, the mouse's left arch_hw.c for a [MOUSE] line from its driver, and the mouse's packets counter - counted since the driver was written and read by nobody - is on that line now.

Input device: 4 -> 1. The one edit left is the file's line in the build.

What building it found

Nobody types in CI, so the keyboard's interrupt path had never run in a boot. Two boot sabotages - do not route the legacy lines; do not wake a reader when an input interrupt arrives - went NOT RED. The reason was not a weak assertion: the boot's script is injected into the keyboard's ring, which raises no interrupt, so IRQ1's routing, the dispatch and the wake-up were exercised by no boot at all. The first had also been true before C7, under the name of the driver.

The keyboard's probe now proves the path: it asks the PS/2 controller to put a byte in its output buffer as though the keyboard had sent it (command 0xD2, with a key-release code the driver ignores), which raises IRQ1 exactly as a keystroke does, and waits - bounded - for it. [KBD] ... irq_proved= says it arrived; [DEV] ... input_irq_wakes= says the dispatch woke readers because of it. The gate asserts both (kbd_irq_unproven, input_irq_wake_unproven), and the two sabotages are red by those names now. If the interrupt never comes, the probe takes the byte back off the port - otherwise the mouse's probe, next, would read a keyboard byte as its own acknowledgement.

The first version probed under the lock, where that interrupt could never arrive on the core that was waiting for it: the lock masks interrupts, and the line is routed to that core. Caught by reading the code before the boot; the host test and io-device.txt hold it now.

KEEP in the linker script does nothing today - the image is not linked with --gc-sections - and the first draft of its comment said otherwise. It is there for the day it is; [DEV] registered= is asserted (device_table_short), so a section that loses its entries is named either way.

How it is proved

• Host test tests/kernel/device_tests.c: refusal of a table with a hole or too many entries; presence before and after probing; every declared line routed; probes in order, outside the lock, seeing the machine's description; the seal and its must-be-zero; interrupt dispatch to every registered device on a line, and to nobody on an undeclared one; self-tests under the lock and reports outside it, for absent devices too; the input class in table order, the pointer only from a present device; report lines whole and newline-terminated.
• scripts/dev/cases/io-device.txt (13 cases, host; 9-10 from step 2, 11-13 from step 3a): all red by name.
• scripts/dev/cases/io-device-boot.txt (4 cases, boot; the fourth from step 3a): an empty table (verdict=boot_volume_missing: no disk driver, so no volume; it was a "wedge" until the kernel said so); no wake; no routing.
• core-observability-modules.txt: the three mouse cases, re-pointed at the driver, red by name.

Step 2: the network interface

A NET class (vibeos_net_ops_t: mac, send, recv) and vibeos_net_device(), which hands the stack the first present network device with every operation - not one whose probe failed (no queues: every frame swallowed) and not one without recv. virtio-net's init is its probe, and hw_net_bringup asks the registry for the result instead of naming the driver.

Network interface: 4 -> 1. What it had been: arch_hw.c declared six of the driver's functions and called four; kmain.c printed its timeout count through a weak default; and two accessors - the transmit/receive frame counts and ready - were declared and called by nobody. The frame counts are on the driver's own [VNET] line now (a boot sends about ten and receives about nine), next to net_tx_timeouts, which left kmain's [IO] WAITS line; the gate reads each where it is and still calls either one missing io_wait_counters_missing.

Proved by the host test (a failed or incomplete network device is never handed out; io-device.txt cases 9-10) and on the boot (io-device-net.txt: the timeout leaving the report line is io_wait_counters_missing; a device reported absent takes the lease and the TCP round trip down with it, by name).

Step 3a: the disk drivers

A BLOCK class (vibeos_block_ops_t: read, read_many, write, write_many, barrier, sectors, timeouts). AHCI and virtio-blk are descriptors; their init is their probe, and arch_hw.c binds every present block device in table order through one loop instead of initialising each by name and spelling out seven of its functions.

Interrupt vectors are handed out, not chosen. A PCI device has no legacy line to declare, so the descriptor's isa_irq is VIBEOS_DEVICE_NO_IRQ and the registry gives each table slot a vector of its own - slot i gets VIBEOS_DEVICE_VECTOR_BASE + i (48..63), passed to the probe in env->vector, one stub each in isr.S. The disks used to route their lines to 42 and 43, literals chosen by hand inside the legacy range, each with its own branch in the interrupt handler. vibeos_device_irq_vector dispatches to the slot; anything it cannot place is stray_vectors on the [DEV] line, a must-be-zero the gate asserts (device_stray_vector). Two rules in that dispatch, each with a host test and a sabotage case:

• it does not require the device to be present: a disk's probe is its init, which routes the line and then issues commands that complete by interrupt - before the probe has returned and the slot is marked;
• a device on a legacy line is never dispatched a vector: it was handed one it does not use, and a stray would otherwise become a keyboard read of port 0x60.

The probes moved after the kernel log exists (the disk drivers log). The counters left kmain's tlbq line - four weak defaults and four prints - for each driver's own report line, [AHCI] ahci_irqs=.. timeouts=.. and [VBLK] blk_irqs=.. blk_irq_completions=.. blk_poll_completions=.. timeouts=..; the gate's patterns were never anchored to the line, so they read the new ones unchanged. [DEV] registered= must now be at least 5 (keyboard, mouse, virtio-net and both disks are always built).

Block driver: 4 -> 1. One visible change: the adapters now bind in link order, AHCI first ([BLK] disks=.. disk=ahci:0 disk=virtio-blk:1). That was checked rather than assumed: which disk the machine boots from has been decided by mounting since I5, not by bind order, and the boot gate is green on both controllers.

Proved by the host test (env.vector == BASE + slot; a vector reaches that slot and no other; strays past the table, without a handler, on a legacy line and either side of the range call nobody; io-device.txt cases 11-13) and on the boot, every case red:

• io-device-block.txt (AHCI, 3 cases): its line routed to a registry vector nobody was given is device_stray_vector - about 5.9 million of them, because a level-triggered line whose handler never runs is never acknowledged - and ahci_interrupt_never_fired; the vector ignored (the driver polls, and the disk still works, which is exactly why only the counter can say so) is ahci_interrupt_never_fired; the count leaving its line is ahci_irq_counter_missing.
• io-device-block-vblk.txt (virtio-blk, 2 cases): blk_interrupt_never_fired and blk_completion_counters_missing.
• io-device-boot.txt case 4, the bind loop stopping after the first disk: verdict=boot_volume_missing. It first went red as a wedge - see below.

"Wedged" was a machine that had finished

That case first went red as missing:VIBEOS_SELFTEST_DONE verdict=guest_wedged, and so did the other two ways of losing the boot volume (case 1, an empty device table; io-device-fs.txt case 1, a FAT driver that does not declare itself). The serial log says otherwise. With only AHCI bound the kernel printed [BLK] boot volume on none, ran the built-in init, finished userland at once and sat at vibeos>. Nothing was hung. The gate was waiting for a self-test that lives on the disk that was not there, and after 45 seconds of an idle prompt it called the quiet a wedge and sent wedge_report to look for a hung core.

Carrying on without a volume is kept on purpose: the built-in init and the kernel console are worth having on a machine whose disk this kernel cannot read, which is the VirtualBox story in CLAUDE.md. What changed is that the kernel says so as a stage failure, [BLK] BOOT_VOLUME_FAIL: no disk carries a mountable volume tried=.., and the gate turns that into its own verdict, boot_volume_missing, ahead of guest_wedged and without the wedge report. All three cases now go red with that verdict. The same sabotage without the marker is guest_wedged, which is the before.

tried, not the existing rejected: rejected counts adapters passed over on the way to one that mounted, so when none mounts it is one short - the failing boot printed rejected=0x0 with one disk tried.

Step 3b: the registered filesystem, without its init call

FAT had a registry - vibeos_storage_register - and still cost four files: io_bringup.c called a register function by name, arch_x86_64.h declared it beside an ops accessor and two exported function pointers (the probe and the formatter, for the I4c exercise), and arch_hw.c declared the boot-volume mount extern. Now the driver declares itself with VIBEOS_FS_DRIVER into a linker section of its own; arch_hw.c registers whatever is there, once, at boot, before anything is mounted; and every caller reaches it through the table - vibeos_storage_driver(name) for the two that choose a filesystem rather than scan for one (the boot volume, which UEFI requires to be FAT, and the exercise that formats one), the scan for everything else. The storage core still takes registrations rather than walking the section, because PE/COFF has no __start_/__stop_ symbols and the Windows job builds that core.

Filesystem (registered): 4 -> 1. "Filesystem (direct)" - ext2, NTFS, exFAT and ISO9660, compiled into storage.c's probe table - is still 4.

Proved by a host test the registry never had (test_storage_driver_registry: whole-name lookup, a driver with no mount refused, reset) with two cases in storage.txt, and on the boot by io-device-fs.txt: the driver not declaring itself is verdict=boot_volume_missing (it was a "wedge"; see step 3a); a mount that ignores the volume it is given is red by name, format:FAILED:_also_on_the_root - after two fixes, below.

What the sabotage found: a check that had been blind for seventeen days

The second case went NOT RED, and the reason was two defects stacked.

1. The exercise could not see it. It formats a scratch volume, mounts it at /vol1, writes a file and reads it back through the resolver - which proves /vol1 reaches the scratch mount and that the mount round-trips. A mount of the boot volume does both, so the file went onto the disk the machine runs from and came back intact. It now also checks that the file is not visible at /, and says FAILED: also on the root.
2. The gate could not see that. Instrumented, the sabotaged boot printed result=FAILED: also on the root and the gate still passed: the assertion was "result=OK" not in text, anywhere in the log, and [IO] LOGSINK result=OK is on every boot. Both lines date from 2026-09-06 - the FORMAT check in I4c step 3, the log sink in I5b later the same day - so from then on no FORMAT failure could be reported. The gate reads the FORMAT line's own verdict now. The other two whole-log ..=OK tokens the gate uses (round_trip=OK, tls=ok) were checked against a log and appear on one line each.

Step 4: the display - the phase's "done when"

Before C7 the GUI was wired in: arch_hw.c declared five of its functions, initialised it from the framebuffer setup, repainted it from the timer, printed its counters and kept its canary, and serial.c named its putc through a weak default. It had no lock, and two of its three callers run on any core: the timer's repaint, and putc from the console write path - which is not always under the console lock (kmain's hex printer writes a character at a time with none). Two cores in putc could both pass row < ROWS before either scrolled, and the second wrote a row past the end of the grid, into whatever the linker put after it. The phase calls it the prime suspect for corrupting another process's memory; whether it ever did is not known, and now cannot happen silently.

It is kernel/io/gui.c now, a DISPLAY-class device, with the seven parts of docs/core/architecture.md:

1. A header, include/vibeos/gui.h.
2. All of its state in one file, in two kinds with one rule each: the terminal grid and the counters under the lock, every access; the back buffer, the screen and the pointer's last position owned by whoever holds g_ticking, which only the repaint takes, by exchange. The repaint copies the grid under the lock and draws from the copy outside it, so a console write never waits for a window to be blitted with interrupts off.
3. Its own lock, a vibeos_dev_lock_t. The lock operations are registered once, by the machine, for every driver (vibeos_device_set_lock_ops): a portable driver cannot build a lock, and registering each driver's lock by name from the arch would have put the driver back in arch_hw.c. The provider has one extra duty: lock returns -1 instead of waiting when the caller already holds it - the machine answers from the spinlock's owning CPU - so a panic printing from inside the GUI is dropped and counted (reentered) instead of waiting on its own core.
4. Counters with two must-be-zeros: term_overrun (a grid write out of bounds, refused) and guard_broken (the canary). The canary is the GUI's own now, written directly after the pixels and examined on every repaint, not once at the end of the boot; guard_checks says it ran.
5. An init that refuses by name: no framebuffer; too large; too small; a back buffer with no room for the canary; already active.
6. The registry's DISPLAY class: the console writes through vibeos_display_putc and the timer repaints through vibeos_display_tick; neither names a driver.
7. Case files: io-gui.txt (host), io-gui-torture.txt (the model and threads), io-gui-boot.txt and io-gui-backbuf.txt (the gate).

The font became include/vibeos/font8x8.h, a header: a constant table has no state, and as a .c module it would be judged by check-subsystem for a lock and a must-be-zero it has no use for.

Display: 3 -> 1. Nothing outside gui.c and its header names the GUI.

What building it found

• A screen under about 30 pixels high wrote off the end of the buffer. The text area's height is window - 26; on a 30-pixel screen that is 25 - 26, which is 0xFFFFFFFF, and the clamp if (y + h > g_h) wrapped y + h back under the screen - so the fill ran on. Width had the same shape below 10 pixels. No real screen is that small; init accepted any. It refuses them by name now, and every clamp compares before it adds.
• The character that wrapped the last row was lost. The old putc wrapped, found the row past the end, skipped the write and scrolled afterwards.
• A machine with no mouse never showed console text: the repaint returned before the text when there was no pointer.
• The pointer left fragments on the desktop. After a text repaint the old code forgot the pointer's position ("whatever was under the pointer is gone"), which is true only inside the text window. The torture's first run found it, comparing the screen with the composition pixel by pixel; its sabotage case puts the old line back.
• A registered driver in a static archive is not linked. Moving gui.c to kernel/io put it in the core library the image links as an archive, and an archive member is extracted only when something references it - which, for a driver that registers, nothing does. The boot came up with registered=0x5, the text console took the framebuffer, and the gate said gui_counters_missing. Such drivers are listed in VIBEOS_KERNEL_DRIVER_SOURCES, compiled into the image directly and into the host library for the tests; the gate's floor is six devices.
• A GUI that refused passed the gate. Every GUI check was conditional on [GUI] desktop up. The gate now fails gui_refused:<reason> when the text console had to take the framebuffer.
• [FB] no framebuffer; console is serial-only was printed on every boot that had a desktop - the text console's "else" was reached whenever the GUI had taken the screen. Three cases, three lines.
• backbuf_shared and backbuf_lost were must-be-zero and asserted by nobody. guard_broken led their line and check-mustbezero-asserted reads only the first name after the word; moving the canary exposed them.

How it is proved

• tests/kernel/gui_tests.c, in the host suite: the refusals by name with nothing written, the canary written and checked on the repaint and counted once, the terminal's rows, wrap and scroll, the wrap on the last row, the pointer drawn and not baked into the composition, reentrancy, the lock paired, and the display class choosing the first present display with both operations.
• tests/kernel/gui_torture.c (vibeos_gui_torture <seed> [rounds] [threads]): geometry at the edges of what init accepts, with both buffers fenced; the terminal against a model that keeps a list of lines rather than a grid; the screen against the composition, and the pointer visible; a flipped canary word; a print from inside the lock; then writers and two racing repaints on real threads, with every character accounted for. A short run in check.sh; the nightly job gui-torture runs 200 seeds under ASan and UBSan and the threads under ThreadSanitizer.
• The gate: gui_counters_missing, gui_term_overrun, gui_guard_never_checked, gui_refused, gui_backbuf_shared, gui_backbuf_lost, and device_table_short at six.

Every case red, and all but one by name:

• io-gui.txt (6, host): each by the test that names it. Removing the minimum screen accepted a 30-pixel screen and did not overrun: the clamps now compare before they add, so the two defences each hold alone.
• io-gui-torture.txt (4): no lock at all - the GUI as it was - is 71094 characters sent, 37897 counted from the thread phase; the pointer fragment is "screen differs from the composition"; a pointer not redrawn is "not on the screen"; an uncounted scroll disagrees with the model. The first version of the no-lock case removed the lock and kept the unlock, and went red on the single-threaded pairing check instead - which proved the wrong thing, so it was rewritten.
• io-gui-boot.txt (6) and io-gui-backbuf.txt (2): gui_counters_missing, gui_guard_never_checked, gui_term_overrun=483, gui_refused:back_buffer_missing_or_too_small_for_the_screen_and_its_canary, gui_reported_nothing, gui_terminal_empty, gui_backbuf_shared=1000, gui_backbuf_lost=1000.
• io-device.txt case 14, a display with no repaint handed out: red by name. Its first run was red as a crash - the test called the repaint before checking which display it had - and the test was reordered.

What CI found on the first push

The Windows job built the first VIBEOS_DEVICE descriptor in the portable library without complaint, and the nightly's new job - 200 seeds under ASan and UBSan, the threads under ThreadSanitizer - passed. The clang Debug job did not: UBSan stopped on store to misaligned address ... uint64_t in the canary. The canary sat straight after the pixels, and a screen with an odd pixel count puts that on a 4-byte boundary. gcc's UBSan, in the nightly, ran the same code and said nothing; one sanitizer's silence is not the other's.

It starts at the pixel count rounded up to even now, the size the caller owes is one macro (VIBEOS_GUI_BACK_BYTES), and init refuses a buffer that is not 8-byte aligned. The host test's screen is 201x151, so the odd case runs on every build rather than only on the torture's random screens. io-gui-ubsan.txt puts the old placement back and verify-host-sanitized.sh - the CI job's own configuration - reports the same error CI did (M-053).

check.sh all green, warnings 0 on gcc and clang, repeat-boot 6/6.

Where C7 leaves the rows

The objective said every row. One is not 1, by a recorded decision: a syscall is 2 (its row, and its declaration in abi.h). The other - the four filesystems compiled into storage.c - was closed afterwards; see the last section.

The last row: the four filesystems (2026-09-27)

ext2, NTFS, exFAT and ISO9660 declare themselves with VIBEOS_FS_DRIVER, as FAT did at step 3b, and nothing names them. They were named in four files: storage.c's probe table with a mount wrapper each, a member each in vibeos_volume_t, and io_bringup.c, which mounted the loop-device images through each driver's state, mount and ops. Now:

• The volume supplies the state. vibeos_volume_t has one opaque fs_state (VIBEOS_FS_STATE_BYTES, sized by NTFS's 4160) instead of a member per filesystem, and each driver asserts at compile time that its state fits. The caller keeping the storage is the block layer's existing rule - a driver with a pool of its own would have run out in the host tests, which scan more than once.
• Each driver states its order. NTFS 10, exFAT 20, ext2 30, ISO9660 40, FAT 50. The linker section they arrive in has no order, and the order is a correctness decision: NTFS and exFAT boot sectors are FAT boot sectors, and FAT's probe would claim them. Registration inserts in order.
• The volume's length reaches the driver, as mount's sectors - the authoritative bound of H-029, which the wrappers used to set on each driver's struct.
• A probe is optional. These four refuse through their mount; a refusing mount is "not mine", not "mine and broken".
• They moved from the core archive to VIBEOS_KERNEL_DRIVER_SOURCES. A registered driver in an archive is linked only if something references it, and nothing does - the GUI's lesson, again.

Two things went wrong on the way and both are cases now: registration still refused a driver without a probe, so all four were refused (on a boot, a panic at registration); and the host tests had to register the four themselves, because they do not walk the linker section. The scan zeroes the shared state before each attempt, because a refused mount leaves its fields behind.

check-blast-radius.py: filesystem (direct) 4 -> 1, total 11 -> 8. Cases fs-registry.txt (host) and fs-ext2-registers.txt (boot).

Noticed and left: the boot gate asserts the loop-device images of ext2 and ISO9660 by name, not NTFS's or exFAT's. They are mounted and reported every boot; nothing fails if they stop working.

Taking the dead code out, first increment

kernel/mm/vm.c and kernel/core/interrupts.c are gone, with their headers, their three syscall handlers, and their tests. 621 lines of kernel and three test functions.

They were not dead. They were built and never consulted

That distinction is the whole point, and it is worse than "dead code".

The live vibeos_kmain — the function that prints BOOT_OK — called all three of these on every boot:

vibeos_vm_init(&kernel->kernel_aspace);          /* line 42  */
vibeos_intc_init(&kernel->intc);                 /* line 80  */
vibeos_intc_bind_timer_irq(&kernel->intc, ...);  /* line 91  */

And nothing else in either file was ever called from anywhere the machine reaches. vibeos_intc_dispatch in particular has no caller outside its own file, so the timer handler that bind_timer_irq registered could not fire. The arch layer's IDT, initialised a few lines above it, is the one that runs.

So this is not a corner nobody visits. It is "configured and consulted by nobody" — the defect docs/core/ names as the one this project produces most often — at the scale of two subsystems, executed on every boot.

The three syscalls that went with them

VM_MAP, VM_UNMAP and VM_PROTECT operated on kernel->kernel_aspace, an abstract maps[] array that was never the machine's page tables. Whatever they returned said nothing about any mapping any process runs on. An external review flagged vm.c for exactly this — that an abstract model should not be read as hardware enforcement — and classified it correctly as informational.

What it cost on the test side, measured before cutting

kernel_tests.c had 64 references. They split cleanly:

The timer coverage is preserved rather than lost: vibeos_timer_on_irq is what the removed handler called, and the test drives it directly now.

And a mistake made rewiring it

vibeos_timer_on_irq returns 1 when the divider is satisfied and it ticks, 0 when it only accumulates, −1 on error. The removed handler discarded the value with (void) and the test checked vibeos_intc_dispatch instead, so the three-valued return was nobody's problem until it became the call being made. Replacing it with != 0 turned a tick into a failure. It is < 0 now.

What the removal proved about the tool that should have found it

check-reachable.py never flagged either file, and could not have.

It asks "is this function named anywhere outside the file that defines it?" — and these were named, by kmain.c and syscall.c, both of which are themselves unreached. The question cannot see "named only by code that is itself dead".

That limitation was written into its docstring as a deliberate trade: a real call graph would have to understand function pointers, which every registration seam uses, and would report the frame layer's lock as unreachable. The trade was the right one and it still cost this. The stronger version — a transitive walk seeded from the arch layer's entry points, treating any function whose address is taken as reached — is now recorded in that file as its next improvement.

The baseline is tightened to 12 in this change, from 27. It has been 12 for days; lowering it is a decision, and this is the commit that earns it.

What is left, and the order

kernel_tests.c is 9,028 lines and still holds roughly 330 references to that half — most of the largest test file exercises the kernel that does not run, which is part of why it is always green.

C3 says the choice between deleting and integrating is made by asking which produces the smaller diff in C4. The measurement for that now exists.

Second increment: kmain.c, and the claim it corrected

The previous section said kmain.c has "17 dead functions around one live entry point". That was wrong, and it was wrong by the exact method this file had just finished criticising.

It came from grepping which of its functions the arch layer names. Only vibeos_kmain matched, and the conclusion drawn was that the other seventeen were dead. But vibeos_kmain calls them. The question "who does the arch layer name" answers reachability only for the first hop.

A transitive closure seeded from vibeos_kmain alone reaches 16 of the 18. kmain.c holds the kernel CLI - the vibeos> prompt, status, meminfo, log - the boot log, and the boot-failure path. All of it runs.

Acting on the earlier claim would have deleted the CLI.

What was actually unreached: two functions, 47 lines of 915

vibeos_kernel_dispatch_trap wrapped vibeos_trap_dispatch_ex and added a KILL_CURRENT -> vibeos_proc_terminate step. The arch layer calls vibeos_trap_dispatch_ex directly and kills through hw_fault_kill_current_user, so this duplicated live functionality and no fault on the machine could reach it. It is also where the third review's process-slot finding lived.

vibeos_kernel_boot_health was an accessor for boot_health_flags. Checked before removing it, because the CLI prints health= on every boot and breaking that line would have been a silent regression in something visible: the CLI reads the field directly at kernel_cli_print_status, not through the accessor.

Their tests went with them - one whole test function that drove a path no fault can take, and one call replaced by the field it was reading.

The point, which is not the 47 lines

621 lines came out of the first increment and 47 out of this one, and the difference between them is entirely in the analysis. The same file looked like "834 lines of dead code" under the weak question and is "two functions" under the right one.

That is the argument for the transitive walk recorded in check-reachable.py as its next improvement, stated more precisely than it was there: the weak question is not merely incomplete, it errs in both directions. It missed vm.c and interrupts.c entirely - two subsystems built on every boot and consulted by nobody - and it would have condemned a live command-line interface.

Third increment: syscall.c, and a capability model that was never there

kernel/core/syscall.c (1502 lines) and kernel/core/syscall_policy.c (23) are gone, with test_syscalls (687), four functions in user/lib/user_api.c (52) and 18 lines of surgical edits elsewhere. 2282 lines.

Why this one needed a decision rather than a grep

The first two increments removed code that was unreachable. This one is different: C3 asks whether the portable syscall layer should be deleted or integrated, and the rule for answering is which choice produces the smaller diff in C4 - where the Linux ABI stops being 41% of arch_hw.c.

So the measurement came first, and it went against integrating:

Two switches. C4 wants a table - a syscall id mapped to the checks that apply to it - and neither of these is one. Integrating would have meant carrying 1502 lines of the wrong shape into the change that is supposed to fix the shape.

The 23 lines that were worth keeping, and are kept as prose

syscall_policy.c was the right shape: vibeos_syscall_policy_for(id) returning the checks a syscall requires. It is now written into docs/core/architecture.md as C4's starting form, because a 23-line file consulted by nobody is worth less than a paragraph read by whoever does C4.

That is the trade this increment makes explicit: a design does not have to be compiled to survive.

What the removal established, which is the actual finding

Chasing the callers of syscall_policy produced a fact worth more than the 2282 lines: vibeos_sec_* appears zero times in the arch layer.

The kernel that boots has no capability model at all. The one in kernel/core/ was a complete, correct, tested model that nothing on the machine consulted - the project's most-repeated defect, again, at the scale of a security subsystem.

C4 is therefore not "move the policy layer down". It is "there is no policy layer on the metal; write one". Deleting the file is what made that sentence sayable.

Two failures on the way out, both of the same family

The tests went red, and both reasons were more interesting than the removal.

A capability flag outlived its implementation. vibeos_user_api_capabilities() still reported supports_boot_event_signal, supports_process_security_label, supports_process_interaction_check and supports_policy_summary as 1 after the functions behind them were removed. This is "configured and consulted by nobody" inverted: not a mechanism nothing reads, but a declaration nothing implements - and a capability flag is read precisely to decide whether a function exists.

The assertion was inverted, not deleted: it now fails if any of the four comes back non-zero. A removed feature that still advertises itself is a defect whether or not anything currently believes it.

An assertion on the effect of a removed function. test_user_api_and_bootloader asserted vibeos_event_is_signaled(&kernel.boot_event)

• the effect of vibeos_user_signal_boot_event, which had just gone. Nothing signals that event now, so the assertion was not lost coverage; it was an assertion about a function that no longer exists. Removed.

What is left

process.c is the subject of C5 - "one owner of what a task is". Deleting it now would decide C5 sideways, in a dead-code commit, without the comparison C5 exists to make. The choice between it and hw_task_* is the phase, not a cleanup.

And the removal was reported finished twice before it was

Both times the evidence was a binary rather than the tree.

The stale assertion above was described as removed while it was still on line 884. What appeared to confirm that was running build-gcc-Release/vibeos_kernel_tests by hand: it printed ALL_TESTS_PASS, and it was built from an older tree - the verification script builds clang only, so the gcc binary beside it had never seen the change. Third instance here of "a green build is not a build", and the first where the stale artefact was reached for deliberately, as a second opinion.

The wrapper made it easy. It printed host-tests=FAIL kernel=1 on line 11 and [exited with code 0] on line 18, because the script's own exit status was the last echo. A summary whose verdict contradicts its exit code is a summary nobody reads carefully twice. It now checks every line it prints, ends with VERDICT=green|RED, and exits non-zero - the same rule check.sh already follows with rc=, applied one level up.

The first performance measurement this kernel has ever had

C0 of the core plan. Before this there was no benchmark, no timing, no budget and no regression gate, so every statement anyone could make about this kernel's speed — including a reassuring one — was invented.

The refactor adds indirect calls to the syscall, fault and switch paths. Without a baseline it could not have been shown not to have cost anything, in either direction, since an unmeasured reassurance is worth exactly what an unmeasured alarm is.

What is measured

Three hot paths, instrumented at one site each:

The syscall is timed at the dispatch rather than inside the handler, because what the refactor changes is the classify/marshal step an ABI translator adds — timing only the handler would miss precisely the thing being introduced.

The fault is timed at the call site rather than inside hw_handle_cow_fault, which has five returns: at the call site the measurement is one pair of reads and cannot miss an exit path. Only resolved faults are counted; an unresolved one ends in a kill or a panic, and folding those in would make the number drift with how often the machine crashed.

The switch is counted and not timed. That function is the switch — it ends by installing cr3 and returning into the next task — so there is no second point at which to stop a clock.

Two things the first measurements corrected

The mean is not a baseline. The first boot read 46 million cycles per syscall. That is not dispatch cost: a syscall that blocks is timed across the block, so the number was reporting how long waitpid waited. It would have moved with anything that changed scheduling — the opposite of what a performance ratchet is for.

The minimum replaced it. A blocked task cannot lower a minimum, and an added lookup or lock on the path raises it. The syscall minimum is around 600 cycles, against a mean sixty thousand times larger.

The counts are not deterministic. They were going to be described as such, and ratcheted on that basis, on the reasoning that the same boot does the same work. Six boots:

Syscalls move 4.7% across the range, faults 18%, switches 21%, and the syscall minimum itself 41%. Nothing here can carry a tight ratchet, and a threshold written from the first sample would have been wrong.

This is the memory manager's P2 mistake caught from the other side: that phase was judged for a day and a half against "48 boots with no failure", a criterion measured against a background nobody had characterised. Taking the second measurement before writing the criterion is what this project's own rule asks for, and it is the only reason the false claim did not ship.

The trend that was not one

Worth recording in full, because it happened while this file was being written.

After five boots the counts were decreasing monotonically — 1416, 1381, 1383, 1370, 1352, and faults 396, 378, 366, 353, 335. A monotone run of five is not what scatter looks like, and this file said so: it named a suspect (qemu-cli-logdisk.img, the one piece of state I5b deliberately keeps across boots, whose attach scan grows with it) and called for a five-boot sweep with the image deleted to settle it.

The sixth boot went back up. Faults 335 → 369, switches 426 → 453.

So it was scatter, and the paragraph explaining it was a mechanism invented to fit five points. Nothing was wrong with the reasoning except that it started. The rule this project already has for detectors — the first question is whether the detector is right, and it is never answered by a count — applies to a baseline reading its own numbers, and five samples on a machine with 20% spread is a count.

The log disk remains a reasonable thing to test for drift. It is no longer evidence of any.

What is gated

Only that the counts are non-zero.

That is deliberately weak and it is the assertion this project keeps needing. VIBEOS_BLK_TIMEOUT was defined, printed, asserted by the gate and produced by no driver. A disk-interrupt counter read zero for an hour because its dispatcher hook had never been added, and sent four measurements in the wrong direction. A counter nothing increments and a counter reporting nothing happening are indistinguishable, so before any of these numbers can be reasoned about, something has to establish that they can move at all.

Also gated: cycles accumulated without events, or events without cycles — half a pair is worse than neither, because a mean built from one of the two reads looks like a measurement.

The ratchet is deliberately not here. It needs a characterised spread, and the six boots above are the start of collecting one rather than the end.

Cost of the instrumentation

Two rdtsc and one atomic add per event; the minimum uses a compare-exchange loop, which by construction cannot spin, since each retry means the value strictly decreased. Under TCG that is far below the cost of the event being measured.

One boot in the sweep reported stress_run_did_not_finish before the minimum tracking was added, and the boot before it had passed. Two boots decide nothing on a machine with a known intermittent failure, and the four boots since have all passed with the instrumentation in — so it is not attributed to the instrumentation, and it is not attributed to anything else either.

What this says about the next phases

architecture.md states that registration must be resolved once and not per call, and that an indirect call may not be added to the three hot paths without a measurement showing what it cost. That measurement now exists, and its first lesson is about its own limits: on this machine, under TCG, the noise floor is wide enough that a seam adding a handful of cycles will not be visible. What will be visible is a lock or a per-call lookup, which is the failure the rule was written for.

The fault minimum is around 700,000 cycles, which is large. The copy-on-write fault sends a TLB shootdown IPI and waits for the acknowledgements, so most of that is likely the round trip. Likely, not measured — under TCG the emulated cost of an IPI bears no fixed relation to a real one, and this project has a rule against reasoning about a number like that without a second source.

Revising the kernel core plan

The plan in docs/core/ was written, challenged four times, and rewritten end to end against four requirements: maintainable, modular, observable, fast, with the size of arch_hw.c treated as a symptom rather than a goal.

This file records what the revision changed and, more usefully, what measuring found that reading had not.

The criterion was wrong, and had already failed twice

The first plan's completion criterion was the length of arch_hw.c. That criterion has been used twice in this project and failed both times: once the file grew by 633 lines during a session whose stated purpose was shrinking it, and once by 2,800 during the I5/I5b work — both times while the document naming its length as the criterion sat unchanged in the repository.

A file grows because adding to it is the path of least resistance. Cutting it does not change that. So the criterion is now blast radius: how many files you must edit to add one thing of a known kind.

It is already a controlled experiment rather than a theory:

Four filesystems and four block drivers arrived without their layers being edited. Everything else arrives by making the monolith bigger. The rule that follows was rediscovered independently eight times — there are eight registration seams in the tree, each invented separately by somebody solving one problem — and never named until now: a subsystem is extended by registering into it, never by editing it.

Three things measurement found that the previous plan had wrong

The scheduler phase is already done. hw_pick_next calls vibeos_sched_policy_pick, and falls back to vibeos_runq_pick rather than idling — deliberately, because a task the policy was never told about is an admission bug, and refusing to run it would turn that bug into a hang instead of a slower machine. The plan had it as a future phase. It is recorded as done rather than deleted: a plan that quietly loses a finished phase cannot be audited.

Observability is much thinner than the tooling suggests. The kernel prints 25 distinct report tags and has five must-be-zero counters in the whole tree: frames_leaked, medium, double_free, bad_unlocks, illegal_transition. Against 48 sabotage case files and a 2,020-line boot gate, that is not a tooling gap, it is a coverage gap — most subsystems report what they did and nothing about whether it went wrong. Every hard defect in this project's history was found by a counter or a detector, so observability got its own phase, placed ahead of every phase that moves code.

Performance has never been measured. Not once. No benchmark, no timing, no budget, no regression gate. The architecture adds indirect calls to paths that run millions of times a boot, and with no baseline the refactor could not be shown not to have cost anything — in either direction, since an unmeasured reassurance is worth exactly what an unmeasured alarm is. The baseline turns out to be cheap to start: the boot gate has been recording phase_history since it existed and nothing has ever read it.

The structural claim that reordered the plan

arch_hw.c measured: 10,087 lines in 19 sections. Every section now has a destination in docs/core/architecture.md. Summed, 7,726 lines leave and about 2,360 stay — the parts where a second architecture would need a different answer, not the same answer implemented differently.

The largest single block that leaves is the Linux ABI: the syscall layer (679), the socket syscalls (1,654), what a program needs once running (651) and what a C runtime asks for before it runs (1,185). 4,169 lines, 41% of the file — and it is exactly what the next refactor on the roadmap has to move anyway.

So the file cut and the multi-ABI syscall layer became one phase instead of two. Splitting them was the previous plan's worst decision: cutting first produces four smaller files with the same shape, which all get rewritten when the ABI interface arrives. Building the interface first and moving the code through it does the work once, and is the only version in which the cut is verifiable — code that moves behind an interface either satisfies it or does not compile.

An ABI is a registered translator (classify, marshal, result), never a branch in the dispatcher. Three ABIs as three branches is three copies of every permission check, and the checks are where every security defect in this project has been found.

What is now watched that was not

check-reachable.py is written and running: for every function in the portable kernel, is it named anywhere outside the file that defines it? It reports unreached=12 baseline=27, ratcheted downward only.

It is a deliberately weaker question than "is it reached from the boot path". A real call graph would have to understand function pointers, which every registration seam uses, so it would report the frame layer's lock and the task view as unreachable — the kind of confidently wrong answer that teaches people to ignore a check. "Nobody names it" is coarse, almost never wrong when it fires, and catches every case this project has actually had: a portable dispatcher no process reaches, a scheduler policy the boot path did not consult, a page cache with no caller, four filesystem drivers that had never parsed a byte.

The two entries that matter are kernel/core/syscall.c (1,477 lines) and kernel/proc/process.c (1,115). The arch layer names vibeos_syscall zero times. That code carries three uncorrected defects — thread creation with no check on the caller, a process slot that is never freed, and a caller identity read from an argument the caller supplies — and the plan's hardest gate says nothing there may become reachable from ring 3 until they are closed. Not afterwards; not in the same change.

Three more checks are specified and not yet written: check-subsystem.py (the seven parts), check-blast-radius.py (the table above, ratcheted) and check-chokepoints.py (each security check declares its call-site count, so a second site is noticed rather than forbidden).

The rule this revision is itself an instance of

Every correction above came from running something, not from reading. The scheduler was assumed unreached until grep said otherwise; observability was assumed adequate until the must-be-zero counters were counted; the ABI's share of the file was a guess until the section banners were measured against line numbers.

That is the same rule the case files keep arriving at from the other direction: when a detector fires, the first question is whether the detector is right, and it is never answered by a count. A plan is a detector for what is wrong with a codebase, and this one was firing on the wrong thing.

The copy-on-write page that keeps the parent's contents

The oldest open defect here, and the one the memory-manager rewrite was written for. This file records what is now known about it, because four earlier investigations each ended at a plausible pointer with no mechanism behind it, and two of them were wrong in ways that cost days.

The symptom

svc-stress, round 5 or 6, reports:

STRESS_FAIL: the child's own copy-on-write page at offset 0: found 0x33 expected 0xcc
STRESS_FAIL: verdict=the page was private and changed anyway

0xcc is ~0x33, and the program computes after = ~before, so the child is reading back exactly the value the page held before the fork.

What has been established

A reproduction came first, and everything below rests on it rather than on reading the code.

It reproduces on demand. check.sh all build-clang-Release fails three times out of three. Local gcc builds boot 8/8 clean, which is why this went unreproduced for so long - and it is the second time here that a defect lived in the configuration nobody ran by hand.

It is not a race. Forced to a single core with -smp 1, it still fails three times out of three. That removes every concurrency explanation, including the TLB-shootdown family that had been the leading theory, and makes the defect deterministic enough to reason about.

The copy does happen. The four page samples say so:

The frame changes on the child's first write, which is copy-on-write working, and it does not change again.

The frame is private and stays private. owners == 1 at the check, and the frame is the same one the write went to.

The whole page is stale, not one byte. 4096 bytes of 4096 differ. This is the measurement that mattered most and it was the last one taken: the check reports the first byte that differs, which is always offset 0, and that was read for an entire session as "only offset 0 is wrong". It is equally consistent with every byte being wrong, and every byte is. Those are different defects - a few stale bytes is a copy racing a store; a wholly stale page is a write that went somewhere else entirely.

What has been ruled out, each by a detector rather than by argument

• A frame freed while still mapped. The existing free-side watch was turned up from one free in sixty-four to every free. Silent for the whole boot.
• A frame handed out while still owned. A new counter in frame_take (double_allocs, printed in MM_STATS and asserted zero by the gate) watches the allocation side, which nothing watched before. Zero.
• A write to a freed page. poison_hits is zero.
• Global TLB entries surviving a CR3 reload. There is no global bit anywhere in this kernel and CR4.PGE is never set.
• The two user windows having different mapping rules. hw_map_low_user_page is a thin wrapper on hw_map_page; they are the same code.

Where the next attempt should start

The child writes 4096 bytes and reads back 4096 bytes of the pre-fork value, from a frame that the page tables and the ownership count both say is its own, on a single core, deterministically. Either the stores did not land in frame 3020, or the reads did not come from it.

The next measurement should therefore not be about ownership or lifetime - both are now instrumented and clean - but about which frame the CPU actually used: have the child write one byte, then ask the kernel to read that page through the identity map and report what it sees. If the kernel sees after and the child sees before, the mapping is right and the child's translation is stale. If the kernel also sees before, the store never reached the frame at all.

Note also that the write loop is compiled by clang at -O2 and the defect is clang-only so far; whether that is a vectorised store pattern or simply a different allocation order has not been established, and should not be assumed either way.

The sharpest fact so far: mappers=2, owners=1

A repeat-boot run caught the release-side watch firing, and its message is the most precise statement this defect has produced in five investigations:

[MM] FREE_WHILE_MAPPED frame=0x2355000 still mapped by pid=0xb
     during destroy mappers=0x2 owners=0x1 owners_now=0x1

Two address spaces map the frame; the ownership count knows about one. That is not an arithmetic error in the count - it is a mapping that was installed without taking a reference, which is exactly the failure the memory-manager rewrite was proposed to make impossible.

It is reported during a destroy, and specifically a destroy of an address space that is not the current task's - the arch-level short circuit for "the dying task legitimately still maps what it is freeing" did not apply. So the path is a task tearing down somebody else's address space: exit being reaped, or execve discarding an old image.

vibeos_vmspace_map_raw takes its reference before publishing the entry, and clone_one goes through it, so neither fork nor an ordinary map is the uncounted one. The next attempt should look for a page-table entry written without going through that function.

Why these counters exist

The condition appears about one boot in sixteen. A message alone therefore makes every run a lottery in which "nothing reported" and "fixed" are indistinguishable - which is how three earlier fixes here were believed. Two counters now make each boot a measurement:

• double_allocs - a frame handed out while somebody still owns it. Nothing watched the allocation side before, and it is the blind spot that matters: a double allocation frees nothing, so every release-side watch stays silent.
• free_while_mapped - more mappers than owners, counted rather than only printed.

Both are on the MUSTBEZERO line and the boot gate fails if either is non-zero. The assertion was confirmed to go red by making frame_take count unconditionally: mm_double_allocs=4813.

The free-side walk now samples one release in eight rather than one in sixty-four. A counter that only sees one free in sixty-four cannot be compared between two states, which is the whole point of having it. Eight clean boots out of eight at the higher rate.

Asking a second observer, and what it settled

pageinfo now returns first_word: the first eight bytes of the frame as read by the kernel, through its own mapping rather than through the caller's. The whole value of the field is that it does not use the translation under suspicion. Two runs settled two questions that five investigations had not.

The store never reached the frame. In the failing round the child wrote 188 to all 4096 bytes; immediately afterwards the kernel read 239 at byte zero of the frame the page tables point at - and 239 is the pre-fork value. So the copy is intact and untouched, and the child's writes are simply not in it. The reads are fine: child and kernel agree on what the frame holds.

The page itself works. After the failure, the child stores one ordinary byte, 0x5a, and samples again: child reads 90, kernel reads 90, same frame. The mapping is right, the frame is right, the permissions are right, and an ordinary store lands immediately.

So nothing is wrong with the page. What is lost is specifically the write loop.

The write loop, and why this is not "a test bug"

for (i = 0; i < 4096; i++) mem[i] = after; is not 4096 byte stores by the time clang has had it. Making that loop volatile - so each byte is a separate ordinary store - makes the failure vanish: three runs out of three clean, where the same tree failed three out of three.

What the binaries do contain is movaps and movdqa - ordinary 16-byte aligned SSE stores - and no non-temporal stores at all, so no missing fence explains this. Ordinary SSE stores are cache-coherent and atomic with respect to faults: architecturally there is no reason for one to be lost.

One measurement here was taken wrongly and is recorded so it is not taken again. Counting wide stores across the whole binary gives gcc 18 and clang 172, and that was briefly written down as evidence that clang vectorises this loop and gcc does not. It is not evidence of anything: the same two counts come back unchanged when the loop is made volatile, so they are counting other code entirely and never described the fill loop. The restore that was supposed to put the loop back had failed silently first - the backup was in /tmp, which WSL had cleaned, which is a trap this project has already written down once. The volatile result itself was measured correctly and stands; the disassembly comparison did not and does not.

The loop has therefore not been made volatile, and must not be. A volatile loop would turn the boot green while leaving the defect exactly where it is, and this file already records three fixes that were believed on that kind of evidence. musl's own memset uses the same instructions, so if a wide store to a freshly copy-on-write-resolved page can be lost, it is lost for every program on this machine and not only for the one that noticed.

Where the next attempt should start

The question is now narrow and mechanical: what happens when a 16-byte SSE store, rather than a byte store, takes the copy-on-write fault?

The child's first movaps faults on a read-only shared page. The handler allocates a frame, copies the old one into it, installs the entry and invalidates. The instruction is then retried by hardware. Something in that sequence loses the retried store while a byte store survives it, and the candidates are few enough to check one at a time:

1. Whether the fault is even reported the same way - the error code, and whether hw_handle_cow_fault accepts it.
2. Whether the retry happens at all, or the handler returns to the following instruction. A skipped rep-like vectorised block would lose the whole fill, which is precisely the symptom.
3. Whether the copy runs after the retried store rather than before it.

Instrument the fault handler to log the faulting rip and the fault count for this page. If the page faults once, the store was lost after a successful resolution; if it faults twice, the second fault is the interesting one.

The page faults once, and there is more than one failure here

The fault handler can now log every copy-on-write fault with its faulting rip - built with -DVIBEOS_COW_FAULT_TRACE=1, off otherwise, because a line per fault is hundreds of lines in a boot: it floods the log the gate reads and it changes the timing of the defect it is looking for. An unhandled fault is rare and always worth a line, so that half is unconditional.

It answered the question it was built for. The page that loses a wide store faults once: va=0x8004000000 ... handled, and nothing further. So the store is lost after a successful resolution, not to a second fault that nobody handled.

It also showed something that changes how these runs should be read. The failing round is not always the same defect. One run reported:

STRESS_FAIL: the child's own copy-on-write page at offset 0:
  found 0x00 expected 0x68 - this is the kernel's free-page poison:
  the page was reclaimed while still mapped here

All zeroes, which is what frame_take fills a page with - so that page was properly freed and then legitimately reallocated to somebody else while this process still mapped it. double_allocs is zero, so the allocator was not at fault; something released the frame without the ownership layer noticing.

That is the same family as the mappers=2, owners=1 event, and a different defect from the lost wide store. Both hide behind one sentence from ring 3 - "the bytes are not what I wrote" - which is exactly the confusion pageinfo was added to end, and it is why the four verdicts the stress service prints matter more than the byte values.

Two defects, then, not one:

1. A wide store lost after a resolved copy-on-write fault. One fault, page healthy afterwards, an ordinary byte store lands. clang only so far.
2. A frame released while an address space still maps it. Reported both as mappers=2 owners=1 at a destroy and as a page of zeroes handed to a live process.

Previous investigations treated these as one, which is a large part of why each of them ended somewhere plausible and wrong.

The lost wide store is TCG, not the kernel

Two more measurements finished this half.

The child reads the old value from its own page with no kernel in between. Every earlier observation went through page_sample, which is a syscall - so "the child sees the wrong value" had always been seen on the far side of a kernel entry. Reading mem[0] straight after the loop, before any syscall, returns before: the loop wrote 60 to all 4096 bytes and the next instruction to look reads 195.

The parent's page is untouched. 0 bytes of 4096 differ, parent and kernel agree, so the stores did not go to the shared frame either. They went nowhere.

And it does not happen on real hardware. Same binary, same kernel, three runs each:

The argument that settles it does not rest on that table, because this project has been misled by a KVM-clean result before - twenty clean runs once validated a setup that pure TCG broke in two runs out of three, which is why every script here forces TCG. It rests on where the store happens: once the fault handler returns, the faulting instruction is retried by the CPU with no kernel involvement at all. The kernel cannot lose a store it does not take part in. Everything the kernel is responsible for has been shown correct - one fault, handled, a private singly-owned frame, the right contents copied into it, and an ordinary byte store landing in it immediately afterwards.

The strongest evidence is not the KVM run at all - it is in CI, and it holds the emulator constant. Of the five jobs on this commit, exactly one fails:

Same kernel, same TCG, same machine, same test. The only thing that changes between the clang job that fails and the clang job that passes is the optimisation level - that is, whether the fill loop is vectorised. A kernel defect does not know about -O2.

The last piece came free from the disassembly. svc-stress has another operation that fills a fresh mmap page with the same movdqu instructions and checks it, and that one passes. So:

• wide store, no fault - works
• byte store, copy-on-write fault - works
• wide store, copy-on-write fault - lost

which is a statement about restarting a 16-byte store after a page fault, and that is the emulator's job.

What this means for the gate

The boot gate forces TCG, deliberately and for good reasons, so CI will keep failing here until something is done. The options are not equal and the choice is not obvious:

• Make the fill volatile. One line, and it is exactly the kind of change this file warns about three times: the boot goes green and nothing is understood. It is defensible only because the kernel has now been shown not to be involved, and it should carry a comment saying so.
• Keep it and accept a permanently red gate, which trains people to ignore it.
• Narrow the assertion so this specific operation is reported but not fatal.

This is a maintainer's decision, not the investigation's, and it is left open here rather than settled quietly.

What is still open

The other defect is untouched by all of this: a frame released while an address space still maps it, seen as mappers=2 owners=1 at a destroy and as a page of zeroes handed to a live process. That one is real, it is the kernel's, and it is what the memory-manager rewrite exists for.

Seen again, 2026-09-11

Boot 3 of the twelve-boot series that verified interruptible waits:

[MM] FREE_WHILE_MAPPED frame=0x22ba000 still mapped by pid=0x14
     during destroy mappers=0x2 owners=0x1 owners_now=0x1 at_va=0x80003ff000

The same path and the same counters as the signature above, during svc_bomb's fork storm. Not attributed to that change: it touched blocking waits, not fork, reference counts or teardown. The rate on that series - one in twelve - says nothing either way against the one in sixteen recorded here.

What the recurrence adds is at_va, which the original did not carry. The frame is the top page of a native program's stack, in the 0x8000000000 window. That narrows "a page-table entry written without going through map_raw" to whatever builds or copies a native program's stack. It is a direction to instrument, not a finding.

Two checks about the checks

Status: both in check.sh, both sabotage-verified, and the second found a real defect on its first run.

Why

Counting today's work honestly: of the defects found, more were in this kernel's detectors than in the code they watch — a poison check reading uninitialised state, frame accounting sampled from a machine that was still forking, a trap dump reporting the plan instead of the outcome, a deadlock reporter that took the console lock and therefore deadlocked, a diagnostic that cleared its own evidence before it was read.

The tempting response is a framework that all detectors are written against. That is the wrong answer: those five have different causes and only look alike because they were found together, and an abstraction over them hides them better rather than preventing them.

Two of the shapes, though, are mechanical, and both were present in the same defect. VIBEOS_BLK_TIMEOUT was defined, printed by kmain, asserted by the boot gate, and produced by no driver — so the assertion was green by construction for as long as it existed, and it took reading the source to find. Neither half needs judgement to detect.

check-assertions-covered.py

Every name the gate can put in reason=, against every sabotage case in scripts/dev/cases/. An assertion no case mentions has never been observed failing and might not be able to.

115 assertions; 7 covered. That number is the finding.

It is a ratchet, not a target: zero would start red, and a check that starts red is one nobody reads — this project has a rule about that. The baseline is what the tree had when the check was written and may only go down. What it catches from day one is a new assertion arriving without a case, which is exactly how BLK_TIMEOUT happened.

It does not claim that a case was run or that it turned that assertion red — only that somebody wrote one. That is the cheap half, and the half that hides an assertion which cannot fire.

check-counters-produced.py

Every field of every reported stats struct, against every ++, += and non-zero assignment in the tree. A counter nothing increments is an assertion that cannot go red.

It found one immediately: vibeos_rmap_stats.cycles. The boot gate asserts rmap_cycles is zero. Nothing had ever written to it — vibeos_rmap_init did not even reset it — so the check was BLK_TIMEOUT again, in a different subsystem, and had been since the counter was declared.

Worse, the thing it was declared for was real and unguarded: every list walk in rmap.c was while (cur != RMAP_NONE) with no bound. A cycle is not a wrong answer there, it is a core that never comes back — and this kernel has had exactly that, when the node pool was carved after vibeos_frame_init and user pages overwrote the lists, leaving CPU#0 in vibeos_rmap_add for the rest of the boot. The walks are bounded by the pool size now, and hitting the bound is what produces the counter.

It also found vibeos_reclaim_stats.skipped_pinned dead: vibeos_anon_reclaim does refuse pinned frames and never said so, so "reclaim found nothing to take" and "everything reclaim looked at was pinned" were the same silence — and one of those is the kernel holding memory it will not give back.

The exemption list is the point as much as the failures

Eighteen counters are declared and legitimately unproduced: reporting that exists ahead of the phase that will fill it, which is the order this project's plans use deliberately. Each one names its phase. An entry parked there because it is inconvenient would be this check's own defect wearing a permission slip, so a stale exemption — one the tree now produces — fails too.

What it cannot do

It matches by field name across every watched struct, so two structs sharing a name cover for each other: io_stats.cache_hits reads as produced because mm_stats.cache_hits exists, and those are different caches. Fixing that needs to know which struct an expression belongs to, which needs a C parser. The limitation is named in the tool rather than papered over, because a checker that quietly gets this wrong is the exact failure the checker is for.

Confirmed by breaking them

An assertion added with no case: assertions-covered=FAIL uncovered=109 baseline=108. A producer removed: counters-produced=FAIL ... nothing ever increments: vibeos_rmap_stats.cycles.

What is deliberately not automated

"A detector must not depend on the thing it watches." "Evidence must not be cleared before it is read." "A threshold comes from a distribution, not from one measurement." Those are judgements, and they belong in CLAUDE.md with the other lessons — where three of them already were, and were broken today by somebody quoting them.

Diagnostics and Observability Progress

Status: In Progress (six runtime detectors, all gated; they found and closed the premature-free defect that had been chased three times from the far end) Last review: 2026-08-29

Everything here exists because of a specific bug that cost hours, not because it is good practice in general. That is the selection rule: a detector earns a place by being able to name a failure this project has actually had.

The recurring shape of a hard bug in this kernel is that it surfaces a long way from its cause - in a different program, minutes later, as a pointer that makes no sense. Every item below shortens that distance.

Implemented

Poisoned freed pages

hw_free_page fills the page with 0xDEAD0000DEAD0000 before putting it on the freelist, and hw_alloc_page samples the poison when handing a recycled page back out.

A freed page used to keep its old contents, so a use-after-free read plausible data and the program carried on until something unrelated broke. The pattern is non-canonical as a pointer, so the first dereference faults instead of the tenth one corrupting something. The re-check on allocation reports a write to an already-free page at the moment it is discovered.

Gate: use_after_free_detected.

Console-lock hygiene

vibeos_x86_64_serial_unlock refuses an unlock from a core that does not hold the lock, and counts the attempt; bad_unlocks is printed with the memory statistics and the boot fails if it is not zero.

One missing serial_lock() in hw_log_emit freed the lock out from under another core mid-line. The markers the boot gate matches on were cut in half and the gate reported failures that had never happened - two crashes were investigated in full before the split was noticed.

Gate: console_unlock_by_non_owner.

Log-integrity check

interleaved_lines() in the boot gate runs before any other assertion, because every other assertion reads the same text: a split line can invent a failure or hide a real one.

It reports a line when a hex field is cut short (0x with no digits and a tag following - the kernel always prints its values in full) or when a second tag follows a kernel tag. A line opened by a ring-3 write is exempt: a program may write without a trailing newline, and the first version of this check called that a defect and cried wolf on its first run.

It carries self-tests against real lines from real boots, including one that must not be flagged. Known limit, in the docstring rather than left to be rediscovered: a split inside a ring-3 write that truncates no number is not caught here - the bad-unlock counter guards that case.

Found, over three runs: eight multi-part kernel messages assembled without bracketing - [EXEC] three times, then [SIG] deliver, [SIG] tkill, [SIG] tgkill, [SCHED] fork lost its slot and the unimplemented-syscall notice. serial_puts and serial_print_hex each take the lock on their own, so an unbracketed six-part line is six critical sections. All eight fixed; the check kept finding the next one each time the previous was fixed, which is what a working detector looks like.

Gate: serial_log_interleaved(N_lines).

The kernel's own complaints are now assertions

Any [LOG][WARN], [LOG][ERROR] or [LOG][FATAL] line that is not on a short allowlist of deliberately provoked ones fails the boot.

The kernel has had levelled logging for a long time and not one of its warnings had ever failed a build. This is the same lesson as the ring-3 self-test that printed abi: ...wrong for a whole session while the gate stayed green.

The allowlist is deliberately short and specific. Adding a pattern to quieten a real warning is how this mechanism stops working.

Gate: kernel_reported_problems(N).

Crash records

A ring-3 fault is captured at the moment it happens - registers, vector, error code, fault address, the executable's path, and as much of the user stack as is readable - into a ring of four. crash on the kernel console prints the last one in full.

A faulting process used to leave two numbers behind, rip and cr2, printed once and gone. Every hard bug here was then diagnosed by going back for the registers, the stack and which binary the task was running - by which time the process no longer exists. The record names the executable because an address alone identifies nothing when every Linux program links at 0x400000; that omission produced three wrong diagnoses of a single address.

The gate drives crash every boot, because svc-crash faults every boot: a dumper exercised only when nothing has crashed proves nothing.

Gate: fault_was_not_recorded, crash_record_does_not_name_the_program, crash_dump_found_no_record.

Seeded stress service

svc-stress (user/prog/svc_stress.c, staged as SVC_STRS.ELF) runs 120 rounds of randomised fork, anonymous mmap, copy-on-write and pipe work, in a different order each boot, checking the result of every operation. The seed is printed on its first line, so a failure replays: EFI/BOOT/SVC_STRS.ELF <seed>.

The boot otherwise runs one fixed script, which produces the same handful of interleavings every time and can only find a race by luck - which is how the last three were found, one boot in thirty, after a lot of waiting.

Its failures name what they found rather than that something was wrong, and they recognise the free-page poison: "the page was reclaimed while still mapped here" is a different investigation from "the data was wrong".

Gate: stress_seed_not_reported, stress_run_did_not_finish, stress_run_found_a_defect.

Panic records

A kernel panic prints which core noticed, and then one line per online core: its task, pid, state, cr3, and the executable that task was running.

A ring-3 fault has had a full crash record for a while; a panic had a backtrace of the single core that noticed and nothing at all about the other three. Every wedge investigated in this project needed exactly the missing part - which core was on which task, and on whose address space - and it had to be dug out of QEMU's monitor from the host afterwards, when it could have been printed at the time for the cost of a loop.

The per-CPU blocks are read directly rather than stopping the cores with an IPI. This is a machine that is about to halt, and a round trip is the kind of thing that hangs instead of reporting; a slightly stale line is worth more than no line.

Verified against a real panic, not a synthetic one: removing the branch that kills a faulting ring-3 task turns svc-crash back into a machine halt, and the record then names it -

FATAL: unrecoverable CPU exception, halting on cpu 0x2
[PANIC] cpu=0x2 ... pid=0xa state=0x2 cr3=0x21d5000 exe=/EFI/BOOT/SVC_CRSH.ELF

What these found

The premature free, and what closed it

hw_sys_munmap freed the frame behind every user page it unmapped, outright, with no frame_ref_dec. That is correct only for a page nobody else has - and after a fork, that is the rare case rather than the common one. Unmapping a copy-on-write page therefore put it straight back on the freelist while another process was still running from it.

This is the same defect that had already been chased three times from the far end, each time presenting as something else entirely: a musl program tripping over its own malloc bins, init printing a pointer where a pid belonged, a forked child reading back a value it had not written. Each investigation ended in a plausible-looking garbage pointer and no mechanism.

What closed it was two detectors meeting. The stress run produced the failure on demand instead of one boot in thirty; the free-page poison told it what the wrong bytes were. The message it printed named the mechanism outright:

STRESS_FAIL: the child's own copy-on-write page at offset 0:
  found 0x0 expected 0x96 - this is the kernel's free-page poison:
  the page was reclaimed while still mapped here

From there the fix was one call, and 48 local boots passed without a recurrence.

It came back. The nightly of 2026-08-30, running a commit that contained the fix, reproduced it: seed 170000012, round 18, the same free-page poison in a child's own copy-on-write page. So munmap was one premature-free path and not the only one, and the claim that the family was closed was made on the strength of local boots that could not see it. Both statements have been corrected here rather than left standing.

Freed pages now also record who freed them: the freelist link takes the first word of a reclaimed page and the caller's name goes in the second, so the next occurrence names the function that released it instead of only proving that something did.

Driving VirtualBox from the harness

scripts/dev/vbox-run.py imports the shipped appliance, boots it headless with the serial line to a file, watches for the boot markers, and takes the guest apart if it stops talking: per-core registers through debugvm getregisters, symbolised with addr2line against the kernel ELF, the guest paging mode, and optionally a full ELF core through debugvm dumpvmcore (about a gigabyte). It removes the VM afterwards unless asked to keep it.

A second hypervisor is not a luxury here. VibeOS could only talk to virtio-blk for months: the appliances imported, booted, and could not read their own disk, and nothing caught it because nothing ever ran the artifact by hand. And VirtualBox inspects a stopped guest better than the QEMU monitor does - a full guest core is the right answer for a wedge, where pushing megabytes through a serial port is not.

python scripts/dev/vbox-run.py            # boot, watch, clean up
python scripts/dev/vbox-run.py --core     # write a guest core if it hangs
python scripts/dev/vbox-run.py --keep     # leave the VM registered

Windows-side, because that is where VBoxManage lives; addr2line is called through WSL, because that is where the toolchain that built the kernel is.

Static analysis

CodeQL runs on every push. Four alerts were open and each was answered on its merits rather than silenced:

Crash collector

scripts/dev/report-crash.py reads crash records out of a serial log and collects them into a single GitHub issue, one comment per distinct crash. It is the "send a report" every desktop OS has, with three rules that keep it useful rather than noisy:

• The guest never sends anything. VibeOS writes a crash record to its console and stops there. The reporter runs on a host, on an explicit command, on a log somebody chose to hand it. An operating system that uploads on its own is a different kind of thing from one with a bug reporter.
• One issue, never more. Reports are comments on a collector issue found by its exact title. The script will not open a second one.
• Deduplicated by signature - the program, the vector, and the faulting instruction, deliberately not the pid or the stack contents. A crash that recurs for a fortnight edits its own comment, bumping a count and a last-seen date, instead of adding fourteen. It also skips the crashes the boot provokes on purpose (svc-crash faults every single run), and refuses to open more than three new reports in one invocation.

Nothing is posted without --post. Without it the script prints exactly what it would send, which is also how to check what a dump contains before it becomes public: a crash record carries register values and a slice of the process stack.

python scripts/dev/report-crash.py qemu-cli-serial.log

Wired into the nightly workflow only, and only on failure, with issues: write declared explicitly on the job - the default token permissions depend on a repository setting, and a reporter that silently cannot post looks exactly like one with nothing to report.

A seed with no entropy is not a random test

The stress service seeded itself from clock_gettime, and the seeds it produced here were 220000010, 230000012, 180000010, 160000010 - the same value give or take a coarse tick. Every boot therefore explored very nearly the same sequence, which is the one thing a randomised test must not do. Fifty local boots stayed green while CI failed five times out of five on sequences this machine had never tried.

It reads rdtsc now, which changes every cycle and is available from ring 3; the clock and the pid are still mixed in to separate two boots that start on the same cycle count. Seeds are eleven digits and different every run.

Still not reproduced locally. The configurations are identical - same Release flags, same TLS setting, and it fails under both gcc and clang in CI - so the difference is the machine. Rather than keep guessing from here, the gate now prints every STRESS_FAIL and STRESS_SEED line when the stress run fails, and the crash collector files stress failures as well as faults. The environment that can see the defect is the one that gets to describe it.

The boot sequence is inside out, and it was hiding every userland failure

Asked plainly - "don't you have a boot sequence, kernel first and then the services?" - the honest answer turned out to be no. The real order, read off a healthy log rather than off the code: