feat(lucebox): guided CLI for buyers and contributors

[easel]

Summary

Ship one simple inference CLI for both Lucebox buyers and open-source contributors.

Running lucebox opens the branded ASCII menu. Wi-Fi, Bluetooth, and device provisioning are intentionally outside this PR; this surface is focused on selecting, configuring, and running the inference engine.

Buyer flow

• lucebox setup guides backend/image selection, model selection, optimization, background-service installation, and start.
• lucebox models select shows a numbered catalog, downloads when needed, and activates factory-preloaded models without contacting Hugging Face.
• lucebox optimize explains the decision for DFlash, PFlash, KVFlash, and Spark before applying it.
  • Automatic is model-, primary-GPU-, VRAM-, host-RAM-, and installed-asset-aware.
  • Advanced lets the user override those four product choices while context, cache, and DDTree details remain safely tuned.
• Automatic profiles are replanned when the model changes; direct low-level edits become a preserved Custom profile.
• The menu exposes start, stop, status, logs, active model, backend, optimization mode, and engine state.

Safe optimization behavior

• DFlash is enabled only when a non-empty matching draft/speculator is installed.
• PFlash is automatic only for the validated Qwen3.6 dense long-context path and uses one shared Qwen3-0.6B BF16 scorer.
• KVFlash is enabled automatically only under real Qwen-family memory pressure; otherwise exact full-KV execution is preferred.
• Spark is enabled automatically only for supported MoE models under VRAM pressure and with at least 32 GB reported host RAM for cold experts.
• Automatic profiles leave KV dtype selection to each model family and do not reintroduce the quality-risky blanket tq3_0 fallback.
• Zero-byte model/scorer placeholders and incompatible KVFlash + FA-window settings are rejected.

Hardware behavior

• NVIDIA CUDA and AMD ROCm image/runtime selection.
• RTX 3090 + Strix defaults to CUDA; an explicit ROCm choice retunes against the AMD device facts.
• R9700 + Strix selects ROCm and pins the largest-VRAM AMD device with ROCR_VISIBLE_DEVICES.
• Strix-only ROCm remains supported.
• Automatic tuning uses one selected primary GPU and never sums VRAM across devices. Transparent multi-GPU layer sharding is not claimed by this release.

Contributor flow

The same ./lucebox.sh menu detects a source checkout and adds:

• lucebox build [cuda|rocm] — native dflash_server build for the selected accelerator.
• lucebox native [cuda|rocm] — run the selected model with the native engine.
• lucebox harness — Claude Code, Codex, OpenCode, Hermes, Pi, OpenClaw, and Open WebUI picker.
• Native and harness paths receive the same DFlash/PFlash/KVFlash/Spark profile as the buyer container path.

All menu actions keep scriptable equivalents for CI and expert workflows.

Package and installation

• install.sh installs the small host wrapper; buyer machines can receive the wrapper, image, models, and shared optimizer scorer preinstalled.
• The typed lucebox/ Python package remains the source of truth for TOML config, model downloads, optimization planning, and launch construction.
• The package builds as a wheel and source distribution with the lucebox console entry point.

Validation

• 166 Python tests on macOS and on Lucebox5.
• Ruff correctness checks and MyPy (11 typed source modules).
• ShellCheck, Bash syntax checks, and the 71-case wrapper/entrypoint/harness integration suite on Lucebox5.
• Final wheel + source distribution build; clean isolated wheel install and console-entry-point smoke.
• Lucebox5 hardware probe: R9700 gfx1201 + Strix gfx1151, ROCm 7.2.4, 125 GB RAM.
• Lucebox5 live offline/preload flow: activate Qwen3.6-27B, apply Automatic, persist DFlash + PFlash at 98,304 context, pin the R9700 by stable ROCm UUID, and render the final launch contract.
• All nine findings from Cubic's automated review were handled and regression-tested.
• GitHub CI and CUDA/ROCm image jobs for commit 12d1ab51 (running).

Lucebox5 currently has no Docker installation, so this validation covers real hardware detection, CLI/config behavior, and the ROCm launch contract, but not an end-to-end container inference request. Existing GitHub CUDA/ROCm build and GPU jobs provide the engine/image coverage.

Out of scope

• Wi-Fi/Bluetooth/Tailscale onboarding.
• Transparent automatic multi-GPU layer sharding.
• Benchmark sweeps that mutate a user's profile automatically.
• A separate GUI.

[cubic-dev-ai]

All reported issues were addressed across 52 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

1 issue found across 2 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="lucebox/src/lucebox/docker_run.py">

<violation number="1" location="lucebox/src/lucebox/docker_run.py:231">
P3: Several newly added helper functions are dead code (defined but never called anywhere in the codebase).</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

1 issue found across 37 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="lucebox/src/lucebox/docker_run.py">

<violation number="1" location="lucebox/src/lucebox/docker_run.py:231">
P3: Several newly added helper functions are dead code (defined but never called anywhere in the codebase).</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 10 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

2 issues found across 30 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="lucebox/tests/test_placement.py">

<violation number="1" location="lucebox/tests/test_placement.py:625">
P3: The test's stated purpose is to prove Python capabilities match the engine table, but the newly added prefix_slots column is captured only to keep the following draft column aligned and is never cross-checked. A drift between C++ default_prefix_cache_slots and Python prefix_cache_slots would go unnoticed. Consider asserting capability.prefix_cache_slots == int(row["prefix_slots"]) (mirroring how the other columns are validated) or, if the Python architecture table intentionally doesn't track this value, note that on the capability struct so the column doesn't get silently dropped.</violation>
</file>

<file name="server/test/test_entrypoint_cache_defaults.sh">

<violation number="1" location="server/test/test_entrypoint_cache_defaults.sh:90">
P3: The tailored failure message is effectively unreachable: on a regression the entrypoint aborts non-zero and this test's own `set -e` terminates before the grep executes, so the operator just sees a bare exit code instead of this diagnostic. Wrap the entrypoint invocation in an explicit `if ! ...; then cat "$gb10_stderr"; exit 1; fi` so the clear message is printed on failure, and optionally assert the serve actually completes.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P3: The test's stated purpose is to prove Python capabilities match the engine table, but the newly added prefix_slots column is captured only to keep the following draft column aligned and is never cross-checked. A drift between C++ default_prefix_cache_slots and Python prefix_cache_slots would go unnoticed. Consider asserting capability.prefix_cache_slots == int(row["prefix_slots"]) (mirroring how the other columns are validated) or, if the Python architecture table intentionally doesn't track this value, note that on the capability struct so the column doesn't get silently dropped.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At lucebox/tests/test_placement.py, line 625:

<comment>The test's stated purpose is to prove Python capabilities match the engine table, but the newly added prefix_slots column is captured only to keep the following draft column aligned and is never cross-checked. A drift between C++ default_prefix_cache_slots and Python prefix_cache_slots would go unnoticed. Consider asserting capability.prefix_cache_slots == int(row["prefix_slots"]) (mirroring how the other columns are validated) or, if the Python architecture table intentionally doesn't track this value, note that on the capability struct so the column doesn't get silently dropped.</comment>

<file context>
@@ -622,6 +622,7 @@ def test_python_architecture_capabilities_match_engine_table() -> None:
         r'\{"(?P<arch>[^\"]+)",\s*'
         r"(?P<split>true|false),\s*(?P<remote>true|false),\s*"
         r"(?P<pflash>true|false),\s*(?P<offload>true|false),\s*"
+        r"(?P<prefix_slots>[0-9]+),\s*"
         r"(?P<draft>kNever|kMono|kBoth),"
     )
</file context>

[cubic-dev-ai]

P3: The tailored failure message is effectively unreachable: on a regression the entrypoint aborts non-zero and this test's own set -e terminates before the grep executes, so the operator just sees a bare exit code instead of this diagnostic. Wrap the entrypoint invocation in an explicit if ! ...; then cat "$gb10_stderr"; exit 1; fi so the clear message is printed on failure, and optionally assert the serve actually completes.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At server/test/test_entrypoint_cache_defaults.sh, line 90:

<comment>The tailored failure message is effectively unreachable: on a regression the entrypoint aborts non-zero and this test's own `set -e` terminates before the grep executes, so the operator just sees a bare exit code instead of this diagnostic. Wrap the entrypoint invocation in an explicit `if ! ...; then cat "$gb10_stderr"; exit 1; fi` so the clear message is printed on failure, and optionally assert the serve actually completes.</comment>

<file context>
@@ -65,4 +65,32 @@ assert_arg_pair "$configured_output" --prefix-cache-slots 4
+    DFLASH_TARGET="$TARGET" \
+    DFLASH_DRAFT="$TMP_DIR/no-draft" \
+    DFLASH_SERVER_BIN="$FAKE_SERVER" \
+    bash "$ENTRYPOINT" serve >/dev/null 2>"$gb10_stderr"
+if grep -Fq "syntax error: operand expected" "$gb10_stderr"; then
+    echo "entrypoint attempted arithmetic on GB10 [N/A] memory" >&2
</file context>

[cubic-dev-ai]

1 issue found across 5 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="server/src/deepseek4/deepseek4_backend.cpp">

<violation number="1" location="server/src/deepseek4/deepseek4_backend.cpp:705">
P3: The predicate `draft_kind != target_kind || draft_gpu != cfg_.device.gpu` is now duplicated between this new qualification guard and the existing backend-creation branch a few lines below. The two copies can silently diverge (e.g. if the backend-creation condition grows another trigger such as `separate_draft_stream`), which could bypass the qualification. Consider hoisting the shared condition into a single named bool and reusing it in both places.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P3: The predicate draft_kind != target_kind || draft_gpu != cfg_.device.gpu is now duplicated between this new qualification guard and the existing backend-creation branch a few lines below. The two copies can silently diverge (e.g. if the backend-creation condition grows another trigger such as separate_draft_stream), which could bypass the qualification. Consider hoisting the shared condition into a single named bool and reusing it in both places.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At server/src/deepseek4/deepseek4_backend.cpp, line 705:

<comment>The predicate `draft_kind != target_kind || draft_gpu != cfg_.device.gpu` is now duplicated between this new qualification guard and the existing backend-creation branch a few lines below. The two copies can silently diverge (e.g. if the backend-creation condition grows another trigger such as `separate_draft_stream`), which could bypass the qualification. Consider hoisting the shared condition into a single named bool and reusing it in both places.</comment>

<file context>
@@ -699,6 +699,21 @@ bool DeepSeek4Backend::load_spec_drafter() {
+    // Startup qualification covers only the target GPU. DFLASH_DS4_DRAFT_GPU
+    // can select a different CUDA device, so qualify the resolved draft
+    // device before creating a backend on it.
+    if (draft_kind == PlacementBackend::Cuda &&
+        (draft_kind != target_kind || draft_gpu != cfg_.device.gpu)) {
+        int draft_sm = 0;
</file context>