---
name: boot-race-self-heal
description: v0.3.1 daemon self-heals a net-less boot start (NetHost retry+attach); systemd-user network-online ordering does NOT reliably prevent the race under linger — the self-heal is the real guarantee
metadata: 
  node_type: memory
  type: project
  originSessionId: 183adaa7-7665-46dd-bb77-a1c8691f9f3c
---

The daemon can autostart at boot (linger) BEFORE the network/DNS stack is ready → `NetHost::start` fails (`Failed to create an address lookup service`) → net-less broker. Pre-v0.3.1 the peer pump was gated on `net_up` at boot, so it never spawned → node silently unreachable until a manual restart (kitsubito 2026-06-08 reboot).

**Fix (v0.3.1, REQ-DAEMON-9):** `Broker.net` is a `OnceLock<NetHost>` with `attach_net()`; `Daemon::run` slow-path spawns a background supervisor that retries `NetHost::start` (capped 30s backoff) and attaches + spawns the pump once net comes up. `cmd_daemon_status` renders a net-less broker as "no connection (retrying)" instead of a STALLED alarm off a stale pre-boot heartbeat.

**Field-proven (kitsubito reboot 2026-06-09):** journal showed `NET_BIND_FAIL` then `NET_ATTACHED` ~1s later → `peer pump: live`, no manual restart. **CRITICAL FINDING: the boot race STILL fired despite `After=network-online.target` in the unit** — systemd-USER network-online is unreliable under linger. So the unit ordering (installer) is belt-and-suspenders; the **daemon self-heal is the actual guarantee**. Don't rely on network-online ordering alone for a user-service daemon. Shipped v0.3.1 (commit c44e622). Related: [[kitsubito-linux-rig]], [[daemon-service-detection-gotcha]].