fix: detect cgroup v2 misconfiguration during onboard preflight

[brianwtaylor]

Summary

Adds a preflight check to nemoclaw onboard (step [1/7]) that detects the cgroup v2 / Docker cgroupns misconfiguration before gateway startup, instead of letting it fail late with a cryptic kubelet error.

• New module bin/lib/preflight.js with isCgroupV2() and checkCgroupConfig() detection
• Wired into the existing preflight step in bin/lib/onboard.js between Docker/OpenShell checks and GPU detection
• On failure: prints the exact error users will see, and points them to nemoclaw setup-spark (which does a safe JSON merge of daemon.json, preserving existing settings)
• 13 new unit tests in test/preflight.test.js covering all branches

Closes #16

Hardware verification

Tested on two NVIDIA DGX Spark units (aarch64, Ubuntu 24.04.4 LTS, Docker 28.x, cgroup v2):

Machine	cgroup	daemon.json	Detection result	Expected
spark0	cgroup2fs	missing	{ok: false, reason: "...does not exist..."}	Correct
spark1	cgroup2fs	missing	cgroup2fs confirmed, no daemon.json	Correct
spark0 (simulated fix)	cgroup2fs	{"default-cgroupns-mode": "host"}	{ok: true}	Correct

Both machines are in the exact broken state described in #16. The check catches it and exits with actionable guidance before the gateway ever starts.

Test plan

Automated Tests

node --test test/preflight.test.js
node --test test/*.test.js

Manual verification

1. On a cgroup v2 host without daemon.json: nemoclaw onboard should fail at step [1/7] with the cgroup error
2. After running nemoclaw setup-spark: nemoclaw onboard should pass the cgroup check
3. On a cgroup v1 host or macOS: check is silently skipped (returns {ok: true})

[ericksoa]

LGTM. Clean implementation — detection logic is well-separated in preflight.js with dependency injection for testability, error message is actionable (points to nemoclaw setup-spark), and 13 unit tests cover all branches.

Verified: code reads one file (/etc/docker/daemon.json) and runs one safe command (stat -fc %T /sys/fs/cgroup). No shell injection surface, no network calls. macOS/cgroup v1 silently passes.

Hardware verification by the author on two DGX Spark units covers the real detection path that can't be exercised in Docker CI.

[derekhsu]

Code Review — PR #62 (post-merge)

Reviewed the merged diff (fc31ae8): new bin/lib/preflight.js + wiring in bin/lib/onboard.js + test/preflight.test.js. This is a retrospective review, so issues are framed as potential follow-ups rather than merge blockers.

Strengths

• Clear, actionable failure path. The error printed in onboard.js shows the exact kubelet error users hit (openat2 /sys/fs/cgroup/kubepods/pids.max) and points straight to nemoclaw setup-spark. This directly addresses the "fails late with a cryptic error" problem from Detect and remediate the cgroup v2 / "Kubernetes namespace not ready" onboarding blocker on Ubuntu 24.04 #16.
• Testable design. checkCgroupConfig(opts) injects both cgroupV2 and daemonPath, so the unit tests exercise real file I/O against temp daemon.json files instead of mocks. All branches are covered (v1 skip, v2+host, missing file, missing key, wrong value "private", invalid JSON, extra keys).
• Correct platform guard. isCgroupV2() short-circuits to false on non-Linux before ever invoking stat, so macOS never depends on command failure as a fallback.
• Safe parse. readDaemonJson() swallows both missing-file and parse errors, so a malformed daemon.json can't crash onboarding.

Issues

Important (Should Fix — follow-up)

1. stat -fc %T is fragile across coreutils implementations — bin/lib/preflight.js isCgroupV2()

   • stat -fc %T /sys/fs/cgroup relies on GNU coreutils emitting the literal cgroup2fs. uutils/Rust coreutils (shipping on some minimal/Ubuntu images) can emit UNKNOWN (0x63677270) instead, which makes isCgroupV2() return false and silently skips the check — so the user still hits the late kubelet failure this PR was meant to prevent.
   • Fix: fall back to a filesystem signal that doesn't depend on stat output formatting, e.g. existence of /sys/fs/cgroup/cgroup.controllers (cgroup v2-only) or parsing /proc/mounts.

2. Detection only inspects daemon.json → false-positive process.exit(1) — bin/lib/preflight.js checkCgroupConfig()

   • default-cgroupns-mode=host can also be set via a dockerd CLI flag or a systemd drop-in (/etc/systemd/system/docker.service.d/*.conf). A host correctly configured that way still has no (or a different) daemon.json, so the check fails and onboard.js calls process.exit(1), hard-blocking a working setup.
   • Fix: before failing, also consult the live daemon (docker info's cgroup/cgroupns fields) or the effective ExecStart from systemctl show docker.

Minor (Nice to Have)

3. reason conflates "missing file" with "invalid JSON" — bin/lib/preflight.js

   • readDaemonJson() returns null for both cases, so the reason text is always "…does not exist or is not valid JSON". A user with a typo'd daemon.json is told it "does not exist," which misleads debugging. Consider returning a small struct ({ exists, parsed }) so the message can distinguish the two. (The test only asserts substring "not valid JSON", which happens to be present in the combined message, so this gap isn't caught.)

4. No non-interactive short-circuit — bin/lib/onboard.js

   • The multi-line guidance is fine for a TTY but is noisy in CI/non-interactive runs where the user can't act on it. A shorter message in non-interactive mode would be cleaner. (Minor.)

Important context for maintainers (not a defect in this PR)

This preflight no longer exists in main in its merged form. It was reimplemented in TypeScript at src/lib/onboard/preflight.ts, and the enforcement is now deliberately disabled: requiresHostCgroupnsFix: false is hardcoded with the comment "Current OpenShell sets host cgroupns on its own cluster container." (preflight.ts:584-585). So the cgroup data is still collected but never blocks onboarding. If that comment is accurate, issues #1/#2 above are moot going forward; if OpenShell's behavior regresses, the same portability/false-positive concerns will resurface in the TS version. Worth confirming the disable was intentional and documenting why.

Assessment

Ready to merge? Already merged — would have been With fixes. The core implementation is clean, well-tested, and solves the stated problem; the two Important items (coreutils portability and daemon.json-only detection) are the parts most likely to cause real-world false negatives/positives and are the best follow-up candidates.

_{🤖 Review generated with Devin}