The device manager supervises: hello, backoff, and the crash-loop cap (M18.1)

The manager is now a harness service on the well-known .device_manager endpoint. Every driver spawns supervised; drivers with an assignment must hello (device-manager-protocol, versioned) within a deadline enforced by a timer sweep. Exit reasons drive the restart decision: clean exits stay down, faults restart with 300/600/1200ms backoff, and three fast deaths mark a driver failed instead of respawning forever. usb-xhci-bus is the first conforming driver; the crash-test fixture claims a device, hellos, and faults on purpose — each respawn re-proving claim release on death through the manager's own path. maximum_tasks grows 16 -> 32: the initial-ramdisk sweep (15 binaries at once) was intermittently overflowing the static pool.
Mark the feat/process-lifecycle merge done in the M17-M18 plan
2026-07-13 00:19:30 +01:00 · 2026-07-12 23:53:50 +01:00 · 2026-07-12 23:53:50 +01:00 · 2026-07-12 23:53:38 +01:00 · 2026-07-12 23:41:44 +01:00 · 2026-07-12 23:34:09 +01:00
28 changed files with 2104 additions and 115 deletions
@@ -2,12 +2,31 @@
 Codename: Shodan
 Version: 1
-A small operating system, written from scratch in Zig — a bootloader (`boot/`)
+A small resilient operating system, written from scratch in Zig.
-and a microkernel (`system/kernel/`), sharing a neutral handoff contract (`system/boot-handoff.zig`).
+
-It boots x86-64 via UEFI, and so far has a framebuffer console, a physical frame
+## Zen of DanOS:
-allocator, its own paging with W^X permissions, interrupt/exception handling, a
+
-LAPIC timer, a kernel heap, a fixed-priority preemptive scheduler, and in-kernel IPC
+- Resilient Micro-Kernel Architecture.
-channels. See [`docs/`](docs/README.md) for how each piece works.
+    - Every process run in an isolated user space not kernel space.
    - Processes cannot take down the entire OS with it when they die or is killed
 - Stable public runtime library, private OS ABI.
    - Keeps a stable runtime for user space processes between OS versions (great for backwards compatibility)
    - Allows the underlying OS to be changed without effecting applications
    - Provides a boundary to enable compatibility between OS's e.g. POSIX, MUSL etc
 - Drivers are just isolated processes in user space.
    - Thin binaries that can be restarted like applications.
    - Useful during driver development.
    - Drivers can claim MMIO / ports
    - Driver resources (e.g. IRQ/Port/MMIO) claims are automatically cleaned up if the driver dies or is killed
    - Drivers can also hook into the process lifecyle to clean up or reset hardware
 - No legacy to deal with
    - Zig code uses a clean coding style (Zen of Zig)
    - Favor reading code over writing code.
    - No magic numbers.
    - No shortend names unless its for ABI compatibility or acronyms
 - Inter-Process Communication (IPC)
  - Publish and subscribe to Asynchronous Messages
  - Talk to services and processes synchronously
 ## Prerequisites
@@ -60,7 +79,7 @@ straight into CI.
 ## Documentation
-Design notes explaining the *why* behind the code live in
+Design notes explaining *why* behind the code live in
 [`docs/`](docs/README.md) — start with [`docs/README.md`](docs/README.md).
 ## Logo
@@ -212,6 +212,13 @@ pub fn build(b: *std.Build) void {
        },
    });
    // The device-manager protocol: hello + (M18.2) tree reports, exposed as its
    // own module like the other protocol modules. Imported through the runtime.
    const device_manager_protocol_module = b.addModule("device-manager-protocol", .{
        .root_source_file = b.path("system/services/device-manager/device-manager-protocol.zig"),
    });
    runtime_module.addImport("device-manager-protocol", device_manager_protocol_module);
    // Typed volatile MMIO register access + memory-ordering barriers, for drivers on
    // top of an mmio_map grant. Depends only on `builtin` (arch-conditional barriers);
    // no target set, so it inherits each driver's. See library/mmio/mmio.zig.
@@ -332,6 +339,9 @@ pub fn build(b: *std.Build) void {
    const ps2_keyboard_exe = addUserBinary(b, kernel_target, runtime_module, posix_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "ps2-keyboard", "system/drivers/ps2-bus/keyboard.zig");
    const ps2_mouse_exe = addUserBinary(b, kernel_target, runtime_module, posix_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "ps2-mouse", "system/drivers/ps2-bus/mouse.zig");
    const usb_xhci_bus_exe = addUserBinary(b, kernel_target, runtime_module, posix_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "usb-xhci-bus", "system/drivers/usb-xhci-bus/usb-xhci-bus.zig");
    // A test fixture, not a real driver: hellos to the device manager, then faults —
    // what the driver-restart scenario drives the crash-loop cap with.
    const crash_test_exe = addUserBinary(b, kernel_target, runtime_module, posix_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "crash-test", "system/services/crash-test/crash-test.zig");
    const device_manager_exe = addUserBinary(b, kernel_target, runtime_module, posix_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "device-manager", "system/services/device-manager/device-manager.zig");
    // The input service and its exercisers: the fan-out server, a hardware-free synthetic
    // source, and a subscriber that doubles as the `input` test's oracle. See docs/input.md.
@@ -363,6 +373,8 @@ pub fn build(b: *std.Build) void {
    mk_run.addFileArg(ps2_mouse_exe.getEmittedBin());
    mk_run.addArg("usb-xhci-bus");
    mk_run.addFileArg(usb_xhci_bus_exe.getEmittedBin());
    mk_run.addArg("crash-test");
    mk_run.addFileArg(crash_test_exe.getEmittedBin());
    mk_run.addArg("device-manager");
    mk_run.addFileArg(device_manager_exe.getEmittedBin());
    mk_run.addArg("input");
@@ -0,0 +1,149 @@
 # The device manager
 **Status: the protocol and supervision are built** (M18.1, 2026-07-13): `hello`
 with its deadline, supervised spawn, restart with backoff, and the crash-loop
 cap are in — usb-xhci-bus is the first conforming driver, and the
 `driver-restart` scenario proves fault → backoff → re-claim → cap end to end.
 Tree reports (M18.2) and the application surface (M18.3) remain design. The
 primitives underneath are real ([process-management.md](process-management.md):
 spawn/supervise/kill/exit-notification; [driver-model.md](driver-model.md): the device
 table as a capability system; [drivers.md](drivers.md): claim/map/IRQ), and the first
 per-device driver spawn works (the device manager matches the xHCI controller by PCI
 class and spawns `usb-xhci-bus` with the device id as argv[1]). This document designs
 the rest: the device manager as **the tree, the matcher, and the supervisor** — the
 policy process that turns [resilience.md](resilience.md)'s restart goal into practice
 for drivers.
 How processes stop, reload, and report their deaths is deliberately **not** in this
 document: that is the universal lifecycle every danos process speaks —
 [process-lifecycle.md](process-lifecycle.md), signals over IPC and the stable
 `runtime.process` interface. The device manager is that design's first serious
 customer, not its owner. Its own protocol contains nothing lifecycle-shaped; a
 driver is stopped, health-checked, and buried exactly like any other process.
 ## The tree: structure in the manager, authority in the kernel
 The device tree is two things fused: *information* (what exists, how it nests) and
 *authority* (a descriptor is a licence to map physical memory). They separate:
 - The **kernel keeps the capability system** — device, I/O-port, and interrupt
  claims, resource containment on `device_register`, the
  `mmio_map`/`irq_bind`/`msi_bind` gates — and **cleans all of it up when a process
  dies** (settled; it is increment 1 of
  [process-lifecycle.md](process-lifecycle.md)). The three invariants in
  [driver-model.md](driver-model.md) stay exactly where they are. A device manager
  that could mint MMIO mappings by its own say-so would be a second kernel, and a
  buggy one would un-earn everything the microkernel bought.
 - The **device manager owns the tree as data** — identity, topology, naming, driver
  matching, hotplug events, and being the one process everything else asks about
  devices. Firmware discovery seeds it (today via the kernel's snapshot); **bus
  drivers grow it** by reporting what they see; applications query and watch it.
  `device_enumerate` fades to a manager-internal (then deleted) seam.
 Long-term, discovery itself leaves the kernel — but not *into* the manager. PCI
 enumeration is a **pci-bus driver**: the manager spawns it against the host bridge
 (already a device with the ECAM window as a resource), it scans, it reports functions
 like any bus reports children. ACPI becomes an **acpi service** that interprets the
 tables and reports the namespace. The manager only orchestrates and merges. Moving
 AML interpretation out of ring 0 is its own project on its own track; nothing here
 depends on when it lands.
 ## The protocol
 A `device-manager-protocol` module (the vfs-protocol pattern): extern-struct
 messages, a version in the handshake, reserved fields everywhere. The manager is a
 well-known endpoint (`ipc.register(.device_manager)`); the badge tells it who is
 talking; the same endpoint receives its children's exit notifications — one loop,
 one world.
 | Direction | Message | Purpose |
 |---|---|---|
 | driver → manager | `hello { version, role, device_id }` | confirms the argv assignment, starts the deadline clock |
 | bus → manager | `child_added { parent, identity, resources }` | one node the bus discovered |
 | bus → manager | `child_removed { id }` | unplug, or the bus lost it |
 | app → manager | `enumerate` | snapshot of the tree (read-only) |
 | app → manager | `subscribe` | receive published add/remove events |
 `hello` is the one deadline the manager enforces itself: spawned and silent past the
 deadline means wrong binary, wrong protocol version, or wedged before main — apply
 the stop sequence and the restart policy. Everything else lifecycle-shaped
 (terminate, the common `ping` liveness call, exit reasons) arrives through
 [process-lifecycle.md](process-lifecycle.md)'s vocabulary, not this protocol.
 Assignment stays argv (`usb-xhci-bus <device id>`) for now — simple, and it works.
 The step after `hello` exists is delegation: the manager claims (or is granted) the
 devices and passes the claim to the driver over IPC (the M13 capability-transfer
 mechanism), replacing first-come-first-served `device_claim` with policy. Identity in
 `child_added` is per-bus: PCI children carry the class triple (`pci_class`, as the
 xHCI match already uses); USB children carry the (class, subclass, protocol) triple
 from usb-ids.zig — each bus's native language, decoded by the shared ids modules.
 ## Supervision and restart
 Every driver is spawned with the manager's exit endpoint (`spawnSupervised` — built).
 On a death notification:
 1. **Read the reason** ([process-lifecycle.md](process-lifecycle.md) increment 2).
   Clean exit → it meant to; don't restart. Fault or missed `hello` deadline →
   restart with **backoff**, and a crash-loop cap (three fast deaths → mark failed,
   stop respawning, log loudly; a later `reload` to the manager can retry).
 2. **Prune the subtree** the dead bus driver reported. Its children describe
   protocol state (xHCI slot ids, transfer rings) that died with the process;
   keeping the nodes would be keeping a lie. Watchers receive `child_removed` — the
   input service losing, then regaining, a keyboard is the *honest* description of
   what happened. The restarted instance rediscovers and re-reports.
 3. **The claim is already free** because the kernel released it at death — the
   restarted instance claims the same controller and comes up.
 Who supervises the supervisor: **init** (PID 1), which already supervises the
 services it starts. If the manager dies, drivers keep running (they hold their
 claims; the kernel doesn't care who their supervisor was — though their exit
 notifications now dangle harmlessly). The restarted manager re-learns the world:
 kernel snapshot, then a re-`hello` round — drivers answer a broadcast or are stopped
 and respawned. Full state handoff is deliberately not attempted.
 ## Thin drivers, class protocols
 The [driver-model.md](driver-model.md) three-shape split, restated as processes:
 - A **bus driver** (usb-xhci-bus) owns its controller — claim, MMIO, IRQ/MSI, DMA
  rings — and offers a *transfer* protocol ("submit a control transfer to device N",
  built from the usb-abi request constructors) plus tree reports to the manager.
 - A **class driver** (usb-hid, usb-storage) owns nothing: it is matched to a reported
  child by its identity triple, speaks the bus's transfer protocol downward and its
  service's protocol upward — HID reports to the input service, blocks to the block
  service. It works unchanged over any controller.
 - **Services** (input, display, block) aggregate class drivers and face applications.
 Each arrow is a protocol module. The manager routes none of the data plane — it
 introduces the parties (matching), supervises them (lifecycle), and gets out of the
 way.
 ## Increments
 Increments 1–4 are the lifecycle prerequisites and live in
 [process-lifecycle.md](process-lifecycle.md) (claim cleanup on death, exit reasons,
 published exit events, signals + `runtime.process`). On top of those:
 5. **device-manager-protocol**: `hello`, supervised spawn with restart policy;
   usb-xhci-bus becomes the first conforming driver.
 6. **Tree reports**: `child_added`/`child_removed`; the manager mirrors; xHCI reports
   the mouse and keyboard QEMU already hangs off it.
 7. **App surface**: `enumerate`/`subscribe` over IPC; `device_enumerate` retreats
   to a manager-internal seam.
 8. **Discovery migration**: pci-bus driver first, acpi service second, kernel scan
   retired last. (AML-in-user-space is its own track.)
 ## Settled questions (2026-07-12)
 - **Stateful buses**: pruning the subtree on bus-driver death is right for USB. A
  future storage bus with in-flight writes wants drain-before-terminate — which is
  exactly the `deadline_ms` parameter `stop()` already has; a per-driver deadline
  is one value in the manager's policy table when such a bus arrives. No design
  change.
 - **Manager death**: drivers survive the manager; the restarted manager re-learns
  the world (above). Checkpointing driver state with the manager is deferred until
  something demonstrates the need.
 - **Matching stays code until the third bus.** `driverFor`/`pciDriverFor` are
  honest at two bus types; the third triggers the manifest (a driver declares what
  it binds: a PCI class triple, a USB class triple, an ACPI `_HID`).
@@ -103,3 +103,22 @@ This is what makes a user-space driver possible at all, and it's the subject of
  the oldest (discrete messages, not a coalescing level like the notification ring).
 - **A bounded reply.** `MSG_MAX` is 256 bytes and the copy runs under the big kernel
  lock; a bulk transfer wants shared pages, not a copy.
 ## Lifecycle conventions over IPC (M17)
 Three conventions from [process-lifecycle.md](process-lifecycle.md) ride the
 notification mechanism:
 - **Signals** arrive as notifications on the endpoint a process nominated with
  `signal_bind` (`runtime.process.bindSignals`): badge = the signal bit plus the
  coalesced pending mask (`runtime.process.signalsFrom` decodes). Statements,
  never questions; no payload, no reply.
 - **One-shot timers** (`timer_bind`, `runtime.system.timerOnce`) land as a
  timer-bit notification — the timed wait: a service arms a deadline and keeps
  serving, instead of blocking in sleep.
 - **The universal ping**: a **zero-length request is the liveness probe**,
  answered with a zero-length reply by the service harness itself
  (`runtime.service.run`). No protocol's requests start at length zero, so the
  encoding cannot collide, and a wedged service simply fails to answer — which
  is the diagnosis. Deep health ("can I reach my hardware?") stays a per-service
  protocol message.
@@ -0,0 +1,197 @@
 # M17–M18 execution plan: process lifecycle + device manager
 The operational plan for building [process-lifecycle.md](process-lifecycle.md)
 (M17) and [device-manager.md](device-manager.md) increments 5–7 (M18). Design is
 settled in those documents; this file is the build order — one phase at a time,
 each phase green before the next starts. Delete or archive this file when M18
 lands.
 **Definition of green, every phase:** `zig build` clean, `zig build test` clean,
 `python3 test/qemu_test.py` passes (existing scenarios plus the phase's new one),
 and the relevant design doc's "known gaps" / status lines updated. Commit per
 green phase (no co-author trailers).
 **Workflow (settled 2026-07-12):** work happens in a dedicated git worktree, on
 feature branches cut from `main` — `feat/process-lifecycle` (M17.1–17.4),
 `feat/device-manager` (M18.1), `feat/usb-xhci-bus` (M18.2–18.3). When a branch's
 phases are all green it is **auto-merged into `main`**; branches are kept after
 merge, not deleted. Merges and branches are pushed to origin. Phase 0 (once):
 commit the design docs, merge the outstanding `feat/usb` work into `main`, and
 run the existing QEMU suite green before any new work starts.
 **Numbering note:** continues the milestone sequence (driver track ended at M16).
 ## Status
 The loop marks a phase `[x]` in the same commit that lands it. A phase is marked
 only when its definition of green holds.
 - [x] **Phase 0** — baseline: docs committed, feat/usb merged to main, pushed;
      `usb-xhci-libary.zig` renamed to `usb-xhci-library.zig`; existing QEMU
      suite green from the worktree (48/48, 2026-07-12).
 - [x] **M17.1** — kernel releases claims/MSI on death (claims: `releaseAllOwnedBy`
      in the reap; MSI was already swept by `irq.releaseOwner`; `claim-release`
      test; suite 49/49)
 - [x] **M17.2** — exit reasons (`ExitReason` recorded at exit/fault/kill before
      the notification; `process_exit_reason` supervisor-gated;
      `runtime.process.exitReason`; kernel + ring-3 assertions; suite 49/49)
 - [x] **M17.3** — published exit events + VFS subscriber (`process_subscribe`,
      bounded ref-counted table, publish on every death;
      `runtime.process.subscribeExits`; VFS handles carry owners and are swept on
      the owner's death; `vfs-client-death` test; suite 50/50)
 - [x] **M17.4** — signals, timer notifications, `runtime.process`, the service
      harness (signal_bind/process_signal + coalescing pending mask; timer_bind
      on the tick; bindSignals/signalsFrom/sendSignal/stop + timerOnce;
      runtime.service.run with the zero-length ping; VFS converted; `signals`
      scenario; suite 51/51)
 - [x] **merge** `feat/process-lifecycle` → main, push (merged 2026-07-13)
 - [x] **M18.1** — device-manager protocol: hello + restart policy
      (device-manager-protocol module; the manager as a harness service:
      supervised spawns, hello deadline via timer sweep, restart with
      300/600/1200ms backoff, exit reasons deciding restart-vs-stopped,
      crash-loop cap; usb-xhci-bus first conforming driver; crash-test fixture
      re-proving claim release each respawn; `driver-restart` scenario;
      maximum_tasks 16→32 — the sweep was overflowing the pool; suite 52/52)
 - [ ] **merge** `feat/device-manager` → main, push
 - [ ] **M18.2** — xHCI port scan + tree reports (branch `feat/usb-xhci-bus`)
 - [ ] **M18.3** — app surface: enumerate/subscribe + device-list
 - [ ] **merge** `feat/usb-xhci-bus` → main, push — **loop ends here**
 ---
 ## M17.1 — the kernel releases a dead process's claims
 The cleanup half of iron rule 1; the prerequisite for every restart story.
 - `system/kernel/devices-broker.zig`: `releaseAllOwnedBy(owner: u32)` — clear
  every `claimed[]` slot holding this task id.
 - `system/kernel/process.zig`: call it from the reap path, alongside the existing
  IRQ-binding release (the ordering comment there says why IRQs go first — claims
  slot in after them, before the exit notification).
 - MSI vectors: find where `msi_bind` records per-device vectors (interrupts
  module) and release those by owner in the same pass.
 - Docs: remove the claims bullet from process-management.md "Known gaps".
 **Test:** new QEMU scenario `claim-release` — a test child claims an unclaimed
 device, is killed, is respawned, and claims the same device again successfully;
 assert both claims in the serial log. Kernel-side unit coverage in
 `system/kernel/tests.zig` for `releaseAllOwnedBy` (claim two devices as two owners,
 release one owner, verify exactly its claims freed).
 ## M17.2 — exit reasons
 - `system/abi.zig`: `ExitReason` (exited, aborted, segmentation_fault,
  illegal_instruction, arithmetic_fault, killed).
 - Kernel: record the reason at every death site — clean exit path, each fault
  class in `onException`, the kill path. Bounded recent-exits table (ids are never
  reused, so a small ring keyed by id is enough).
 - New system call `process_exit_reason(id)` — supervisor-gated, like kill; returns
  the recorded reason or `-ESRCH` once evicted.
 - `library/runtime/process.zig`: `ExitReason` + `exitReason(id: u32)`.
 - Docs: remove the no-exit-status bullet from process-management.md.
 **Test:** extend the `supervision` scenario — three children: one exits cleanly,
 one faults (the fault-recovery pattern), one is killed; the supervisor asserts all
 three reasons.
 ## M17.3 — published exit events
 - Kernel: bounded subscriber table (endpoints); new system call
  `process_subscribe(endpoint)` (ungated, like `process_enumerate`); every death
  posts `notify_exit_bit | id` to each subscriber — the same post the supervisor
  path already uses.
 - `library/runtime/process.zig`: `subscribeExits(endpoint)`.
 - VFS becomes the first subscriber: on an exit event, release every handle keyed
  by that task id (badges already are task ids). Log the release.
 - Docs: note the convention in ipc.md (exit events reuse the exit-notification
  badge encoding).
 **Test:** new QEMU scenario `vfs-client-death` — a client opens a file and is
 killed without closing; assert the VFS logs the handle release and its open-handle
 count returns to baseline.
 ## M17.4 — signals and the service harness
 - Kernel: per-task pending mask + bound endpoint; system calls
  `signal_bind(endpoint)` and `process_signal(id, signal)` (supervisor-or-self
  gated); delivery posts `notify_signal_bit | pending mask`, coalescing; pending
  signals with no bound endpoint pend silently.
 - `library/runtime/process.zig`: `Signal`, `SignalSet`, `bindSignals`,
  `signalsFrom`, `sendSignal`, `stop(id, deadline_ms)` (terminate → wait for exit
  notification → kill). Implement `terminate`, `reload`, `user_1`, `user_2`;
  `interrupt`/`quit` are enum members with no sender yet; `alarm` stays unbuilt.
 - Kernel: **one-shot timer notifications** — `timer_bind(endpoint, ms)` posts a
  notification badge when the deadline lands (IRQ-as-IPC again, on the timer
  wheel `sleep` already uses). This is the missing timed-wait primitive:
  `replyWait` blocks forever and `sleep` blocks the whole process, but `stop()`'s
  escalation, the device manager's `hello` deadline (M18.1), and restart backoff
  all need a deadline while staying responsive. It is also the mechanism `alarm`
  gets for free later.
 - New `library/runtime/service.zig`: the harness — `run(callbacks)` owning the
  replyWait loop, folding protocol messages, signals, and child-exit notifications
  into `init` / `on_message` / `on_reload` / `on_terminate`; answers the common
  `ping` automatically. Define the reserved `ping` request encoding here and
  document it in ipc.md (one obvious encoding; smallest that cannot collide with
  existing protocols).
 - Convert one existing service (input-source or hpet) to the harness as proof it
  subtracts code rather than adding it.
 **Test:** extend `supervision` — a harness-built child: `sendSignal(reload)`
 observed in its log, `ping` answered, `stop()` produces a clean exit with reason
 `exited`; a second child that ignores signals (no bind) is killed by `stop()`'s
 deadline with reason `killed`.
 ## M18.1 — device-manager protocol: hello + restart policy
 - New `system/services/device-manager/device-manager-protocol.zig` module
  (vfs-protocol pattern): `hello { version, role, device_id }`; version constant;
  reserved fields.
 - Device manager: register the `.device_manager` endpoint; spawn drivers with its
  exit endpoint; enforce the hello deadline; restart policy — backoff, crash-loop
  cap (three fast deaths → mark failed, log, stop), reasons from M17.2 deciding
  restart vs not.
 - usb-xhci-bus: adopt the harness + send hello. hpet/ps2-bus follow only if the
  conversion is mechanical; otherwise they keep working unconverted (the manager
  only enforces hello on drivers spawned with an assignment).
 - build.zig: test-loop entry for the protocol module if it grows pure logic.
 **Test:** new QEMU scenario `driver-restart` — the xHCI driver takes a test-only
 argv flag to fault after hello on its first run; assert: fault, exit reason
 recorded, manager respawns with backoff, second run claims the controller
 (M17.1) and hellos clean. Assert the crash-loop cap by a driver that always
 faults (a tiny test driver, not xhci).
 ## M18.2 — bus tree reports
 - Protocol: `child_added { parent, identity, resources }` / `child_removed { id }`.
 - usb-xhci-bus: bring-up to **port scan only** — map the MMIO window (claimed in
  M16-era work), controller reset/start per xHCI spec, walk the port registers,
  report one `child_added` per connected port with speed + port number as
  identity. **No transfer rings, no descriptors** — reading device/interface
  descriptors (and therefore USB class triples for matching) is the follow-on USB
  track, not this plan.
 - Device manager: mirror reports into its tree; prune the subtree (emitting
  `child_removed`) when a bus driver dies; assert re-report on restart.
 **Test:** QEMU already attaches usb-kbd + usb-mouse on xhci.0 — assert two
 `child_added` events reach the manager and appear in its tree dump; kill the
 driver, assert two `child_removed` then two fresh `child_added` after respawn.
 ## M18.3 — the application surface
 - Protocol: `enumerate` (tree snapshot) + `subscribe` (published add/remove
  events, input-service pattern).
 - A small client (`device-list`, the `ps` analog) exercising both; the manager
  becomes the one answer to "what devices exist" for user space.
  `device_enumerate` stays for drivers/kernel seeding — its retreat is tied to the
  discovery migration, out of this plan.
 **Test:** QEMU scenario — `device-list` shows the tree including USB children;
 during a driver restart the subscribing client logs remove + add events.
 ---
 **Explicitly out of scope** (own tracks, after M18): discovery migration (pci-bus
 driver, acpi service, retiring the kernel scan), USB control transfers +
 descriptors + class-driver matching, the musl layer, `interrupt`/`quit` senders
 (needs a console), job control.
@@ -0,0 +1,327 @@
 # Process lifecycle: signals over IPC
 **Status: increments 1–4 built** (2026-07-12): claim release on death, exit
 reasons, published exit events, and signals + one-shot timers + the service
 harness are all in — the interface below is as-built. The primitives underneath
 predate this design ([process-management.md](process-management.md):
 spawn, the supervision link, kill, child-exit notifications); this document designs
 the layer above them — the standard vocabulary a danos process speaks about its own
 life, and the stable `runtime.process` interface that carries it. Nothing here is
 device- or driver-specific: a driver, the VFS, and a user application all stop,
 reload, and die the same way. The device manager is simply this design's first
 serious customer ([device-manager.md](device-manager.md)).
 **"POSIX" in this document means the concepts, never the letter of the standard.**
 danos borrows the ideas and the hard-won lessons (what SIGTERM *means*, why SIGPIPE
 was a mistake) without inheriting the mechanism, the API, or the names. The naming
 rule is danos's own and it is strict: plain words that communicate intent
 (`terminate`, `reload`, `exited`) and the IPC vocabulary the system already speaks
 (`bind`, `subscribe`, `publish`, `endpoint`) — never `SIG*`, never a second word for
 a concept that already has one. Literal POSIX arrives later and lives elsewhere: a
 **musl-based C layer** (growing out of library/posix) that wires C programs to the
 danos runtime — musl's syscall surface retargeted at danos system calls and IPC
 protocols (files onto the VFS protocol, `sigaction`/`wait` onto this lifecycle,
 sockets onto whatever networking becomes). Ported programs see POSIX; the system
 underneath never does.
 ## Why a standard vocabulary
 A supervisor can only manage processes it has never heard of if "please exit" means
 the same thing to all of them. That is the one thing POSIX signals got deeply right:
 `SIGTERM` means the same thing to nginx and to a five-line script, which is why
 process supervision on Unix (init systems, container runtimes) is possible at all.
 danos wants that property from day one, because supervision-and-restart is the
 system's core motivation ([resilience.md](resilience.md)).
 What POSIX got wrong — for a system like this — is the **delivery mechanism**:
 asynchronous control-flow hijack. A Unix handler runs on a stolen stack at an
 arbitrary instruction boundary, which is why the async-signal-safe function list
 exists, why `errno` must be saved, and why the canonical signal bug is a SIGTERM
 handler innocently calling `printf` mid-`malloc`. That entire bug class comes from
 the mechanism, not the vocabulary, and none of it is worth importing.
 A microkernel already has the right channel: **a signal is a message.** QNX delivers
 POSIX signals over its message passing; seL4 has notification objects; Erlang turned
 "death is a message to whoever linked" into a reliability philosophy. danos has
 already done it once without naming it: a child's death arrives as a notification
 badge on the supervisor's endpoint — the microkernel's SIGCHLD, the IRQ-as-IPC
 pattern reused. Signals are the same pattern reused a third time.
 ## The mechanism
 - **`signal_bind(endpoint)`** — a process nominates the endpoint its signals arrive
  on, exactly as `irq_bind` nominates where a device's interrupts land. The runtime
  does this at startup for any program that opts in.
 - **`process_signal(id, signal)`** — posts the signal as an asynchronous
  notification to the target's bound endpoint: badge = `notify_badge_bit |
  notify_signal_bit | pending signals`. Non-blocking for the sender, always.
 - **Pending signals coalesce** in a per-process bitmask until the target next waits
  — exactly like interrupt notifications, and exactly POSIX's own semantics for
  non-realtime signals (two pending SIGTERMs are one SIGTERM). The bitmask *is* the
  design: signals carry no payload. Anything with a payload is a protocol message.
 - **Authority**: the supervisor may signal its children — the same link that is
  already the kill authority. A process may signal itself. Anything broader waits
  for transferable process handles.
 - **No binding, no problem**: a process that never calls `signal_bind` is not
  broken — its signals pend unread and only `process_kill` works on it. Simple
  programs stay simple; the vocabulary is opt-in, the kill authority is not.
 Because delivery is a message into the process's own event loop, there is no
 async-signal-safe list in danos: a handler is ordinary code running at a point the
 process chose. The bug class is gone by construction, not by discipline.
 ## The vocabulary: POSIX.1-1990, sorted honestly
 The full 1990 set, and what each becomes. Two intrinsically problematic cases get a
 defense below the table.
 | POSIX.1-1990 | danos disposition | Notes |
 |---|---|---|
 | SIGTERM | signal `terminate` | finish up and exit; the supervisor's polite half |
 | SIGHUP | signal `reload` | re-read configuration / re-scan |
 | SIGINT | signal `interrupt` | interactive interrupt; meaningful once a console can send it, in the vocabulary now so numbering is stable |
 | SIGQUIT | signal `quit` | as SIGINT, without the core-dump baggage |
 | SIGALRM | signal `alarm` | timer expiry as a message; the Unix SIGALRM+`longjmp` timeout hacks are impossible here. In the vocabulary, unbuilt: no consumer yet, and when one appears it is runtime sugar over the existing timer — zero kernel work |
 | SIGUSR1, SIGUSR2 | signals `user_1`, `user_2` | service-defined |
 | SIGCHLD | **already exists** — the exit notification | the badge carries the child id, dodging the classic coalescing bug (Unix code must loop `waitpid`) |
 | SIGKILL | `process_kill` — kernel mechanism | its definition is "cannot be handled"; it was never really a signal |
 | SIGABRT | exit reason `abort` | `abort()` is synchronous self-termination, not an event |
 | SIGSEGV, SIGILL, SIGFPE | exit reasons, **never delivered** | see below |
 | SIGPIPE | **an error return**, not a signal | see below |
 | SIGSTOP, SIGTSTP, SIGTTIN, SIGTTOU, SIGCONT | deferred | job control needs terminals, sessions, and process groups; stop/continue is scheduler territory |
 **The fault signals (SIGSEGV, SIGILL, SIGFPE) are intrinsically wrong for messages.**
 They are *synchronous* — raised at a specific faulting instruction, not "sometime
 soon". A message cannot be delivered to a process whose next instruction re-faults;
 it never reaches its event loop to read it. POSIX only makes fault handlers "work"
 via the async hijack (run the handler *instead of* the instruction), and even there,
 returning from a SIGSEGV handler without curing the cause is undefined behavior.
 danos's architecture already has the better answer: fault → the kernel kills the
 process ([resilience.md](resilience.md) step 2, built) → the supervisor reads the
 reason → restart. Recovery is restart, not a handler. This is also truer to the 1990
 standard than handling is: the standard's default action for all three was
 "terminate the process".
 **SIGPIPE deserves special contempt.** Its default kills a process that writes to a
 closed pipe — which is why "the whole server died because one client disconnected"
 is roughly every network daemon's first production bug, and why every mature codebase
 contains the same fix: ignore SIGPIPE, handle the `EPIPE` error return. danos made
 the right choice natively already — a reply owed to a dead peer fails with `-EPEER`.
 Errors from operations are error returns from those operations. The posix layer can
 synthesize SIGPIPE for ported code that expects it.
 ### Statements, not questions
 A signal and a protocol message both travel over IPC — the difference is the
 **contract**, not the transport. danos IPC has two primitives, both already in
 daily use: the **asynchronous notification** (a badge — bits that coalesce into a
 pending mask; the sender never blocks; no payload, *no reply path*; how IRQs and
 exit events arrive) and the **synchronous call** (a rendezvous — payload both
 ways, the caller waits for the reply; how VFS requests work). A signal is the
 first kind: a *statement*. `terminate` wants no reply — the exit notification is
 its acknowledgement.
 A health probe is the second kind: a *question*, worthless without its answer —
 and the answer's absence within a deadline is the very thing being measured.
 Asked as a signal it has no reply channel (a coalescing bit can't carry an answer,
 and the authority rule forbids a child signalling its supervisor back); asked as a
 call, the timeout-is-the-diagnosis semantics come free. So there is no `health`
 signal. Liveness is the common **`ping`**: a reserved request every harness-run
 service answers automatically on its main endpoint — still free for the service
 author, still one obvious way — and a supervisor's probe is a `ping` call with a
 deadline.
 ## The two iron rules
 1. **Cleanup is the kernel's job.** A process can die with no warning — fault,
   kill, power. Correctness must never depend on a `terminate` handler running. On
   any death the kernel releases the address space, IPC handles, IRQ bindings, and
   owed replies (built), and must also release **device, I/O-port, and interrupt
   claims and MSI vectors** (the known gap in
   [process-management.md](process-management.md); increment 1). A signal handler is
   for *graceful* work — flushing, deregistering, saving — never for *necessary*
   work.
 2. **Kill is not a signal, and exit reasons are load-bearing.** The standard stop
   sequence is *terminate → deadline → `process_kill`*; the unhandleable kill stays
   a kernel mechanism. And a supervisor deciding whether to restart must know *how*
   the child died: clean exit (meant to — don't restart), fault (restart with
   backoff), killed (the supervisor did it). The exit notification today carries
   only the id; it grows a reason. Restart policy cannot be written without it.
 ## Who learns of a death
 A death has three audiences, and conflating them is how systems end up with either
 zombie state or privileged snooping:
 1. **The supervisor** — gets the exit notification on the endpoint it gave at spawn
   (built), which grows the `ExitReason` (increment 2). The supervisor is the only
   audience that needs the *reason*, because it is the only one deciding whether to
   restart.
 2. **The peer owed a reply** — already built: a client that dies mid-request fails
   the server's reply with `-EPEER`; a server that dies fails its waiting clients
   the same way. This covers the *synchronous* case only.
 3. **The subscribers** — the new piece, and it is the input service's
   publish/subscribe shape ([input.md](input.md)) applied to exits. A stateful
   service accumulates per-client state across many requests: the VFS holds a dead
   client's open file handles, the input service holds its subscriptions, a future
   network stack holds its sockets. None of these are the client's supervisor, and
   none learn anything from a failed reply if the client simply never calls again.
   So the kernel **publishes every exit** to whoever subscribed:
   `process_subscribe(endpoint)` adds a subscriber, and each death posts a
   notification to every subscriber (badge = `notify_exit_bit | process id` — the
   same encoding supervisors already decode, the IRQ-as-IPC pattern once more). The
   subscriber filters for ids it holds state for and releases what the dead client
   held. Correlating is free of bookkeeping: an IPC sender's badge already *is* its
   task id (`runtime.ipc.Received`), so the id a service has been keying client
   state by all along is the id the exit event carries.
   Subscription, not broadcast-to-everyone: only processes that asked receive
   events, the kernel keeps a bounded subscriber table, and delivery is the same
   non-blocking coalescing notification as everything else — a dying process never
   waits on its mourners. Subscribing is ungated, like `process_enumerate`: what is
   running (and dying) is not a secret between cooperating processes. Subscribers
   do not receive the exit reason — the VFS does not care *why* the client died.
 This is the service-side mirror of iron rule 1: **a service must never depend on
 its clients cleaning up after themselves.** Handle release on client death is the
 service's job, triggered by the published exit event — never by a courtesy
 "closing now" message that a crashed client will never send.
 ## The stable interface: `runtime.process`
 `runtime.process` already owns what a process receives at birth (`Init`, the
 argv contract). It grows to own the other end of life.
 **The runtime is the stable interface; the numbers are not.** danos applications do
 not make system calls — they call the runtime library, and the system-call numbers,
 notification bits, and signal bit positions beneath it are a **private kernel ↔
 runtime contract** that may change at any time (settled 2026-07-12). This is why
 the runtime exists. Today kernel and runtime ship from one tree in one image, so
 "stability" is simply building them together. When driver binaries start shipping
 as separately-versioned applications — the whole point of the restart design — the
 binary's embedded runtime version becomes compatibility metadata (the same idea as
 the protocol version in the device manager's `hello`), and the kernel refuses what
 it cannot serve. Signals therefore need no reserved numbering scheme: the enum
 below is vocabulary, not ABI.
 ```zig
 /// The signal vocabulary. The value is the bit position in the pending mask — a
 /// private kernel/runtime detail, free to change while they ship together.
 pub const Signal = enum(u5) {
    terminate = 0, // SIGTERM: finish up and exit
    reload = 1, // SIGHUP: re-read configuration
    interrupt = 2, // SIGINT
    quit = 3, // SIGQUIT
    alarm = 4, // SIGALRM
    user_1 = 5, // SIGUSR1
    user_2 = 6, // SIGUSR2
 };
 /// A decoded pending mask: the coalesced set of signals a notification delivered.
 pub const SignalSet = struct {
    pending: u32,
    pub fn has(set: SignalSet, signal: Signal) bool { ... }
    pub fn iterate(set: SignalSet) Iterator { ... }
 };
 /// Nominate `endpoint` as this process's signal endpoint (signal_bind). The
 /// runtime's service harness calls this; a bare program may call it directly and
 /// fold signals into its own replyWait loop.
 pub fn bindSignals(endpoint: usize) bool { ... }
 /// Decode a received badge into signals, or null if the badge is not a signal
 /// notification (mirrors ipc.Received.isChildExit).
 pub fn signalsFrom(badge: usize) ?SignalSet { ... }
 /// Send `signal` to process `id`. Supervisor-gated, like kill; non-blocking.
 pub fn sendSignal(id: u32, signal: Signal) bool { ... }
 /// The standard stop sequence: terminate, wait up to `deadline_ms` for the exit
 /// notification, then process_kill. The one call a supervisor needs.
 pub fn stop(id: u32, deadline_ms: u64) void { ... }
 /// Subscribe `endpoint` to published exit events (process_subscribe). Every
 /// process death posts an asynchronous notification: badge = notify_exit_bit |
 /// process id — the same encoding a supervisor's exit notification uses, decoded
 /// by the same ipc.Received helpers. For stateful services: release what the dead
 /// client held (file handles, subscriptions, sockets). Ungated, like
 /// process_enumerate.
 pub fn subscribeExits(endpoint: usize) bool { ... }
 /// How a process ended — queried after the exit notification (the kernel records
 /// it first, so the two never race). What restart policy reads. (Built in M17.2.)
 pub const ExitReason = enum(u8) {
    exited, // returned from main / clean exit
    aborted, // abort() — deliberate self-termination (SIGABRT's ghost; reserved)
    segmentation_fault, // SIGSEGV's ghost
    illegal_instruction, // SIGILL's ghost
    arithmetic_fault, // SIGFPE's ghost
    protection_fault, // general protection fault
    fault, // any other CPU exception
    killed, // process_kill
 };
 ```
 Two deliberate absences. There is no `mask`/`block` API — a process that is not
 ready for a signal simply has not waited on its endpoint yet; the pending mask *is*
 the blocked set. And there is no per-signal handler registration at this layer —
 dispatch is the process's own `switch` over `SignalSet`, or the service harness's
 callbacks (`on_terminate`, `on_reload`) for programs that want defaults.
 ### The service harness
 `runtime.service` owns the `replyWait` loop and folds every event source — signals,
 child exits, protocol messages — into callbacks, with the vocabulary's defaults:
 `terminate` returns from the loop (clean exit), the common `ping` is answered automatically,
 `reload` is ignored unless overridden. One loop, no locking, nothing reentrant. A
 service author writes domain logic; the lifecycle contract is satisfied by the
 harness. A process that bypasses the harness and ignores its signals meets the
 deadline-then-kill escalation — you cannot force a process to implement an
 interface, but you can make compliance free and non-compliance fatal.
 ### The musl layer later
 The POSIX C layer is a **musl port**: musl's arch/syscall layer retargeted so that
 what musl believes are kernel syscalls become danos runtime calls and IPC — `open`
 and `read` onto the VFS protocol, `kill`/`sigaction`/`waitpid` onto this document's
 vocabulary, `exit` onto the runtime's exit path. `sigaction` handlers registered
 through it are invoked by the runtime's loop when the signal message arrives —
 synchronous underneath, async-looking to ported code, delivered at wait boundaries
 the way most Unix programs already experience signals (at syscalls). No stack hijack
 ever happens, `SA_RESTART` semantics come free because nothing was interrupted, and
 SIGPIPE can be synthesized from `-EPEER` for the programs that expect it. C programs
 get POSIX; danos-native programs never pay for it.
 ## Increments
 1. **Kernel: release device/port/IRQ claims and MSI vectors on death** — the
   cleanup half of iron rule 1, and the prerequisite for any restart story. Test:
   kill a claiming driver, spawn it again, the claim succeeds.
 2. **Exit reason in the death notification** (`ExitReason` above).
 3. **Exit events**: `process_subscribe` in the kernel (bounded subscriber table,
   publishes on every death), `runtime.process.subscribeExits`; the VFS becomes the
   first subscriber — releasing a dead client's handles is its proof test.
 4. **Signals**: `signal_bind` + `process_signal` + the pending mask in the kernel;
   `runtime.process` grows the interface above; the service harness handles
   `terminate` and answers the common `ping`; `stop()` for supervisors.
 [device-manager.md](device-manager.md) builds directly on all four.
 ## Settled questions (2026-07-12)
 - **Signal numbering is not ABI**: the runtime is the stable interface; the numbers
  beneath it are a private kernel ↔ runtime contract (see "The stable interface").
 - **Liveness is a `ping` call, not a signal**: signals are statements, questions
  are synchronous calls (see "Statements, not questions"). A service wanting *deep*
  health ("can I reach my hardware?") defines its own protocol message on top.
 - **Process handles: deferred.** Pids + the supervisor gate cover everything
  planned; transferable handles (Fuchsia-style, delegating signalling without
  delegating kill) wait for the capability table to grow types beyond endpoints.
 - **`alarm`: in the vocabulary, unbuilt.** No consumer yet; when one appears it is
  runtime sugar over the existing timer (arm a timer that posts your own signal) —
  zero kernel work, so deferring costs nothing.
 - **Subscription granularity: all exits**, subscriber-side filtering — one
  subscription per service, a bounded kernel table. Per-id subscriptions only if
  event volume ever matters (hundreds of processes, not before).
 - **Client identity across the exit boundary: no convention needed** — an IPC
  sender's badge already is its task id (see "Who learns of a death").
@@ -95,11 +95,18 @@ the architecture layer calls up into `tick`.
 ## Known gaps (bring-up honesty)
- Device **claims** are not released on death (pre-existing: the fault path has
+- ~~Device claims are not released on death~~ Closed (M17.1): every path out of a
-  the same gap) — a killed driver's device stays claimed until reboot.
+  process releases its device claims alongside its IRQ and MSI bindings
  (`releaseTaskResourcesLocked`), so a restarted driver can claim its hardware
  again — the cleanup half of [process-lifecycle.md](process-lifecycle.md)'s iron
  rule 1. The `claim-release` test proves the kill → release → re-claim cycle.
 - Kernel stacks of dead tasks are leaked, as on every exit path (no reaper yet).
- There is no exit *status* in the notification, only the id; a supervisor that
+- ~~There is no exit status in the notification~~ Closed (M17.2): the kernel
-  needs the code can grow a wait-style call later.
+  records how every process ends — exited, a fault class, or killed — before it
  posts the exit notification, and the supervisor reads it with
  `process_exit_reason` (`runtime.process.exitReason`). This is the input to
  restart policy ([process-lifecycle.md](process-lifecycle.md)); an exit *code*
  for the clean case can still ride alongside later.
 - Enumerate writes through the caller's raw pointer under the bring-up trust
  model, like `device_enumerate` (an unmapped page is a self-DoS, not an
  isolation break).
@@ -109,4 +116,5 @@ the architecture layer calls up into `tick`.
 `process-list` (enumerate), `process-kill` (kernel-level kill paths, refusals,
 notifications), `supervision` (the whole user-side surface via the process-test
 service: spawn supervised → enumerate → kill blocked and spinning children →
-notifications → gone). See test/qemu_test.py.
+notifications → gone), `claim-release` (a killed claim-holder's device is
 claimable again). See test/qemu_test.py.
@@ -94,6 +94,15 @@ pub fn send(h: Handle, message: []const u8) bool {
 /// GSI. See `isNotification`.
 pub const notify_badge_bit: u64 = abi.notify_badge_bit;
 /// Set alongside `notify_badge_bit` when the notification is a **signal** — the
 /// lifecycle vocabulary of docs/process-lifecycle.md, delivered to the endpoint
 /// nominated with `process.bindSignals`. Decode with `process.signalsFrom`.
 pub const notify_signal_bit: u64 = abi.notify_signal_bit;
 /// Set alongside `notify_badge_bit` when the notification is a **one-shot timer**
 /// landing (`system.timerOnce`).
 pub const notify_timer_bit: u64 = abi.notify_timer_bit;
 /// Set alongside `notify_badge_bit` when the notification is a **child-exit
 /// notice** — a process this one spawned (with an exit endpoint) has ended —
 /// rather than a device interrupt. The low bits carry the child's process id.
@@ -133,6 +142,17 @@ pub const Received = struct {
    }
    /// The task id of whoever posted a buffered message, meaningful only when
    /// Whether this arrival is a signal notification — decode the set with
    /// `process.signalsFrom(badge)`.
    pub fn isSignal(self: Received) bool {
        return self.isNotification() and self.badge & notify_signal_bit != 0;
    }
    /// Whether this arrival is a one-shot timer landing (`system.timerOnce`).
    pub fn isTimer(self: Received) bool {
        return self.isNotification() and self.badge & notify_timer_bit != 0;
    }
    /// `isMessage`. (The badge's low bits, with the three high marker bits masked off.)
    pub fn senderTaskId(self: Received) u32 {
        return @intCast(self.badge & ~(notify_badge_bit | notify_exit_bit | notify_message_bit));
@@ -1,8 +1,15 @@
-//! Process-level runtime types: what a user program receives at entry. Mirrors
+//! Process-level runtime types: what a user program receives at entry (`Init`,
 //! the argv contract) and the process end of the lifecycle
 //! (docs/process-lifecycle.md) — today the exit reason a supervisor reads to
 //! decide restart; signals and the stop sequence land here with M17.4. Mirrors
 //! the spirit of `std.process.Init.Minimal` in danos terms — std's `Args` holds
 //! no data on freestanding targets, so the type is danos's own.
 const std = @import("std");
 const abi = @import("abi");
 const sc = @import("system-call.zig");
 const ipc = @import("ipc.zig");
 const system = @import("system.zig");
 /// Everything a program receives at entry. Passed to
 /// `pub fn main(init: runtime.process.Init)`; programs that need nothing keep
@@ -45,3 +52,86 @@ pub const Arguments = struct {
        }
    };
 };
 /// How a process ended — what a supervisor's restart policy reads: a clean exit
 /// meant to stop, a fault wants a restart with backoff, killed means the
 /// supervisor did it itself (docs/process-lifecycle.md).
 pub const ExitReason = abi.ExitReason;
 /// How dead child `id` ended. Ask after the exit notification arrives — the
 /// kernel records the reason before it posts the notification, so this never
 /// races it. Returns null for an id that never lived, is still alive, was
 /// evicted from the kernel's bounded record, or is not this process's child
 /// (the same authority gate as `kill`).
 pub fn exitReason(id: u32) ?ExitReason {
    const r = sc.systemCall1(.process_exit_reason, id);
    if (r > ~@as(usize, 0) - 4095) return null; // a wrapped -errno
    return @enumFromInt(r);
 }
 /// The signal vocabulary (docs/process-lifecycle.md): POSIX's concepts, danos's
 /// names, message delivery. A signal is a one-way coalescing statement — never a
 /// question (liveness is the zero-length ping call) and never kill (that is
 /// `system.kill`, unhandleable by definition).
 pub const Signal = abi.Signal;
 /// The coalesced set of signals one notification delivered: two pending
 /// terminates arrive as one. Decode a received badge with `signalsFrom`.
 pub const SignalSet = struct {
    pending: u32,
    pub fn has(set: SignalSet, signal: Signal) bool {
        return set.pending & (@as(u32, 1) << @intFromEnum(signal)) != 0;
    }
 };
 /// Nominate `endpoint` as this process's signal endpoint. Signals posted while
 /// unbound have pended; they are delivered immediately on bind, coalesced.
 pub fn bindSignals(endpoint: usize) bool {
    return sc.systemCall1(.signal_bind, endpoint) == 0;
 }
 /// Decode a received badge into the signals it delivered, or null if it is not
 /// a signal notification.
 pub fn signalsFrom(badge: u64) ?SignalSet {
    if (badge & abi.notify_badge_bit == 0 or badge & abi.notify_signal_bit == 0) return null;
    return .{ .pending = @truncate(badge & ~(abi.notify_badge_bit | abi.notify_signal_bit)) };
 }
 /// Post `signal` to child `id` (or to yourself). Supervisor-gated, like kill;
 /// non-blocking, always — a statement, not a conversation.
 pub fn sendSignal(id: u32, signal: Signal) bool {
    return sc.systemCall2(.process_signal, id, @intFromEnum(signal)) == 0;
 }
 /// The standard stop sequence (docs/process-lifecycle.md): terminate, wait up to
 /// `deadline_ms` for the exit notification on `exit_endpoint` (the endpoint the
 /// child was spawned with), then kill. Any *other* notifications arriving on
 /// that endpoint while stopping are consumed and dropped — a supervisor with
 /// concurrent traffic implements the same sequence inside its own event loop
 /// (arm `system.timerOnce`, keep serving) instead of calling this.
 pub fn stop(id: u32, deadline_ms: u64, exit_endpoint: usize) void {
    _ = sendSignal(id, .terminate);
    _ = system.timerOnce(exit_endpoint, deadline_ms);
    var receive: [8]u8 = undefined;
    while (true) {
        const got = ipc.replyWait(exit_endpoint, &.{}, &receive, null);
        if (got.isChildExit() and got.childProcessId() == id) return;
        if (got.isTimer()) break; // the deadline passed first — escalate
    }
    _ = system.kill(id);
    while (true) {
        const got = ipc.replyWait(exit_endpoint, &.{}, &receive, null);
        if (got.isChildExit() and got.childProcessId() == id) return;
    }
 }
 /// Subscribe `endpoint` to published exit events: every process death posts an
 /// asynchronous notification with the same badge encoding as a supervisor's exit
 /// notice (decode with `ipc.Received.isChildExit`/`childProcessId`). For stateful
 /// services: release what the dead client held — file handles, subscriptions —
 /// because a service must never depend on clients cleaning up after themselves
 /// (docs/process-lifecycle.md). Ungated, like `system.processes`.
 pub fn subscribeExits(endpoint: usize) bool {
    return sc.systemCall1(.process_subscribe, endpoint) == 0;
 }
@@ -17,6 +17,9 @@ pub const ipc = @import("ipc.zig");
 pub const start = @import("start.zig");
 /// The VFS wire protocol (shared with the VFS server).
 pub const vfs_protocol = @import("vfs-protocol");
 /// The device-manager protocol: hello + tree reports (docs/device-manager.md).
 pub const device_manager_protocol = @import("device-manager-protocol");
 /// Keyboard-event listening (subscribe/next) and broadcasting (publish), over the input
 /// service. See library/runtime/input.zig and system/services/input/.
 pub const input = @import("input.zig");
@@ -35,5 +38,9 @@ pub const panic = start.panic;
 /// Process entry types: the `Init` handed to `main`, and its `Arguments`.
 pub const process = @import("process.zig");
 /// The service harness: one replyWait loop folding requests, signals, and
 /// notifications into callbacks (docs/process-lifecycle.md).
 pub const service = @import("service.zig");
 /// The heap as a `std.mem.Allocator`, for Zig `std` containers in user code.
 pub const allocator = heap.allocator;
@@ -0,0 +1,81 @@
 //! The service harness (docs/process-lifecycle.md): one replyWait loop that
 //! folds protocol requests, signals, and subscribed notifications into
 //! callbacks — so the lifecycle contract ("answers ping, exits on terminate")
 //! is satisfied by construction and a service author writes domain logic only.
 //! Nothing is asynchronous inside the process: a callback runs at a point the
 //! loop chose, never on a hijacked stack — the whole reason signals are
 //! messages.
 //!
 //! The liveness probe: a **zero-length request is the universal ping**, answered
 //! with a zero-length reply by the harness itself. No protocol's requests start
 //! at length zero, so the encoding cannot collide, and there is nothing for a
 //! service author to implement — a wedged service simply fails to answer, which
 //! is the diagnosis (see docs/ipc.md).
 const abi = @import("abi");
 const ipc = @import("ipc.zig");
 const process = @import("process.zig");
 pub const Callbacks = struct {
    /// Called once with the service's endpoint before the loop starts — the
    /// place to subscribe to exit events, bind IRQs, or announce readiness.
    /// Return false to abort startup (the process exits).
    init: ?*const fn (endpoint: ipc.Handle) bool = null,
    /// One protocol request from `sender` (a task id): write the reply into
    /// `reply`, return its length. The zero-length ping never reaches this.
    on_message: *const fn (message: []const u8, reply: []u8, sender: u32) usize,
    /// A notification that is not a signal — a subscribed exit event, a bound
    /// IRQ, a timer landing. The raw badge; decode with the ipc helpers.
    on_notification: ?*const fn (badge: u64) void = null,
    /// The reload signal. Default: ignored.
    on_reload: ?*const fn () void = null,
    /// The terminate signal, called before the loop returns. The clean exit is
    /// the return itself — never put *necessary* work here (iron rule 1: a kill
    /// arrives with no warning; this is for graceful extras only).
    on_terminate: ?*const fn () void = null,
    /// Publish the endpoint under a well-known service id at startup.
    service: ?abi.ServiceId = null,
 };
 /// Run the service: create and (optionally) register the endpoint, bind signals
 /// to it, call `init`, then serve until `terminate` arrives — at which point the
 /// loop returns and main's return is the clean exit the supervisor reads as
 /// `ExitReason.exited`. `maximum_message` sizes the receive and reply buffers
 /// (a service passes its protocol's message maximum).
 pub fn run(comptime maximum_message: usize, callbacks: Callbacks) void {
    const endpoint = ipc.createIpcEndpoint() orelse return;
    if (callbacks.service) |id| {
        if (!ipc.register(id, endpoint)) return;
    }
    _ = process.bindSignals(endpoint);
    if (callbacks.init) |initialise| {
        if (!initialise(endpoint)) return;
    }
    var reply_buffer: [maximum_message]u8 = undefined;
    var reply_len: usize = 0;
    var receive: [maximum_message]u8 = undefined;
    while (true) {
        const got = ipc.replyWait(endpoint, reply_buffer[0..reply_len], &receive, null);
        if (got.isNotification()) {
            reply_len = 0; // nothing owed for a notification
            if (process.signalsFrom(got.badge)) |signals| {
                if (signals.has(.reload)) {
                    if (callbacks.on_reload) |onReload| onReload();
                }
                if (signals.has(.terminate)) {
                    if (callbacks.on_terminate) |onTerminate| onTerminate();
                    return; // the loop's return IS the clean exit
                }
                continue;
            }
            if (callbacks.on_notification) |onNotification| onNotification(got.badge);
            continue;
        }
        if (got.len == 0) {
            reply_len = 0; // the universal ping: a zero-length reply, from the harness
            continue;
        }
        reply_len = callbacks.on_message(receive[0..got.len], &reply_buffer, got.senderTaskId());
    }
 }
@@ -32,6 +32,15 @@ pub fn sleep(ms: usize) void {
    _ = sc.systemCall1(.sleep, ms);
 }
 /// Arm a one-shot timer: after `ms` milliseconds the kernel posts a timer
 /// notification (`ipc.Received.isTimer`) to `endpoint`. The timed wait of
 /// docs/process-lifecycle.md — a service arms a deadline and keeps serving,
 /// instead of blocking in sleep; what stop-sequence escalation, hello deadlines,
 /// and restart backoff are built from.
 pub fn timerOnce(endpoint: usize, ms: u64) bool {
    return sc.systemCall2(.timer_bind, endpoint, ms) == 0;
 }
 /// Monotonic nanoseconds since boot — a time source for timeouts and short delays. It
 /// only ever moves forward. This is *not* wall-clock time (no date, no timezone — that
 /// is a user-space service layered on top). Deadline pattern for a bounded poll loop:
@@ -53,9 +53,31 @@ pub const SystemCall = enum(u64) {
    process_enumerate = 24, // process_enumerate(buffer, maximum) -> total: snapshot the task table
    process_kill = 25, // process_kill(id) -> 0/-errno: end a process this process spawned
    ipc_send = 26, // ipc_send(handle, message_ptr, message_len) -> 0/-errno: post a payload to an endpoint's async queue without blocking
    process_exit_reason = 27, // process_exit_reason(id) -> ExitReason/-errno: how a dead child ended (its supervisor only)
    process_subscribe = 28, // process_subscribe(endpoint) -> 0/-errno: subscribe to published exit events — every death posts a notification
    signal_bind = 29, // signal_bind(endpoint) -> 0/-errno: nominate the endpoint this process's signals arrive on
    process_signal = 30, // process_signal(id, signal) -> 0/-errno: post a signal to a child (or to yourself)
    timer_bind = 31, // timer_bind(endpoint, ms) -> 0/-errno: one-shot timer — posts a notification when ms elapse
    _,
 };
 /// How a process ended — recorded by the kernel at death, queried by the
 /// supervisor with `process_exit_reason`, and the input to its restart decision
 /// (docs/process-lifecycle.md): a clean exit meant to stop, a fault wants a
 /// restart with backoff, killed means the supervisor did it itself. The faults
 /// mirror the CPU exceptions a ring-3 process can die of; they are exit reasons,
 /// never delivered to the faulting process (recovery is restart, not a handler).
 pub const ExitReason = enum(u8) {
    exited = 0, // returned from main / called exit
    aborted = 1, // deliberate self-termination (reserved: no abort path yet)
    segmentation_fault = 2, // page fault
    illegal_instruction = 3, // invalid opcode
    arithmetic_fault = 4, // divide error, x87 or SIMD fault
    protection_fault = 5, // general protection fault
    fault = 6, // any other CPU exception
    killed = 7, // process_kill
 };
 /// The x86 MSI message address base (`0xFEE0_0000`): a device raises an MSI by writing
 /// `data` to this address, which the Local APIC turns into an interrupt at the vector
 /// in `data`. The kernel returns the concrete (address, data) from `msi_bind`; this is
@@ -93,6 +115,35 @@ pub const notify_exit_bit: u64 = 1 << 62;
 /// broadcasts where a rendezvous is the wrong shape (the input service is the first user).
 pub const notify_message_bit: u64 = 1 << 61;
 /// Set (alongside `notify_badge_bit`) in the badge of a **signal notification** —
 /// the process-lifecycle vocabulary of docs/process-lifecycle.md, delivered to the
 /// endpoint the process nominated with `signal_bind`. The low bits carry the
 /// coalesced pending mask (bit positions = `Signal` values): signals are
 /// statements, not questions, and two pending terminates are one terminate.
 pub const notify_signal_bit: u64 = 1 << 60;
 /// Set (alongside `notify_badge_bit`) in the badge of a **timer notification** —
 /// a one-shot `timer_bind` deadline landing. No payload bits: what to do when the
 /// deadline fires is whatever the receiver armed it for (a stop-sequence
 /// escalation, a restart backoff, an alarm).
 pub const notify_timer_bit: u64 = 1 << 59;
 /// The signal vocabulary (docs/process-lifecycle.md): POSIX's concepts, danos's
 /// names, message delivery. The value is the bit position in the pending mask — a
 /// private kernel/runtime detail, free to change while they ship together. Kill
 /// is not here (it is `process_kill`, unhandleable by definition); faults are not
 /// here (they are `ExitReason`s — recovery is restart, not a handler); liveness is
 /// not here (a question, asked as the zero-length ping call, not a statement).
 pub const Signal = enum(u5) {
    terminate = 0, // finish up and exit (the polite half of the stop sequence)
    reload = 1, // re-read configuration / re-scan
    interrupt = 2, // interactive interrupt (no sender until a console exists)
    quit = 3, // as interrupt, by convention more final
    alarm = 4, // a timer the process armed for itself (unbuilt: no consumer yet)
    user_1 = 5, // service-defined
    user_2 = 6, // service-defined
 };
 /// Capacity of `ProcessDescriptor.name` — matches the longest name `system_spawn`
 /// accepts, so a process's recorded name (its argv[0]) is never truncated.
 pub const maximum_process_name = 64;
@@ -125,6 +176,7 @@ pub const ServiceId = enum(u32) {
    vfs = 1,
    input = 2,
    ps2_bus = 3, // the 8042 owner; child device drivers attach here for raw bytes
    device_manager = 4, // the tree, the matcher, the supervisor (docs/device-manager.md)
    _,
 };
@@ -1,58 +1,59 @@
 //! /system/drivers/usb-xhci-bus — the xHCI (USB 3) host-controller bus driver.
-//! The device manager spawns **one instance per controller** it discovers (a machine
+//! The device manager spawns **one instance per controller** it discovers (a
-//! can carry several), passing the controller's device-tree id as argv[1]; this
+//! machine can carry several), passing the controller's device-tree id as
-//! instance claims that device and no other, so multiple instances never fight over
+//! argv[1]; this instance claims that device and no other, so multiple
-//! hardware. This increment proves the plumbing: parse the id, claim the controller,
+//! instances never fight over hardware.
-//! and report its MMIO window. The next increments map the registers and bring the
+//!
-//! controller up (reset, rings, port scan), then enumerate the USB devices on the
+//! M18.1 (this increment): a harness service and the first conforming driver of
-//! bus with the usb-abi request builders and publish each with `device_register`.
+//! the device-manager protocol — claim the controller, `hello` the manager
 //! (role, version, assignment) inside its deadline, then serve. Controller
 //! bring-up (map the MMIO window, reset, port scan) and tree reports
 //! (`child_added` for each connected port) land in M18.2.
 const std = @import("std");
 const runtime = @import("runtime");
 const protocol = runtime.device_manager_protocol;
 const device = runtime.device;
-/// Format one whole log line and emit it in a single `debug_write`, so concurrent
+/// Format one whole log line and emit it in a single `debug_write`, so
-/// instances (one per controller) can never interleave mid-line.
+/// concurrent instances (one per controller) can never interleave mid-line.
 fn writeLine(comptime fmt: []const u8, arguments: anytype) void {
    var line: [128]u8 = undefined;
    _ = runtime.system.write(std.fmt.bufPrint(&line, fmt, arguments) catch return);
 }
-pub fn main(init: runtime.process.Init) void {
+var controller_id: u64 = protocol.no_device;
    const argument = init.arguments.get(1) orelse {
        _ = runtime.system.write("usb-xhci-bus: missing controller device id (argv[1])\n");
        return;
    };
    const controller_id = std.fmt.parseInt(u64, argument, 10) catch {
        writeLine("usb-xhci-bus: malformed controller device id '{s}'\n", .{argument});
        return;
    };
 /// Claim the assigned controller, find its register window, and hello the
 /// manager. Any failure returns false: the process exits cleanly, which the
 /// manager reads as "meant to stop" — a missing assignment is not a crash loop.
 fn initialise(endpoint: runtime.ipc.Handle) bool {
    _ = endpoint;
    if (!device.claim(controller_id)) {
        writeLine("usb-xhci-bus: unable to claim controller device {d}\n", .{controller_id});
-        return;
+        return false;
    }
    // Fetch our own descriptor back for the controller's resources.
    const buffer = runtime.allocator().alloc(device.DeviceDescriptor, 64) catch {
        _ = runtime.system.write("usb-xhci-bus: out of memory\n");
-        return;
+        return false;
    };
    const total = device.enumerate(buffer);
    const descriptor = for (buffer[0..@min(total, buffer.len)]) |d| {
        if (d.id == controller_id) break d;
    } else {
        writeLine("usb-xhci-bus: device {d} not in the device tree\n", .{controller_id});
-        return;
+        return false;
    };
-    // The controller's operational registers live behind BAR0, enumerated as the
+    // The controller's operational registers live behind BAR0, enumerated as
-    // device's first memory resource.
+    // the device's first memory resource.
    const register_window = for (descriptor.resources[0..@intCast(descriptor.resource_count)]) |resource| {
        if (resource.kind == @intFromEnum(device.ResourceKind.memory)) break resource;
    } else {
        writeLine("usb-xhci-bus: controller device {d} has no MMIO window\n", .{controller_id});
-        return;
+        return false;
    };
    writeLine("usb-xhci-bus: claimed controller device {d} (registers at 0x{x}, {d} bytes)\n", .{
        controller_id,
@@ -60,9 +61,53 @@ pub fn main(init: runtime.process.Init) void {
        register_window.len,
    });
-    // Controller bring-up (map the window, reset, rings, port scan) is the next
+    // The handshake: role, protocol version, assignment — inside the manager's
-    // increment; stay resident as the bus's supervisor in the meantime.
+    // deadline (the lookup retries cover the manager still registering).
-    while (true) runtime.system.sleep(1000);
+    var manager: ?runtime.ipc.Handle = null;
    var tries: u32 = 0;
    while (manager == null and tries < 100) : (tries += 1) {
        manager = runtime.ipc.lookup(.device_manager);
        if (manager == null) runtime.system.sleep(20);
    }
    const h = manager orelse {
        _ = runtime.system.write("usb-xhci-bus: no device manager to hello\n");
        return false;
    };
    const hello = protocol.Hello{ .role = @intFromEnum(protocol.Role.bus), .device_id = controller_id };
    var reply: [protocol.message_maximum]u8 = undefined;
    const n = runtime.ipc.call(h, std.mem.asBytes(&hello), &reply) catch {
        _ = runtime.system.write("usb-xhci-bus: hello call failed\n");
        return false;
    };
    if (n < protocol.reply_size or std.mem.bytesToValue(protocol.HelloReply, reply[0..protocol.reply_size]).status != 0) {
        _ = runtime.system.write("usb-xhci-bus: hello refused\n");
        return false;
    }
    _ = runtime.system.write("usb-xhci-bus: hello acknowledged\n");
    return true;
 }
 /// No bus protocol to serve yet — transfer requests arrive with the USB track.
 fn onMessage(message: []const u8, reply: []u8, sender: u32) usize {
    _ = message;
    _ = reply;
    _ = sender;
    return 0;
 }
 pub fn main(init: runtime.process.Init) void {
    const argument = init.arguments.get(1) orelse {
        _ = runtime.system.write("usb-xhci-bus: missing controller device id (argv[1])\n");
        return;
    };
    controller_id = std.fmt.parseInt(u64, argument, 10) catch {
        writeLine("usb-xhci-bus: malformed controller device id '{s}'\n", .{argument});
        return;
    };
    runtime.service.run(protocol.message_maximum, .{
        .init = initialise,
        .on_message = onMessage,
    });
 }
 pub const panic = runtime.panic;
@@ -104,6 +104,19 @@ pub fn ownerOf(id: u64) ?u32 {
    return claimed[@intCast(id)];
 }
 /// Release every claim held by `owner` — called by the process layer on every
 /// path out of a process (exit, fault, kill), so a restarted driver can claim its
 /// hardware again (docs/process-lifecycle.md iron rule 1: cleanup is the kernel's
 /// job). The devices stay in the table — they describe hardware, which did not go
 /// away — only their ownership clears.
 pub fn releaseAllOwnedBy(owner: u32) void {
    for (claimed[0..count]) |*slot| {
        if (slot.*) |o| {
            if (o == owner) slot.* = null;
        }
    }
 }
 /// Resource `index` of device `id`, or null if out of range.
 pub fn resourceOf(id: u64, index: u64) ?device_abi.ResourceDescriptor {
    if (id >= count) return null;
@@ -412,13 +412,26 @@ fn recoverableFault(vector: u64) bool {
 /// plus a POST code and a persistent breadcrumb. (A ring-3 fault on a *borrowed*
 /// kernel thread — process.run, the user-pf isolation probe — also lands here: there
 /// is no scheduled process to kill.)
 /// Classify a CPU exception vector as the ExitReason a supervisor reads — the
 /// fault classes of docs/process-lifecycle.md. Faults are exit reasons, never
 /// signals delivered to the faulting process: recovery is restart, not a handler.
 fn exitReasonForVector(vector: u64) abi.ExitReason {
    return switch (vector) {
        14 => .segmentation_fault, // page fault
        6 => .illegal_instruction, // invalid opcode
        0, 16, 19 => .arithmetic_fault, // divide error, x87, SIMD
        13 => .protection_fault, // general protection
        else => .fault,
    };
 }
 fn onException(state: *const architecture.CpuState) noreturn {
    if (architecture.fromUser(state) and scheduler.currentIsUserProcess() and recoverableFault(state.vector)) {
        statusPrint("\ndanos: process {d} ({s}) killed by {s} (vector {d}) on core {d}\n", .{ scheduler.currentId(), scheduler.current().name(), architecture.exceptionName(state.vector), state.vector, scheduler.currentCpuIndex() });
        statusPrint("  error code : 0x{x}\n", .{state.error_code});
        statusPrint("  IP         : 0x{x:0>16}\n", .{architecture.instructionPointer(state)});
        if (architecture.faultAddress(state)) |address| statusPrint("  fault addr : 0x{x:0>16}\n", .{address});
-        process.killCurrentProcess(); // reclaims everything, reschedules; never returns
+        process.killCurrentProcess(exitReasonForVector(state.vector)); // reclaims everything, reschedules; never returns
    }
    log.checkpoint(cp_exception);
@@ -137,6 +137,7 @@ pub fn init() void {
    architecture.setSystemCallHandler(system_call);
    scheduler.terminate_current_hook = terminateCurrentLocked;
    scheduler.reap_task_hook = reapTaskLocked;
    scheduler.timer_tick_hook = timerSweepLocked;
 }
 /// Return -1 (as an unsigned bit pattern) in the system_call result register.
@@ -164,6 +165,7 @@ fn system_call(state: *architecture.CpuState) void {
            // A scheduled process tears down fully (terminateCurrent); a borrowed
            // test thread unwinds back to the kernel that entered it.
            if (scheduler.currentIsUserProcess()) {
                scheduler.current().exit_reason = .exited;
                terminateCurrent();
            } else architecture.userExit();
        },
@@ -199,6 +201,11 @@ fn system_call(state: *architecture.CpuState) void {
        .clock => systemClock(state),
        .process_enumerate => systemProcessEnumerate(state),
        .process_kill => systemProcessKill(state),
        .process_exit_reason => systemProcessExitReason(state),
        .process_subscribe => systemProcessSubscribe(state),
        .signal_bind => systemSignalBind(state),
        .process_signal => systemProcessSignal(state),
        .timer_bind => systemTimerBind(state),
        _ => fail(state),
    }
 }
@@ -552,7 +559,11 @@ pub var fault_kill_count: u64 = 0;
 ///   endpoint reference destroys the Endpoint, and a still-bound GSI would have an
 ///   ISR call notifyFromIsr on freed memory the next time the device fired.
 ///   `releaseOwner` also leaves the line masked, so a dead driver's device goes
-///   quiet rather than storming.
+///   quiet rather than storming. (It drops MSI vectors by the same owner sweep.)
 /// - Device claims are released with the IRQ bindings, so a restarted driver can
 ///   claim the same hardware again — the cleanup half of process-lifecycle.md's
 ///   iron rule 1. Claims hold no pointers, so ordering is free; they go here so
 ///   the exit notification (below, last) observes a fully-released child.
 /// - A client this task still owes a reply to (it died between receive and reply)
 ///   is failed with -EPEER rather than left blocked forever — a dead server must
 ///   not hang its callers.
@@ -565,7 +576,33 @@ pub var fault_kill_count: u64 = 0;
 ///   reference taken at spawn is dropped with it.
 /// Precondition: the big kernel lock is held.
 fn releaseTaskResourcesLocked(t: *scheduler.Task) void {
    recordExitLocked(t);
    irq.releaseOwner(t.id);
    devices_broker.releaseAllOwnedBy(t.id);
    // The dying task's signal endpoint and one-shot timers go with it.
    if (t.signal_endpoint) |raw| {
        ipc.dropRef(@ptrCast(@alignCast(raw)));
        t.signal_endpoint = null;
    }
    t.pending_signals = 0;
    for (&one_shot_timers) |*slot| {
        if (slot.*) |timer| {
            if (timer.owner == t.id) {
                ipc.dropRef(timer.endpoint);
                slot.* = null;
            }
        }
    }
    // A dead subscriber's own subscriptions go first: it must not hear about
    // itself, and the slots' endpoint references drop with it.
    for (&exit_subscribers) |*slot| {
        if (slot.*) |subscriber| {
            if (subscriber.owner == t.id) {
                ipc.dropRef(subscriber.endpoint);
                slot.* = null;
            }
        }
    }
    if (t.ipc_client) |client| {
        t.ipc_client = null;
        client.ipc_status = -ipc.EPEER;
@@ -575,6 +612,12 @@ fn releaseTaskResourcesLocked(t: *scheduler.Task) void {
    scheduler.removeFromWaitQueueLocked(t);
    scheduler.forgetIpcClientLocked(t);
    ipc.closeHandles(t);
    // Publish the exit to every subscriber (docs/process-lifecycle.md): the same
    // badge encoding as the supervisor's notification, and equally late, so a
    // subscriber also observes a fully-released child.
    for (&exit_subscribers) |*slot| {
        if (slot.*) |subscriber| ipc.notifyLocked(subscriber.endpoint, abi.notify_exit_bit | t.id);
    }
    if (t.exit_endpoint) |raw| {
        const endpoint: *ipc.Endpoint = @ptrCast(@alignCast(raw));
        t.exit_endpoint = null;
@@ -628,6 +671,7 @@ pub fn killProcess(caller_id: u32, target_id: u32) i64 {
    const target = scheduler.taskByIdLocked(target_id) orelse return -ipc.ESRCH;
    if (target.aspace == 0) return -ipc.ESRCH; // kernel tasks are not processes
    if (target.supervisor != caller_id) return -ipc.EPERM;
    target.exit_reason = .killed;
    if (target.state == .running) {
        target.kill_pending = true;
    } else {
@@ -640,12 +684,170 @@ pub fn killProcess(caller_id: u32, target_id: u32) i64 {
 /// The fault is confined to the process — the kernel trapped it on the task's own
 /// kernel stack and is intact — so everything the process held is reclaimed and the
 /// core reschedules. The system keeps running; only the faulting process dies
-/// (docs/resilience.md: fault -> kill -> continue).
+/// (docs/resilience.md: fault -> kill -> continue). `reason` is the fault class
-pub fn killCurrentProcess() noreturn {
+/// (from the vector), recorded for the supervisor's `process_exit_reason`.
 pub fn killCurrentProcess(reason: abi.ExitReason) noreturn {
    scheduler.current().exit_reason = reason;
    fault_kill_count += 1;
    terminateCurrent();
 }
 /// The bounded record of recent deaths, for `process_exit_reason`: ids are never
 /// reused, so a ring keyed by id is enough — a record evicted by wraparound reads
 /// as -ESRCH, the same as an id that never lived, which a supervisor treats as
 /// "too late to ask". Written under the big kernel lock by the reap.
 const exit_record_capacity = 64;
 const ExitRecord = struct { id: u32 = 0, supervisor: u32 = 0, reason: abi.ExitReason = .exited, valid: bool = false };
 var exit_records: [exit_record_capacity]ExitRecord = .{ExitRecord{}} ** exit_record_capacity;
 var exit_record_next: usize = 0;
 /// Record a dying task's (id, supervisor, reason) — called by the reap before the
 /// exit notification is posted, so a supervisor that hears the notification can
 /// always still query the reason. Precondition: the big kernel lock is held.
 fn recordExitLocked(t: *scheduler.Task) void {
    exit_records[exit_record_next] = .{ .id = t.id, .supervisor = t.supervisor, .reason = t.exit_reason, .valid = true };
    exit_record_next = (exit_record_next + 1) % exit_record_capacity;
 }
 /// How dead process `id` ended, for `caller` — the kernel half of the
 /// process_exit_reason system call. Returns the ExitReason value, -ESRCH (never
 /// lived, still alive, or evicted from the ring), or -EPERM (the caller was not
 /// its supervisor — the same authority gate as process_kill).
 pub fn exitReasonOf(caller_id: u32, target_id: u32) i64 {
    const flags = sync.enter();
    defer sync.leave(flags);
    for (&exit_records) |*record| {
        if (record.valid and record.id == target_id) {
            if (record.supervisor != caller_id) return -ipc.EPERM;
            return @intFromEnum(record.reason);
        }
    }
    return -ipc.ESRCH;
 }
 /// The published exit events' subscribers (docs/process-lifecycle.md "Who learns
 /// of a death"): stateful services — the VFS's file handles, input's
 /// subscriptions — that must release what a dead client held and cannot learn it
 /// any other way (a client that simply never calls again looks like silence).
 /// Bounded like every kernel table; each entry holds its own endpoint reference.
 const exit_subscriber_capacity = 8;
 const ExitSubscriber = struct { endpoint: *ipc.Endpoint, owner: u32 };
 var exit_subscribers: [exit_subscriber_capacity]?ExitSubscriber = .{null} ** exit_subscriber_capacity;
 /// process_subscribe(endpoint): subscribe the caller's endpoint to published exit
 /// events. Ungated, like process_enumerate — what is running (and dying) is not a
 /// secret between cooperating processes. -ENOSPC when the table is full.
 fn systemProcessSubscribe(state: *architecture.CpuState) void {
    const t = scheduler.current();
    if (t.aspace == 0) return fail(state);
    const endpoint = ipc.resolveHandle(t, architecture.systemCallArg(state, 0)) orelse return failErr(state, ipc.EBADF);
    const flags = sync.enter();
    defer sync.leave(flags);
    for (&exit_subscribers) |*slot| {
        if (slot.* == null) {
            endpoint.refcount += 1; // the slot's own reference, dropped on unsubscribe-by-death
            slot.* = .{ .endpoint = endpoint, .owner = t.id };
            return architecture.setSystemCallResult(state, 0);
        }
    }
    failErr(state, ipc.ENOSPC);
 }
 /// signal_bind(endpoint): nominate where this process's signals arrive — the
 /// IRQ-as-IPC pattern a fourth time (docs/process-lifecycle.md). Replacing a
 /// binding drops the old reference; signals that pended while unbound are
 /// delivered immediately on bind, coalesced into one notification.
 fn systemSignalBind(state: *architecture.CpuState) void {
    const t = scheduler.current();
    if (t.aspace == 0) return fail(state);
    const endpoint = ipc.resolveHandle(t, architecture.systemCallArg(state, 0)) orelse return failErr(state, ipc.EBADF);
    const flags = sync.enter();
    defer sync.leave(flags);
    if (t.signal_endpoint) |raw| ipc.dropRef(@ptrCast(@alignCast(raw)));
    endpoint.refcount += 1;
    t.signal_endpoint = @ptrCast(endpoint);
    if (t.pending_signals != 0) {
        ipc.notifyLocked(endpoint, abi.notify_signal_bit | t.pending_signals);
        t.pending_signals = 0;
    }
    architecture.setSystemCallResult(state, 0);
 }
 /// process_signal(id, signal): post a signal — a one-way, coalescing statement,
 /// never a question (docs/process-lifecycle.md). The authority gate is the
 /// supervision link, like kill; a process may also signal itself. Unbound
 /// targets accumulate the signal in their pending mask.
 fn systemProcessSignal(state: *architecture.CpuState) void {
    const t = scheduler.current();
    if (t.aspace == 0) return fail(state);
    const id = architecture.systemCallArg(state, 0);
    const signal = architecture.systemCallArg(state, 1);
    if (id > std.math.maxInt(u32)) return failErr(state, ipc.ESRCH);
    if (signal > 31) return failErr(state, ipc.EBADF); // not a Signal bit position
    const flags = sync.enter();
    defer sync.leave(flags);
    const target = scheduler.taskByIdLocked(@intCast(id)) orelse return failErr(state, ipc.ESRCH);
    if (target.aspace == 0) return failErr(state, ipc.ESRCH);
    if (target.supervisor != t.id and target.id != t.id) return failErr(state, ipc.EPERM);
    target.pending_signals |= @as(u32, 1) << @intCast(signal);
    if (target.signal_endpoint) |raw| {
        const endpoint: *ipc.Endpoint = @ptrCast(@alignCast(raw));
        ipc.notifyLocked(endpoint, abi.notify_signal_bit | target.pending_signals);
        target.pending_signals = 0;
    }
    architecture.setSystemCallResult(state, 0);
 }
 /// The one-shot timers of timer_bind: the missing timed wait. A service arms a
 /// deadline and keeps serving; the expiry arrives in the same replyWait as
 /// everything else (notify_timer_bit). What stop-sequence escalation, hello
 /// deadlines, and restart backoff are built from — and later, `alarm`.
 const timer_capacity = 16;
 const OneShotTimer = struct { deadline: u64, endpoint: *ipc.Endpoint, owner: u32 };
 var one_shot_timers: [timer_capacity]?OneShotTimer = .{null} ** timer_capacity;
 /// Sweep expired timers — hung on scheduler.timer_tick_hook, so it runs on every
 /// tick with the big kernel lock held, like the sleeper wake it rides beside.
 fn timerSweepLocked() void {
    const now = architecture.millis();
    for (&one_shot_timers) |*slot| {
        if (slot.*) |timer| {
            if (now >= timer.deadline) {
                ipc.notifyLocked(timer.endpoint, abi.notify_timer_bit);
                ipc.dropRef(timer.endpoint);
                slot.* = null;
            }
        }
    }
 }
 /// timer_bind(endpoint, ms): arm a one-shot timer. -ENOSPC when the table is full.
 fn systemTimerBind(state: *architecture.CpuState) void {
    const t = scheduler.current();
    if (t.aspace == 0) return fail(state);
    const endpoint = ipc.resolveHandle(t, architecture.systemCallArg(state, 0)) orelse return failErr(state, ipc.EBADF);
    const ms = architecture.systemCallArg(state, 1);
    const flags = sync.enter();
    defer sync.leave(flags);
    for (&one_shot_timers) |*slot| {
        if (slot.* == null) {
            endpoint.refcount += 1;
            slot.* = .{ .deadline = architecture.millis() + ms, .endpoint = endpoint, .owner = t.id };
            return architecture.setSystemCallResult(state, 0);
        }
    }
    failErr(state, ipc.ENOSPC);
 }
 fn systemProcessExitReason(state: *architecture.CpuState) void {
    const t = scheduler.current();
    if (t.aspace == 0) return fail(state);
    const id = architecture.systemCallArg(state, 0);
    if (id > std.math.maxInt(u32)) return failErr(state, ipc.ESRCH);
    const r = exitReasonOf(t.id, @intCast(id));
    architecture.setSystemCallResult(state, @bitCast(r));
 }
 /// Resolve `(device_id, resource_index)` to a GSI this process is entitled to bind, or null.
 /// The two checks are the whole security story: the device must be *claimed* by the
 /// caller, and the resource must be one of that device's `irq` resources as recorded
@@ -50,6 +50,17 @@ pub const Task = struct {
    // null. Holds its own reference, dropped when the notification is posted.
    // Opaque here for the same reason as `handles` below.
    exit_endpoint: ?*anyopaque = null,
    // How this process ended — set by the death paths (exit, fault, kill) just
    // before the reap records it for `process_exit_reason`. Meaningless while
    // the task lives.
    exit_reason: abi.ExitReason = .exited,
    // Endpoint this process's signals arrive on (signal_bind), or null — same
    // ownership rules as exit_endpoint (holds a reference; opaque here).
    signal_endpoint: ?*anyopaque = null,
    // Signals posted but not yet delivered: the coalescing pending mask
    // (docs/process-lifecycle.md). Bits are abi.Signal values. Signals pend here
    // until an endpoint is bound; two pending terminates are one terminate.
    pending_signals: u32 = 0,
    // Set by process_kill on a task that is running on another core; the kernel
    // finishes the kill at that task's next system call or timer tick.
    kill_pending: bool = false,
@@ -643,9 +654,15 @@ fn reapKillPendingLocked() void {
 /// other critical section, but releases it *without* touching the interrupt flag
 /// — the handler's `iretq` restores the interrupted context's flags, so
 /// re-enabling here would open a nested-interrupt window before the return.
 /// Called from the tick with the big kernel lock held — process.zig hangs the
 /// one-shot timer sweep here (timer_bind), the same call-up pattern as the
 /// teardown hooks below.
 pub var timer_tick_hook: ?*const fn () void = null;
 pub fn tick() void {
    _ = sync.enter();
    wakeExpired();
    if (timer_tick_hook) |hook| hook();
    reapKillPendingLocked();
    if (preemption_enabled) schedule();
    sync.leaveIsr();
@@ -132,6 +132,14 @@ pub fn run(case: []const u8, boot_information: *const BootInformation) void {
        processKillTest(boot_information);
    } else if (eql(case, "supervision")) {
        supervisionTest(boot_information);
    } else if (eql(case, "claim-release")) {
        claimReleaseTest(boot_information);
    } else if (eql(case, "vfs-client-death")) {
        vfsClientDeathTest(boot_information);
    } else if (eql(case, "signals")) {
        signalsTest(boot_information);
    } else if (eql(case, "driver-restart")) {
        driverRestartTest(boot_information);
    } else if (eql(case, "initial-ramdisk")) {
        initialRamdiskTest(boot_information);
    } else if (eql(case, "vfs")) {
@@ -1207,15 +1215,15 @@ fn userPfTest() void {
 /// hand — address space, code page RO+X, stack page RW+NX — because the blob is a
 /// raw code fragment, not an ELF `spawnProcess` could load. Returns false if any
 /// allocation fails.
-fn spawnFaultingProcess() bool {
+fn spawnFaultingProcess() ?u32 {
    const blob = process.pfBlob();
    const flags = sync.enter();
    defer sync.leave(flags);
-    const aspace = architecture.createAddressSpace() orelse return false;
+    const aspace = architecture.createAddressSpace() orelse return null;
    const code_frame = pmm.alloc() orelse {
        architecture.destroyAddressSpace(aspace);
-        return false;
+        return null;
    };
    // Fill through the physmap (the user mapping is read-only); pad with int3 so a
    // stray jump traps instead of sliding.
@@ -1226,15 +1234,16 @@ fn spawnFaultingProcess() bool {
    const stack_frame = pmm.alloc() orelse {
        architecture.destroyAddressSpace(aspace); // frees code_frame too — it's mapped
-        return false;
+        return null;
    };
    architecture.mapUserPageInto(aspace, process.stack_base_virtual, stack_frame, true, false); // RW + NX
-    if (scheduler.spawnUserLocked(aspace, process.code_virtual, process.stack_base_virtual + abi.page_size, 4, "fault-probe", 0, null) == null) {
+    // Supervised by the calling test task, so exitReasonOf can read the verdict.
    const id = scheduler.spawnUserLocked(aspace, process.code_virtual, process.stack_base_virtual + abi.page_size, 4, "fault-probe", scheduler.currentId(), null) orelse {
        architecture.destroyAddressSpace(aspace);
-        return false;
+        return null;
-    }
+    };
-    return true;
+    return id;
 }
 /// Fault recovery (docs/resilience.md step 2): a scheduled ring-3 process that
@@ -1263,7 +1272,8 @@ fn faultRecoveryTest(boot_information: *const BootInformation) void {
    scheduler.setPriority(4);
    check("init heartbeat before the fault", process.write_count >= 1);
-    check("faulting process spawned", spawnFaultingProcess());
+    const probe = spawnFaultingProcess() orelse 0;
    check("faulting process spawned", probe != 0);
    // The kill: the faulting process #PFs on its first instruction and the kernel
    // reaps it instead of halting.
@@ -1272,6 +1282,7 @@ fn faultRecoveryTest(boot_information: *const BootInformation) void {
    while (process.fault_kill_count < 1 and architecture.millis() < deadline) scheduler.yield();
    scheduler.setPriority(4);
    check("faulting process was killed (not the machine)", process.fault_kill_count == 1);
    check("the probe's reason reads segmentation_fault", process.exitReasonOf(scheduler.currentId(), probe) == @intFromEnum(abi.ExitReason.segmentation_fault));
    // Life after the kill: init must keep beating on the same core.
    const beats_at_kill = process.write_count;
@@ -1423,6 +1434,12 @@ fn processKillTest(boot_information: *const BootInformation) void {
    check("the sleeper's exit notification arrived (length 0)", r == 0);
    check("its badge carries the exit bit and the child id", badge == abi.notify_badge_bit | abi.notify_exit_bit | sleeper);
    // M17.2: the recorded reason — the notification is the fence, so it is
    // already readable, and gated by the same supervisor check as the kill.
    check("the sleeper's reason reads killed", process.exitReasonOf(me, sleeper) == @intFromEnum(abi.ExitReason.killed));
    check("a non-supervisor may not read the reason (-EPERM)", process.exitReasonOf(me + 12345, sleeper) == -ipcsync.EPERM);
    check("an unknown id has no reason (-ESRCH)", process.exitReasonOf(me, 0xFFFF_FF00) == -ipcsync.ESRCH);
    const beats_at_kill = process.write_count;
    scheduler.sleep(1500); // more than one heartbeat period
    check("the heartbeat stopped with the kill", process.write_count == beats_at_kill);
@@ -1443,6 +1460,21 @@ fn processKillTest(boot_information: *const BootInformation) void {
    check("the spinner's exit notification arrived (length 0)", r == 0);
    check("its badge carries the exit bit and the child id", badge == abi.notify_badge_bit | abi.notify_exit_bit | spinner);
    // M17.2: a child that ends on its own must read exited, not killed —
    // args-echo with arguments echoes once and returns from main.
    var clean: u32 = 0;
    i = 0;
    while (i < rd.count) : (i += 1) {
        const item = rd.entry(i) orelse continue;
        if (!eql(item.name, "args-echo")) continue;
        clean = process.spawnProcessSupervised(item.blob, 4, &.{ "args-echo", "clean-exit" }, me, endpoint) catch 0;
        break;
    }
    check("args-echo spawned as the clean-exit child", clean != 0);
    r = ipcsync.replyWait(endpoint, 0, 0, 0, 0, abi.no_cap, &badge, &received_cap);
    check("the clean child's exit notification arrived", badge == abi.notify_badge_bit | abi.notify_exit_bit | clean);
    check("the clean child's reason reads exited", process.exitReasonOf(me, clean) == @intFromEnum(abi.ExitReason.exited));
    var table: [32]abi.ProcessDescriptor = undefined;
    const total = scheduler.enumerate(&table);
    var still_listed = false;
@@ -1454,6 +1486,214 @@ fn processKillTest(boot_information: *const BootInformation) void {
    result();
 }
 /// M17.1: a dead process's device claims are released by the reap, so a restarted
 /// driver can claim its hardware again (docs/process-lifecycle.md iron rule 1).
 /// First the broker release in isolation — two owners, one released, the other's
 /// claim must survive. Then the death-path wiring with a real child: the claim is
 /// made on the child's behalf (the broker is kernel-callable), the child is
 /// killed, and once the exit notification arrives — posted last, after release —
 /// the device must be unclaimed and claimable again.
 fn claimReleaseTest(boot_information: *const BootInformation) void {
    log("DANOS-TEST-BEGIN: claim-release\n", .{});
    var buffer: [2]device_abi.DeviceDescriptor = undefined;
    const total = devices_broker.enumerate(&buffer);
    check("the device tree is seeded (>= 2 devices)", total >= 2);
    if (total < 2) {
        result();
        return;
    }
    // The broker release in isolation.
    check("device 0 claimed by owner 111", devices_broker.claim(0, 111));
    check("device 1 claimed by owner 222", devices_broker.claim(1, 222));
    devices_broker.releaseAllOwnedBy(111);
    check("owner 111's claim is released", devices_broker.ownerOf(0) == null);
    check("owner 222's claim survives", (devices_broker.ownerOf(1) orelse 0) == 222);
    devices_broker.releaseAllOwnedBy(222);
    check("cleanup released owner 222", devices_broker.ownerOf(1) == null);
    // The death-path wiring: a real process dies holding a claim.
    check("bootloader handed over /system/services/init", boot_information.init_len != 0);
    if (boot_information.init_len == 0) {
        result();
        return;
    }
    const image = @as([*]const u8, @ptrFromInt(boot_handoff.physicalToVirtual(boot_information.init_base)))[0..boot_information.init_len];
    const me = scheduler.currentId();
    const endpoint = ipcsync.createIpcEndpoint() orelse {
        check("exit endpoint allocated", false);
        result();
        return;
    };
    const child = process.spawnProcessSupervised(image, 4, &.{"/system/services/init"}, me, endpoint) catch 0;
    check("supervised child spawned", child != 0);
    check("device 0 claimed on the child's behalf", devices_broker.claim(0, child));
    check("the kill is accepted", process.killProcess(me, child) == 0);
    var badge: u64 = 0;
    var received_cap: u64 = 0;
    _ = ipcsync.replyWait(endpoint, 0, 0, 0, 0, abi.no_cap, &badge, &received_cap);
    check("the exit notification arrived", badge == abi.notify_badge_bit | abi.notify_exit_bit | child);
    check("death released the child's claim", devices_broker.ownerOf(0) == null);
    check("the device is claimable again", devices_broker.claim(0, me));
    devices_broker.releaseAllOwnedBy(me);
    result();
 }
 /// M17.3: the published exit events, proven by their first subscriber. The VFS
 /// subscribes at startup; a client opens a file and parks holding the handle;
 /// the kill posts the exit event to the VFS's endpoint; the VFS releases the
 /// dead client's handle and says so — the service-side mirror of iron rule 1
 /// (a service must never depend on clients cleaning up after themselves).
 fn vfsClientDeathTest(boot_information: *const BootInformation) void {
    log("DANOS-TEST-BEGIN: vfs-client-death\n", .{});
    if (boot_information.initial_ramdisk_len == 0) {
        check("bootloader handed over an initial_ramdisk", false);
        result();
        return;
    }
    const image = @as([*]const u8, @ptrFromInt(boot_handoff.physicalToVirtual(boot_information.initial_ramdisk_base)))[0..boot_information.initial_ramdisk_len];
    const rd = initial_ramdisk.Reader.init(image) orelse {
        check("initial_ramdisk image is valid", false);
        result();
        return;
    };
    process.write_count = 0;
    check("vfs spawned", spawnNamed(rd, "vfs"));
    const me = scheduler.currentId();
    const endpoint = ipcsync.createIpcEndpoint() orelse {
        check("exit endpoint allocated", false);
        result();
        return;
    };
    var client: u32 = 0;
    var i: u32 = 0;
    while (i < rd.count) : (i += 1) {
        const item = rd.entry(i) orelse continue;
        if (!eql(item.name, "vfs-test")) continue;
        client = process.spawnProcessSupervised(item.blob, 4, &.{ "vfs-test", "park" }, me, endpoint) catch 0;
        break;
    }
    check("parked client spawned (supervised)", client != 0);
    // Its heartbeat is the fence: once it beats, the handle is open.
    const parked = "vfstest: parked";
    scheduler.setPriority(1);
    var deadline = architecture.millis() + 10000;
    while (architecture.millis() < deadline) {
        if (process.write_len >= parked.len and eql(process.write_buffer[0..parked.len], parked)) break;
        scheduler.yield();
    }
    scheduler.setPriority(4);
    check("client parked holding an open handle", process.write_len >= parked.len and eql(process.write_buffer[0..parked.len], parked));
    check("the kill is accepted", process.killProcess(me, client) == 0);
    var badge: u64 = 0;
    var received_cap: u64 = 0;
    _ = ipcsync.replyWait(endpoint, 0, 0, 0, 0, abi.no_cap, &badge, &received_cap);
    check("the exit notification arrived", badge == abi.notify_badge_bit | abi.notify_exit_bit | client);
    // The VFS heard the same published event; its release line is the proof.
    const released = "vfs: released 1 handle(s) for dead client";
    scheduler.setPriority(1);
    deadline = architecture.millis() + 10000;
    while (architecture.millis() < deadline) {
        if (process.write_len >= released.len and eql(process.write_buffer[0..released.len], released)) break;
        scheduler.yield();
    }
    scheduler.setPriority(4);
    check("the VFS released the dead client's handle", process.write_len >= released.len and eql(process.write_buffer[0..released.len], released));
    result();
 }
 /// M17.4 from ring 3: process-test's signal-run role drives the whole lifecycle
 /// surface — the zero-length ping (answered by the harness), signals as
 /// statements (reload logged, terminate = clean exit), the one-shot timer, and
 /// both endings of the stop sequence (polite -> exited, deaf -> killed at the
 /// deadline). Its "process-test: signals ok" is the pass marker.
 fn signalsTest(boot_information: *const BootInformation) void {
    log("DANOS-TEST-BEGIN: signals\n", .{});
    if (boot_information.initial_ramdisk_len == 0) {
        check("bootloader handed over an initial_ramdisk", false);
        result();
        return;
    }
    const image = @as([*]const u8, @ptrFromInt(boot_handoff.physicalToVirtual(boot_information.initial_ramdisk_base)))[0..boot_information.initial_ramdisk_len];
    const rd = initial_ramdisk.Reader.init(image) orelse {
        check("initial_ramdisk image is valid", false);
        result();
        return;
    };
    process.setInitialRamdisk(image); // the parent system_spawns its children by name
    process.write_count = 0;
    var runner: u32 = 0;
    var i: u32 = 0;
    while (i < rd.count) : (i += 1) {
        const item = rd.entry(i) orelse continue;
        if (!eql(item.name, "process-test")) continue;
        runner = process.spawnProcessSupervised(item.blob, 4, &.{ "process-test", "signal-run" }, scheduler.currentId(), null) catch 0;
        break;
    }
    check("signal-run parent spawned", runner != 0);
    const pass_marker = "process-test: signals ok";
    const fail_marker = "process-test: FAIL";
    scheduler.setPriority(1);
    const deadline = architecture.millis() + 15000;
    var saw_pass = false;
    var saw_fail = false;
    while (architecture.millis() < deadline and !saw_pass and !saw_fail) {
        if (process.write_len >= pass_marker.len and eql(process.write_buffer[0..pass_marker.len], pass_marker)) saw_pass = true;
        if (process.write_len >= fail_marker.len and eql(process.write_buffer[0..fail_marker.len], fail_marker)) saw_fail = true;
        scheduler.yield();
    }
    scheduler.setPriority(4);
    check("the signal-run parent reported ok", saw_pass and !saw_fail);
    result();
 }
 /// M18.1: the device manager's restart machinery, end to end. In test-restart
 /// mode the manager also supervises crash-test: a fixture that claims device 0,
 /// hellos, and faults. The scenario asserts three markers in order — the real
 /// xHCI driver hellos clean and stays; crash-test is restarted with backoff
 /// (each respawn re-claiming the device the dead instance held, M17.1 through
 /// the manager's path); the crash loop caps and the manager gives up.
 fn driverRestartTest(boot_information: *const BootInformation) void {
    log("DANOS-TEST-BEGIN: driver-restart\n", .{});
    if (boot_information.initial_ramdisk_len == 0) {
        check("bootloader handed over an initial_ramdisk", false);
        result();
        return;
    }
    const image = @as([*]const u8, @ptrFromInt(boot_handoff.physicalToVirtual(boot_information.initial_ramdisk_base)))[0..boot_information.initial_ramdisk_len];
    const rd = initial_ramdisk.Reader.init(image) orelse {
        check("initial_ramdisk image is valid", false);
        result();
        return;
    };
    process.setInitialRamdisk(image); // the manager system_spawns drivers by name
    process.write_count = 0;
    var manager: u32 = 0;
    var i: u32 = 0;
    while (i < rd.count) : (i += 1) {
        const item = rd.entry(i) orelse continue;
        if (!eql(item.name, "device-manager")) continue;
        manager = process.spawnProcessSupervised(item.blob, 4, &.{ "device-manager", "test-restart" }, scheduler.currentId(), null) catch 0;
        break;
    }
    check("device-manager spawned in test-restart mode", manager != 0);
    // The assertions live in the harness: its expect regex requires, in order,
    // the xHCI hello ack, a crash-test restart, and the crash-loop cap — read
    // from the whole serial capture, immune to the transient-line races a
    // write_buffer poll would have here (many processes log concurrently).
    result();
 }
 /// The whole user-side surface at once: spawn process-test's supervisor role,
 /// which — entirely from ring 3 — creates an exit endpoint, spawns its two
 /// children supervised, sees them in process_enumerate, kills them (one blocked,
@@ -16,8 +16,11 @@
 pub const maximum_cpus = 128;
 /// Maximum tasks (kernel threads) alive at once — the static task-table size. Each
-/// online core consumes one slot for its idle task, plus task 0 on the BSP.
+/// online core consumes one slot for its idle task, plus task 0 on the BSP. Sized
-pub const maximum_tasks = 16;
+/// for the initial-ramdisk sweep (15 bundled binaries spawned at once) plus the
 /// device manager's supervised children with room to grow — at 16 the sweep
 /// started failing spawns once the bundle passed a dozen binaries.
 pub const maximum_tasks = 32;
 /// Each task's kernel stack (also each AP's bring-up stack), in bytes.
 pub const kernel_stack_size = 16 * 1024;
@@ -0,0 +1,44 @@
 //! crash-test — a test fixture, not a driver: claims the device it is assigned,
 //! hellos the device manager, announces itself, then faults on purpose. The
 //! driver-restart scenario drives the manager's whole restart machinery with
 //! it: fault → exit reason → backoff → respawn → the **same claim succeeding
 //! again** (claim release on death, M17.1, through the manager's path) → the
 //! crash-loop cap. Spawned bare (the initial-ramdisk sweep starts every bundled
 //! binary), it exits silently so it cannot derange other tests.
 const std = @import("std");
 const runtime = @import("runtime");
 const protocol = runtime.device_manager_protocol;
 pub fn main(init: runtime.process.Init) void {
    const argument = init.arguments.get(1) orelse return; // bare: stay silent
    const assigned = std.fmt.parseInt(u64, argument, 10) catch return;
    // The respawn only reaches this line because the kernel released the
    // previous instance's claim at death. A failed claim exits cleanly — the
    // manager reads "meant to stop" and the scenario fails loudly by silence.
    if (!runtime.device.claim(assigned)) {
        _ = runtime.system.write("crash-test: claim failed\n");
        return;
    }
    var manager: ?runtime.ipc.Handle = null;
    var tries: u32 = 0;
    while (manager == null and tries < 100) : (tries += 1) {
        manager = runtime.ipc.lookup(.device_manager);
        if (manager == null) runtime.system.sleep(20);
    }
    const h = manager orelse return;
    const hello = protocol.Hello{ .role = @intFromEnum(protocol.Role.device), .device_id = assigned };
    var reply: [protocol.message_maximum]u8 = undefined;
    _ = runtime.ipc.call(h, std.mem.asBytes(&hello), &reply) catch return;
    _ = runtime.system.write("crash-test: faulting now\n");
    const poison: *volatile u32 = @ptrFromInt(0xdead0000);
    poison.* = 1; // the restart machinery's fuel: a real segmentation fault
 }
 pub const panic = runtime.panic;
 comptime {
    _ = &runtime.start._start; // pull the runtime entry shim into the image
 }
@@ -0,0 +1,58 @@
 //! The device-manager protocol (docs/device-manager.md): what drivers and
 //! applications say to the device manager over its well-known endpoint. The
 //! vfs-protocol pattern — extern-struct messages, a version in the handshake,
 //! reserved fields — so both sides depend on the contract by name. Deliberately
 //! contains nothing lifecycle-shaped: stopping, liveness (the zero-length ping),
 //! and exit reasons are the universal vocabulary of
 //! docs/process-lifecycle.md, not this protocol.
 /// The protocol version a driver states in its hello. A manager that cannot
 /// serve a driver's version refuses the hello, and the mismatch is loud at
 /// startup instead of quiet corruption later.
 pub const version: u16 = 1;
 /// What kind of driver is talking (docs/driver-model.md's shapes).
 pub const Role = enum(u8) {
    /// Owns a controller and reports the devices behind it (`child_added`).
    bus = 1,
    /// Serves one device, reached through a bus's transfer protocol.
    device = 2,
 };
 /// The message kinds. `child_added`/`child_removed` land in M18.2;
 /// `enumerate`/`subscribe` in M18.3.
 pub const Operation = enum(u8) {
    hello = 1,
 };
 /// `Hello.device_id` for a driver that serves no enumerated device (a test
 /// fixture, a synthetic source).
 pub const no_device: u64 = ~@as(u64, 0);
 /// The handshake, sent once by every driver the manager spawns — the manager's
 /// one self-enforced deadline: spawned and silent past it means wrong binary,
 /// wrong version, or wedged before main, and the stop sequence follows.
 pub const Hello = extern struct {
    operation: u8 = @intFromEnum(Operation.hello),
    /// A Role value.
    role: u8,
    /// The protocol version this driver was built against (`version`).
    version: u16 = version,
    reserved: u32 = 0,
    /// The device this driver was assigned (its argv[1]), or `no_device`.
    device_id: u64,
 };
 pub const hello_size = @sizeOf(Hello);
 /// The manager's answer to a hello. Nonzero status = refused (version mismatch,
 /// unknown sender); a refused driver should exit cleanly.
 pub const HelloReply = extern struct {
    status: i32,
    reserved: u32 = 0,
 };
 pub const reply_size = @sizeOf(HelloReply);
 /// Upper bound on any message in this protocol — sizes the endpoint buffers.
 pub const message_maximum = 64;
@@ -1,20 +1,24 @@
 //! /system/services/device-manager — the ring-3 process that turns the device
-//! tree into a running system. The kernel enumerates the hardware and enforces the
+//! tree into a running system: **the matcher and the supervisor**
-//! claim capability (mechanism); this decides *which driver serves which device*
+//! (docs/device-manager.md). The kernel enumerates the hardware and enforces the
-//! and, eventually, spawns it (policy). Keeping that split in user space is the
+//! claim capability (mechanism); this decides which driver serves which device,
-//! whole point of the microkernel: the manager is an ordinary, restartable process
+//! spawns it, and keeps it alive (policy). Keeping that split in user space is
-//! with no special privilege — it uses the same `device_*` system calls any process
+//! the whole point of the microkernel: the manager is an ordinary, restartable
-//! could ([drivers.md](../../../docs/drivers.md), [driver-model.md]).
+//! process with no special privilege.
 //!
-//! Increment 2 (this file): enumerate /system/devices, *match* each device to a
+//! M18.1 (this increment): the manager is a harness service on the well-known
-//! driver, and *spawn* it with `system_spawn` — the kernel loads the named binary
+//! `.device_manager` endpoint. Every driver is spawned **supervised** — exit
-//! from the initial-ramdisk as a fresh ring-3 process. On QEMU this discovers the
+//! notifications land in the same loop as protocol messages. Drivers with an
-//! HPET, decides `hpet` serves it, and brings that driver all the way up. (The
+//! assignment must `hello` within a deadline or be stopped; a driver that dies
-//! kernel still auto-spawns the whole initial-ramdisk at boot; increment 3 removes
+//! is restarted with backoff, and a crash loop (three fast deaths) marks it
-//! that redundancy so the manager is the sole owner of driver spawning.)
+//! failed instead of respawning forever. Exit reasons (M17.2) drive the
 //! decision: a clean exit meant to stop; only faults and missed deadlines
 //! restart. Tree reports (`child_added`) land in M18.2.
 const std = @import("std");
 const runtime = @import("runtime");
 const acpi_ids = @import("acpi-ids");
 const protocol = runtime.device_manager_protocol;
 const device = runtime.device;
 const system = runtime.system;
@@ -27,9 +31,8 @@ fn writeLine(comptime fmt: []const u8, arguments: anytype) void {
 }
 /// The driver that serves each device — the policy table. In a fuller system
-/// this comes from the drivers describing what they bind (or a manifest under
+/// this comes from a manifest (docs/device-manager.md: the third bus type
-/// /system/drivers); for now it is a small static map, which is enough to prove the
+/// triggers it); for now a static map. `null` = no driver for this class yet.
 /// manager reads the tree and decides. `null` = no driver for this class yet.
 fn driverFor(d: device.DeviceDescriptor) ?[]const u8 {
    // detect device via DeviceClass
    if (d.class == @intFromEnum(device.DeviceClass.timer)) return "hpet";
@@ -47,10 +50,9 @@ fn driverFor(d: device.DeviceDescriptor) ?[]const u8 {
 /// pci-class.zig decodes.
 const xhci_pci_class: u64 = 0x0C_03_30;
-/// The bus driver that serves a PCI function, or null. Unlike the singleton drivers
+/// The bus driver that serves a PCI function, or null. A machine can carry
-/// in `driverFor`, a machine can carry several identical controllers — so the caller
+/// several identical controllers — one driver instance per device, the id as
-/// spawns one driver instance *per device*, passing the device id as argv[1] for the
+/// argv[1]. These drivers speak the protocol: a hello is expected.
 /// instance to claim.
 fn pciDriverFor(d: device.DeviceDescriptor) ?[]const u8 {
    if (d.class != @intFromEnum(device.DeviceClass.pci_device)) return null;
    return switch (d.pci_class) {
@@ -59,24 +61,169 @@ fn pciDriverFor(d: device.DeviceDescriptor) ?[]const u8 {
    };
 }
-/// Spawn one instance of `driver_name` to serve the specific device `id` — the id
+// --- supervision -------------------------------------------------------------
-/// arrives as argv[1]. No isProcessRunning gate here: the name alone cannot tell two
+
-/// instances apart, and this manager is the sole spawner of drivers.
+/// How long a protocol driver has to hello after its spawn.
-fn spawnForDevice(driver_name: []const u8, id: u64) void {
+const hello_deadline_ms: u64 = 3000;
-    var text: [20]u8 = undefined;
+/// Deaths faster than this count toward the crash loop; slower ones reset it.
-    const id_text = std.fmt.bufPrint(&text, "{d}", .{id}) catch return;
+const fast_death_ns: u64 = 2_000_000_000;
-    if (system.spawnWithArguments(driver_name, &.{id_text}) != null) {
+/// Consecutive fast deaths before the manager gives up on a driver.
-        writeLine("device-manager: spawned {s} for device {d}\n", .{ driver_name, id });
+const crash_loop_cap: u32 = 3;
 /// Restart backoff: base << (restarts - 1), so 300 ms, 600 ms, 1200 ms.
 const backoff_base_ms: u64 = 300;
 const DriverState = enum {
    awaiting_hello, // spawned; the deadline is armed (protocol drivers only)
    running,
    restarting, // dead; respawn due at restart_due_ns
    stopped, // exited cleanly — it meant to; not restarted
    failed, // crash loop, or unspawnable; the manager gave up
 };
 const Driver = struct {
    used: bool = false,
    name_buffer: [24]u8 = undefined,
    name_len: usize = 0,
    // The assigned device id (becomes argv[1]), or protocol.no_device.
    device_id: u64 = protocol.no_device,
    // Whether this driver speaks the protocol (hello expected, deadline
    // enforced). Legacy drivers (hpet, ps2-bus) are supervised and restarted
    // but not yet required to hello.
    speaks_protocol: bool = false,
    process_id: u32 = 0,
    state: DriverState = .running,
    restarts: u32 = 0,
    spawn_ns: u64 = 0,
    hello_deadline_ns: u64 = 0,
    restart_due_ns: u64 = 0,
    fn name(driver: *const Driver) []const u8 {
        return driver.name_buffer[0..driver.name_len];
    }
 };
 const maximum_drivers = 16;
 var drivers: [maximum_drivers]Driver = .{Driver{}} ** maximum_drivers;
 var manager_endpoint: runtime.ipc.Handle = 0;
 var test_restart_mode = false;
 fn driverByProcess(process_id: u32) ?*Driver {
    for (&drivers) |*driver| {
        if (driver.used and driver.process_id == process_id) return driver;
    }
    return null;
 }
 /// Whether a singleton driver is already in the table (two ACPI nodes can both
 /// map to ps2-bus; one instance serves both).
 fn alreadySupervised(name: []const u8) bool {
    for (&drivers) |*driver| {
        if (driver.used and std.mem.eql(u8, driver.name(), name)) return true;
    }
    return false;
 }
 /// Record a driver in the table and spawn its first instance.
 fn addDriver(name: []const u8, device_id: u64, speaks_protocol: bool) void {
    for (&drivers) |*driver| {
        if (driver.used) continue;
        const n = @min(name.len, driver.name_buffer.len);
        @memcpy(driver.name_buffer[0..n], name[0..n]);
        driver.name_len = n;
        driver.device_id = device_id;
        driver.speaks_protocol = speaks_protocol;
        driver.used = true;
        spawnDriver(driver);
        return;
    }
    writeLine("device-manager: driver table full; cannot supervise {s}\n", .{name});
 }
 /// (Re)spawn a driver instance: supervised on the manager's own endpoint, the
 /// device id as argv[1] when it has one, the hello deadline armed when it
 /// speaks the protocol.
 fn spawnDriver(driver: *Driver) void {
    var id_text: [20]u8 = undefined;
    var arguments: [1][]const u8 = undefined;
    var argument_count: usize = 0;
    if (driver.device_id != protocol.no_device) {
        arguments[0] = std.fmt.bufPrint(&id_text, "{d}", .{driver.device_id}) catch return;
        argument_count = 1;
    }
    const child = system.spawnSupervised(driver.name(), arguments[0..argument_count], manager_endpoint) orelse {
        writeLine("device-manager: failed to spawn {s}\n", .{driver.name()});
        driver.state = .failed;
        return;
    };
    driver.process_id = child;
    driver.spawn_ns = system.clock();
    if (driver.speaks_protocol) {
        driver.state = .awaiting_hello;
        driver.hello_deadline_ns = driver.spawn_ns + hello_deadline_ms * 1_000_000;
        _ = system.timerOnce(manager_endpoint, hello_deadline_ms + 100);
    } else {
-        writeLine("device-manager: failed to spawn {s} for device {d}\n", .{ driver_name, id });
+        driver.state = .running;
    }
    if (driver.device_id != protocol.no_device) {
        writeLine("device-manager: spawned {s} for device {d}\n", .{ driver.name(), driver.device_id });
    } else {
        writeLine("device-manager: spawned {s}\n", .{driver.name()});
    }
 }
-pub fn main() void {
+/// A driver died. The exit reason (M17.2) is the whole decision: a clean exit
 /// meant to stop; anything else restarts with backoff until the crash-loop cap.
 fn onDriverExit(driver: *Driver) void {
    const reason = runtime.process.exitReason(driver.process_id) orelse .fault;
    if (reason == .exited) {
        driver.state = .stopped;
        writeLine("device-manager: {s} exited cleanly; not restarting\n", .{driver.name()});
        return;
    }
    const now = system.clock();
    const alive_ns = now - driver.spawn_ns;
    driver.restarts = if (alive_ns < fast_death_ns) driver.restarts + 1 else 1;
    if (driver.restarts >= crash_loop_cap) {
        driver.state = .failed;
        writeLine("device-manager: {s} is failing repeatedly (crash loop); giving up\n", .{driver.name()});
        return;
    }
    const delay_ms = backoff_base_ms << @intCast(driver.restarts - 1);
    driver.state = .restarting;
    driver.restart_due_ns = now + delay_ms * 1_000_000;
    writeLine("device-manager: restarting {s} in {d} ms (died: {s})\n", .{ driver.name(), delay_ms, @tagName(reason) });
    _ = system.timerOnce(manager_endpoint, delay_ms + 50);
 }
 /// A timer landed: sweep every deadline. Overdue hellos are killed (the exit
 /// notification then routes through the normal restart policy); due restarts
 /// respawn. Timers carry no id on purpose — the table is the state, and one
 /// sweep serves every armed deadline.
 fn sweepDeadlines() void {
    const now = system.clock();
    for (&drivers) |*driver| {
        if (!driver.used) continue;
        switch (driver.state) {
            .awaiting_hello => if (now >= driver.hello_deadline_ns) {
                writeLine("device-manager: {s} missed its hello deadline\n", .{driver.name()});
                _ = system.kill(driver.process_id);
                // The exit notification finishes the job via onDriverExit.
            },
            .restarting => if (now >= driver.restart_due_ns) spawnDriver(driver),
            else => {},
        }
    }
 }
 // --- the harness callbacks -----------------------------------------------------
 fn initialise(endpoint: runtime.ipc.Handle) bool {
    manager_endpoint = endpoint;
    // Enumerate into a heap buffer (too big for the one-page user stack).
    const buffer = runtime.allocator().alloc(device.DeviceDescriptor, 64) catch {
        _ = runtime.system.write("device-manager: out of memory\n");
-        return;
+        return false;
    };
    const total = device.enumerate(buffer);
    const count = @min(total, buffer.len);
@@ -85,28 +232,74 @@ pub fn main() void {
    for (buffer[0..count]) |descriptor| {
        if (pciDriverFor(descriptor)) |driver_name| {
            matched += 1;
-            spawnForDevice(driver_name, descriptor.id);
+            addDriver(driver_name, descriptor.id, true);
            continue;
        }
        const driver_name = driverFor(descriptor) orelse continue;
        matched += 1;
-        if (!system.isProcessRunning(driver_name)) {
+        // Skip a singleton that is already alive (the initial-ramdisk sweep test
-            if (runtime.system.spawn(driver_name) != null) {
+        // starts every bundled binary bare, this manager included) — spawning a
-                writeLine("device-manager: spawned {s}\n", .{driver_name});
+        // second instance would only lose the claim race and churn the log.
-            } else {
+        if (!alreadySupervised(driver_name) and !system.isProcessRunning(driver_name)) {
-                writeLine("device-manager: failed to spawn {s}\n", .{driver_name});
+            addDriver(driver_name, protocol.no_device, false);
        }
        } else {
            writeLine("device-manager: already spawned {s}\n", .{driver_name});
    }
    if (test_restart_mode) {
        // The driver-restart scenario's fixture: claims device 0 (the tree
        // root, otherwise unclaimed), hellos, then faults — driving backoff,
        // re-claim-after-death, and the crash-loop cap deterministically.
        addDriver("crash-test", 0, true);
    }
    if (matched == 0) {
        _ = runtime.system.write("device-manager: no matchable devices\n");
    } else {
        _ = runtime.system.write("device-manager: ok\n");
    }
    return true;
 }
 fn onMessage(message: []const u8, reply: []u8, sender: u32) usize {
    if (message.len < protocol.hello_size) return 0;
    const hello = std.mem.bytesToValue(protocol.Hello, message[0..protocol.hello_size]);
    if (hello.operation != @intFromEnum(protocol.Operation.hello)) return 0;
    var status: i32 = 0;
    if (hello.version != protocol.version) {
        status = -1;
        writeLine("device-manager: refused hello (version {d}) from process {d}\n", .{ hello.version, sender });
    } else if (driverByProcess(sender)) |driver| {
        driver.state = .running;
        writeLine("device-manager: hello from {s} (device {d})\n", .{ driver.name(), hello.device_id });
    } else {
        status = -1;
        writeLine("device-manager: hello from unknown process {d}\n", .{sender});
    }
    const hello_reply = protocol.HelloReply{ .status = status };
    @memcpy(reply[0..protocol.reply_size], std.mem.asBytes(&hello_reply));
    return protocol.reply_size;
 }
 fn onNotification(badge: u64) void {
    if (badge & runtime.ipc.notify_exit_bit != 0) {
        const dead: u32 = @intCast(badge & ~(runtime.ipc.notify_badge_bit | runtime.ipc.notify_exit_bit));
        if (driverByProcess(dead)) |driver| onDriverExit(driver);
        return;
    }
-    _ = runtime.system.write("device-manager: ok\n");
+    if (badge & runtime.ipc.notify_timer_bit != 0) sweepDeadlines();
-    while (true) runtime.system.sleep(1000);
+}
 pub fn main(init: runtime.process.Init) void {
    if (init.arguments.get(1)) |mode| {
        test_restart_mode = std.mem.eql(u8, mode, "test-restart");
    }
    runtime.service.run(protocol.message_maximum, .{
        .service = .device_manager,
        .init = initialise,
        .on_message = onMessage,
        .on_notification = onNotification,
    });
 }
 pub const panic = runtime.panic;
@@ -48,11 +48,91 @@ fn awaitChildExit(endpoint: runtime.ipc.Handle) u32 {
    return received.childProcessId();
 }
 /// The harness-run child of the signals test: echoes requests, logs the two
 /// signals it handles. Terminate makes run() return, and returning from main is
 /// the clean exit the parent reads as ExitReason.exited.
 fn echo(message: []const u8, reply: []u8, sender: u32) usize {
    _ = sender;
    const n = @min(message.len, reply.len);
    @memcpy(reply[0..n], message[0..n]);
    return n;
 }
 fn onReload() void {
    _ = runtime.system.write("process-test: reloaded\n");
 }
 fn onTerminate() void {
    _ = runtime.system.write("process-test: terminating\n");
 }
 /// The parent of the signals test: drives ping, echo, reload, the one-shot
 /// timer, and both endings of the stop sequence (polite -> exited; deaf ->
 /// killed at the deadline). Prints "process-test: signals ok" as the marker.
 fn signalRun() void {
    const endpoint = runtime.ipc.createIpcEndpoint() orelse fail("create exit endpoint");
    const child = runtime.system.spawnSupervised("process-test", &.{"service"}, endpoint) orelse fail("spawn service child");
    // Reach the child's endpoint through the registry (retry: it may not be up).
    var service_handle: ?runtime.ipc.Handle = null;
    var tries: u32 = 0;
    while (service_handle == null and tries < 200) : (tries += 1) {
        service_handle = runtime.ipc.lookup(.input);
        if (service_handle == null) runtime.system.sleep(20);
    }
    const h = service_handle orelse fail("service child never registered");
    // The universal ping: a zero-length call answered zero-length by the harness.
    var reply: [16]u8 = undefined;
    const pong = runtime.ipc.call(h, &.{}, &reply) catch fail("ping call failed");
    if (pong != 0) fail("ping reply not empty");
    // An ordinary request still reaches on_message.
    const n = runtime.ipc.call(h, "echo!", &reply) catch fail("echo call failed");
    if (n != 5 or !std.mem.eql(u8, reply[0..5], "echo!")) fail("echo mismatch");
    // reload: a statement — the child logs it; the kernel test reads the serial.
    if (!runtime.process.sendSignal(child, .reload)) fail("send reload");
    runtime.system.sleep(200);
    // The one-shot timer: armed on our endpoint, lands as isTimer.
    if (!runtime.system.timerOnce(endpoint, 100)) fail("arm timer");
    var scratch: [8]u8 = undefined;
    const landing = runtime.ipc.replyWait(endpoint, scratch[0..0], &scratch, null);
    if (!landing.isTimer()) fail("expected the timer landing");
    // The stop sequence, polite path: terminate, clean exit inside the deadline.
    runtime.process.stop(child, 2000, endpoint);
    if ((runtime.process.exitReason(child) orelse .killed) != .exited) fail("service child reason not exited");
    // The deaf child: binds nothing, hears nothing — the deadline kills it.
    const deaf = runtime.system.spawnSupervised("process-test", &.{"sleeper"}, endpoint) orelse fail("spawn deaf child");
    runtime.system.sleep(50); // let it reach its sleep
    runtime.process.stop(deaf, 300, endpoint);
    if ((runtime.process.exitReason(deaf) orelse .exited) != .killed) fail("deaf child reason not killed");
    _ = runtime.system.write("process-test: signals ok\n");
 }
 pub fn main(init: runtime.process.Init) void {
    const role = init.arguments.get(1) orelse return; // spawned bare (ramdisk sweep): stay silent
    if (std.mem.eql(u8, role, "sleeper")) {
        while (true) runtime.system.sleep(500);
    }
    if (std.mem.eql(u8, role, "service")) {
        // Borrowed well-known id: the input service is not part of this scenario.
        runtime.service.run(64, .{
            .service = .input,
            .on_message = echo,
            .on_reload = onReload,
            .on_terminate = onTerminate,
        });
        return; // terminate arrived; returning is the clean exit
    }
    if (std.mem.eql(u8, role, "signal-run")) {
        signalRun();
        return;
    }
    if (std.mem.eql(u8, role, "spinner")) {
        var beat: u64 = 0;
        const touch: *volatile u64 = &beat;
@@ -89,6 +169,12 @@ pub fn main(init: runtime.process.Init) void {
    if (listed(sleeper, "process-test")) fail("sleeper still listed after kill");
    if (listed(spinner, "process-test")) fail("spinner still listed after kill");
    // M17.2: both children were killed by us, and the reason says so — the whole
    // restart-policy input, read through the runtime like a real supervisor would.
    if ((runtime.process.exitReason(sleeper) orelse .exited) != .killed) fail("sleeper reason not killed");
    if ((runtime.process.exitReason(spinner) orelse .exited) != .killed) fail("spinner reason not killed");
    if (runtime.process.exitReason(0xFFFF_FFF0) != null) fail("unknown id had a reason");
    _ = runtime.system.write("process-test: ok\n");
 }
@@ -6,10 +6,30 @@
 const std = @import("std");
 const runtime = @import("runtime");
-pub fn main() void {
+pub fn main(init: runtime.process.Init) void {
    const u = @import("posix").unistd;
    const payload = "hello-vfs";
    // The "park" role (the vfs-client-death test): open a file, then hold the
    // handle forever without closing — the kill and the VFS's release-on-death
    // are the point.
    if (init.arguments.count > 1) {
        var fd: i32 = -1;
        var tries: u32 = 0;
        while (fd < 0 and tries < 200) : (tries += 1) {
            fd = u.open("parked", u.O_CREAT);
            if (fd < 0) runtime.system.sleep(20);
        }
        if (fd < 0) {
            _ = runtime.system.write("vfstest: park open failed\n");
            return;
        }
        while (true) {
            _ = runtime.system.write("vfstest: parked\n");
            runtime.system.sleep(500);
        }
    }
    // The VFS server may not have registered yet — retry open until it's up.
    var fd: i32 = -1;
    var tries: u32 = 0;
@@ -23,6 +23,10 @@ const Node = struct {
 const OpenFile = struct {
    used: bool = false,
    node: usize = 0,
    // The client (task id — an IPC badge is one) that opened this handle. What
    // release-on-death sweeps by: a service must never depend on its clients
    // cleaning up after themselves (docs/process-lifecycle.md).
    owner: u32 = 0,
 };
 var nodes = [_]Node{.{}} ** 8;
@@ -65,8 +69,29 @@ fn fail(out: []u8) usize {
    return writeReply(out, .{ .status = -1 }, &.{});
 }
-/// Handle one request; write the reply into `out`, return its length.
+/// Format one whole log line and emit it in a single `debug_write`, so lines from
-fn handle(message: []const u8, out: []u8) usize {
+/// concurrent processes can never land in the middle of it.
 fn writeLine(comptime fmt: []const u8, arguments: anytype) void {
    var line: [96]u8 = undefined;
    _ = runtime.system.write(std.fmt.bufPrint(&line, fmt, arguments) catch return);
 }
 /// Release every open handle `client` held — called on that client's published
 /// exit event. The nodes (the files) stay: ramfs contents outlive their writers,
 /// only the dead client's handles go.
 fn releaseClientHandles(client: u32) void {
    var released: u32 = 0;
    for (&opens) |*o| {
        if (o.used and o.owner == client) {
            o.used = false;
            released += 1;
        }
    }
    if (released != 0) writeLine("vfs: released {d} handle(s) for dead client {d}\n", .{ released, client });
 }
 /// Handle one request from `sender`; write the reply into `out`, return its length.
 fn handle(message: []const u8, out: []u8, sender: u32) usize {
    if (message.len < protocol.request_size) return fail(out);
    const request = std.mem.bytesToValue(protocol.Request, message[0..protocol.request_size]);
    const payload = message[protocol.request_size..];
@@ -77,7 +102,7 @@ fn handle(message: []const u8, out: []u8) usize {
            const ni = findNode(name) orelse createNode(name) orelse return fail(out);
            for (&opens, 0..) |*o, i| {
                if (!o.used) {
-                    o.* = .{ .used = true, .node = ni };
+                    o.* = .{ .used = true, .node = ni, .owner = sender };
                    return writeReply(out, .{ .status = 0, .node = i }, &.{});
                }
            }
@@ -113,27 +138,36 @@ fn handle(message: []const u8, out: []u8) usize {
    }
 }
-pub fn main() void {
+/// Startup, under the harness: subscribe to the published exit events — when a
-    const endpoint = runtime.ipc.createIpcEndpoint() orelse {
+/// client dies holding open handles, the exit notification is how the VFS learns
-        _ = runtime.system.write("vfs: no endpoint\n");
+/// to release them (docs/process-lifecycle.md).
-        return;
+fn initialise(endpoint: runtime.ipc.Handle) bool {
-    };
+    if (!runtime.process.subscribeExits(endpoint)) {
-    if (!runtime.ipc.register(.vfs, endpoint)) {
+        _ = runtime.system.write("vfs: exit subscription failed\n");
        _ = runtime.system.write("vfs: register failed\n");
        return;
    }
    _ = runtime.system.write("vfs: ready\n");
    return true;
 }
-    var reply_buffer: [protocol.message_maximum]u8 = undefined;
+/// A non-signal notification: the only kind the VFS subscribes to is exit events.
-    var reply_len: usize = 0;
+fn onNotification(badge: u64) void {
-    var receive: [protocol.message_maximum]u8 = undefined;
+    if (badge & runtime.ipc.notify_exit_bit != 0) {
-    while (true) {
+        releaseClientHandles(@intCast(badge & ~(runtime.ipc.notify_badge_bit | runtime.ipc.notify_exit_bit)));
        const got = runtime.ipc.replyWait(endpoint, reply_buffer[0..reply_len], &receive, null);
        // Ignore notifications (none expected here); handle a request.
        reply_len = handle(receive[0..got.len], &reply_buffer);
    }
 }
 pub fn main() void {
    // The harness owns the loop: requests dispatch to handle(), exit events to
    // onNotification(), ping and terminate are answered for free — this service
    // gained the whole lifecycle contract by deleting its hand-rolled loop.
    runtime.service.run(protocol.message_maximum, .{
        .service = .vfs,
        .init = initialise,
        .on_message = handle,
        .on_notification = onNotification,
    });
 }
 pub const panic = runtime.panic;
 comptime {
    _ = &runtime.start._start;
@@ -240,6 +240,37 @@ CASES = [
     "smp":    4,
     "expect": r"DANOS-TEST-RESULT: PASS",
     "fail":   r"DANOS-TEST-RESULT: FAIL"},
    # M17.1: a dead process's device claims are released by the reap — kill a child
    # holding a claim, the device must be claimable again (process-lifecycle.md).
    {"name": "claim-release",
     "smp":    4,
     "expect": r"DANOS-TEST-RESULT: PASS",
     "fail":   r"DANOS-TEST-RESULT: FAIL"},
    # M17.3: published exit events — the VFS subscribes, a client dies holding an
    # open handle, and the VFS releases it (process-lifecycle.md "Who learns of a death").
    {"name": "vfs-client-death",
     "smp":    4,
     "expect": r"DANOS-TEST-RESULT: PASS",
     "fail":   r"DANOS-TEST-RESULT: FAIL"},
    # M17.4: signals over IPC — ping, reload, terminate (clean exit), the one-shot
    # timer, and the stop sequence's two endings, all driven from ring 3.
    {"name": "signals",
     "smp":    4,
     "expect": r"DANOS-TEST-RESULT: PASS",
     "fail":   r"DANOS-TEST-RESULT: FAIL"},
    # M18.1: the device manager's hello + restart policy — xHCI hellos clean and
    # stays; crash-test faults, is restarted with backoff (re-claiming its device
    # each time), and hits the crash-loop cap (docs/device-manager.md).
    {"name": "driver-restart",
     "smp":    4,
     "timeout": 90,
     "qemu_extra": ["-device", "qemu-xhci,id=xhci",
                    "-device", "usb-kbd,bus=xhci.0",
                    "-device", "usb-mouse,bus=xhci.0"],
     "expect": r"usb-xhci-bus: hello acknowledged[\s\S]*"
               r"device-manager: restarting crash-test[\s\S]*"
               r"device-manager: crash-test is failing repeatedly",
     "fail":   r"DANOS-TEST-RESULT: FAIL"},
    # The initial_ramdisk: the loader ferries a bundle of user binaries; the kernel parses
    # it and spawns each as a ring-3 process (here the VFS-server stub heartbeats).
    {"name": "initial-ramdisk",
Author	SHA1	Message	Date
Daniel Samson	3cc1d38dd0	The device manager supervises: hello, backoff, and the crash-loop cap (M18.1) The manager is now a harness service on the well-known .device_manager endpoint. Every driver spawns supervised; drivers with an assignment must hello (device-manager-protocol, versioned) within a deadline enforced by a timer sweep. Exit reasons drive the restart decision: clean exits stay down, faults restart with 300/600/1200ms backoff, and three fast deaths mark a driver failed instead of respawning forever. usb-xhci-bus is the first conforming driver; the crash-test fixture claims a device, hellos, and faults on purpose — each respawn re-proving claim release on death through the manager's own path. maximum_tasks grows 16 -> 32: the initial-ramdisk sweep (15 binaries at once) was intermittently overflowing the static pool.	2026-07-13 00:19:30 +01:00
Daniel Samson	36e804b848	Mark the feat/process-lifecycle merge done in the M17-M18 plan	2026-07-12 23:53:50 +01:00
Daniel Samson	be83a42d42	Merge feat/process-lifecycle: the process lifecycle (M17.1-M17.4) Claim release on death, exit reasons, published exit events with the VFS as first subscriber, signals over IPC with one-shot timers and the service harness — docs/process-lifecycle.md increments 1-4, all built.	2026-07-12 23:53:50 +01:00
Daniel Samson	650a1b1595	Signals over IPC, one-shot timers, and the service harness (M17.4) Signals are statements delivered as coalescing notifications to the endpoint a process nominates with signal_bind — never a hijacked stack, never a question (liveness is the zero-length ping the harness answers). process_signal is supervisor-or-self gated, like kill; unbound targets accumulate a pending mask delivered on bind. timer_bind is the missing timed wait: a one-shot deadline landing in the same replyWait as everything else — what stop(), hello deadlines, and restart backoff are built from. runtime.service.run folds requests, signals, and notifications into callbacks; the VFS conversion deletes its hand-rolled loop and gains the whole lifecycle contract. The signals scenario drives ping, reload, terminate->exited, the timer, and the deaf-child deadline->killed path from ring 3. docs/process-lifecycle.md increments 1-4 are now as-built.	2026-07-12 23:53:38 +01:00
Daniel Samson	d8c55c6f2f	Publish exit events to subscribers; the VFS releases dead clients' handles (M17.3) process_subscribe adds an endpoint to a bounded, ref-counted subscriber table; every death posts the same badge encoding a supervisor's exit notification uses, equally late, so subscribers observe a fully-released child. A dying subscriber's own subscriptions are removed first — it never hears about itself. The VFS is the first subscriber: open handles now record their owner and are swept when the owner dies, because a service must never depend on clients cleaning up after themselves (docs/process-lifecycle.md). Proven by the vfs-client-death scenario.	2026-07-12 23:41:44 +01:00
Daniel Samson	2ebfb0c3b0	Record and expose how every process ends (M17.2) The kernel records an ExitReason at all three death sites — clean exit, fault (classified by vector), and process_kill — into a bounded ring before the exit notification posts, so a supervisor's query never races the notice. process_exit_reason is gated by the same supervisor check as kill; runtime.process.exitReason is the stable interface. This is the input restart policy reads (docs/process-lifecycle.md iron rule 2).	2026-07-12 23:34:09 +01:00
Daniel Samson	888eaa74e1	Release a dead process's device claims (M17.1) Every path out of a process (exit, fault, kill) now releases its device claims alongside its IRQ and MSI bindings, so a restarted driver can claim its hardware again — the cleanup half of process-lifecycle.md's iron rule 1. MSI vectors were already swept by irq.releaseOwner; claims were the gap. The claim-release test proves kill -> release -> re-claim, plus the broker release in isolation.	2026-07-12 23:23:49 +01:00
Daniel Samson	ed76cbbc79	Mark Phase 0 done: baseline QEMU suite green (48/48)	2026-07-12 23:17:20 +01:00
Daniel Samson	140229b88d	Rename usb-xhci-libary.zig to usb-xhci-library.zig (naming typo)	2026-07-12 23:13:33 +01:00
Daniel Samson	cb2379fd06	Update README.md	2026-07-12 23:12:39 +01:00
Daniel Samson	1665b239b0	Add the status checklist and workflow to the M17-M18 plan	2026-07-12 23:04:43 +01:00
Daniel Samson	70ed0337f8	Merge feat/usb: USB wire ABI, xHCI detection and spawn, M17-M18 design	2026-07-12 22:56:35 +01:00
Daniel Samson	116b8f6c41	Design the process lifecycle and the device manager (M17-M18) Signals over IPC (POSIX concepts, message delivery), published exit events, the stable runtime.process interface, and the device manager as tree + matcher + supervisor. All open questions settled; docs/m17-m18-plan.md is the phase-by-phase execution plan.	2026-07-12 22:56:34 +01:00