feat(lucebox): hub CLI + autotune/sweep/profile + harness adapters + shell wrapper

[easel]

Summary

Adds the lucebox hub CLI (autotune, sweep, profile, smoke, models, config, download, host-check, docker_run) plus the lucebox.sh wrapper and install.sh bootstrap. Also lands the harness/ adapter package (claude_code, codex, hermes, openclaw, opencode, pi) and the run_lucebench.sh shim that lucebox bench-style flows shell out to. Additive only — no existing source files modified outside CI workflow edits, README touch-ups, and a lefthook.yml for the new packages.

Files

• lucebox/ — new Python package: CLI entrypoint, autotune/sweep/profile/smoke/config/download/host-check/docker_run modules, full pytest suite under lucebox/tests/.
• harness/ — new Python package: harness.bench + per-agent client adapters (claude_code.py, codex.py, hermes.py, openclaw.py, opencode.py, pi.py) and the run_lucebench.sh operator shim.
• lucebox.sh + install.sh — top-level shell wrapper and bootstrap installer.
• scripts/check_lucebox_wrapper_sandbox.sh, scripts/test_lucebox_sh.sh — wrapper-shape integration tests.
• .github/workflows/ci.yml — wires the new packages into CI.
• harness/clients/README.md, lefthook.yml — supporting docs/config.

Single commit, ~10.5k LOC added across 49 files.

Dependencies

• build(docker): lucebox-hub container image + CI release pipeline #334 (docker-stack) — lucebox.docker_run shells out to docker run against the lucebox-hub image and reads the IMAGE_INFO produced by the docker build. The CLI cannot exercise a real run path until docker-stack lands.
• feat(luce-bench): in-tree bench harness + multi-turn agent_recorded + LLM judge #337 (luce-bench) — harness/bench.py invokes python -m lucebench.cli ... as a subprocess; harness/clients/run_lucebench.sh is the operator shim around the same package. Both require the lucebench package to be importable.
• refactor(server): shared layer-split backend + GGUF inspection + c2-gate plumbing #336 (server-layer-split) — autotune candidate configs assume the layer-split build flags surfaced by the server build artifacts; without refactor(server): shared layer-split backend + GGUF inspection + c2-gate plumbing #336 the configs reduce to no-ops on real hardware.

Unit tests in lucebox/tests/ and harness/ mock the external surfaces and pass standalone, but end-to-end validation requires the three siblings above.

Test plan

• cd lucebox && uv run pytest (standalone — mocks docker/lucebench surfaces)
• cd harness && uv run pytest (standalone)
• ./lucebox.sh --help resolves once build(docker): lucebox-hub container image + CI release pipeline #334 lands and the image is available
• lucebox host-check reports GPU + driver facts on a fresh host
• lucebox autotune --dry-run enumerates candidate configs without launching a sweep
• End-to-end lucebox bench-style flow once feat(luce-bench): in-tree bench harness + multi-turn agent_recorded + LLM judge #337 (luce-bench) is mergeable and refactor(server): shared layer-split backend + GGUF inspection + c2-gate plumbing #336 (server layer-split) is exposing the expected build flags

Note: this PR's CLI/adapter code is self-contained and unit-tests pass standalone, but full integration validation requires the docker, luce-bench, and server-layer-split siblings to land together.

Generated with Claude Code

[cubic-dev-ai]

29 issues found across 52 files

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>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P3: Several newly added helper functions are dead code (defined but never called anywhere in the codebase).

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At lucebox/src/lucebox/docker_run.py, line 231:

<comment>Several newly added helper functions are dead code (defined but never called anywhere in the codebase).</comment>

<file context>
@@ -0,0 +1,270 @@
+# ── subprocess helpers ─────────────────────────────────────────────────────
+
+
+def run(argv: list[str], *, check: bool = True) -> subprocess.CompletedProcess[str]:
+    """Run a command, streaming stdout/stderr to the user. `check=False` to
+    inspect exit codes manually."""
</file context>

[easel]

Fixed in 73f04f4: removed the unused run(), docker_inspect_running(), host_path_visible(), and stderr() helpers from docker_run.py, plus the now-unused sys import.

[cubic-dev-ai]

Thanks for the update!

[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]

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.sh">

<violation number="1" location="lucebox.sh:696">
P2: The `SuccessExitStatus=143 SIGTERM` directive in the generated systemd unit treats ALL exits with code 143 as successful, which means `Restart=on-failure` will not restart the service after unexpected terminations like an external `docker stop` or daemon-initiated container SIGTERM. These scenarios produce the same 143 exit code as an intentional `systemctl stop` but should trigger a restart. A better approach would be to make `_serve_and_track` distinguish intentional signal-driven stops (e.g., by tracking when the trap fires and returning 0 instead of 143 on clean shutdown) so that `SuccessExitStatus=143` can be removed and only genuine unexpected failures trigger a restart.</violation>
</file>

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

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: The SuccessExitStatus=143 SIGTERM directive in the generated systemd unit treats ALL exits with code 143 as successful, which means Restart=on-failure will not restart the service after unexpected terminations like an external docker stop or daemon-initiated container SIGTERM. These scenarios produce the same 143 exit code as an intentional systemctl stop but should trigger a restart. A better approach would be to make _serve_and_track distinguish intentional signal-driven stops (e.g., by tracking when the trap fires and returning 0 instead of 143 on clean shutdown) so that SuccessExitStatus=143 can be removed and only genuine unexpected failures trigger a restart.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At lucebox.sh, line 696:

<comment>The `SuccessExitStatus=143 SIGTERM` directive in the generated systemd unit treats ALL exits with code 143 as successful, which means `Restart=on-failure` will not restart the service after unexpected terminations like an external `docker stop` or daemon-initiated container SIGTERM. These scenarios produce the same 143 exit code as an intentional `systemctl stop` but should trigger a restart. A better approach would be to make `_serve_and_track` distinguish intentional signal-driven stops (e.g., by tracking when the trap fires and returning 0 instead of 143 on clean shutdown) so that `SuccessExitStatus=143` can be removed and only genuine unexpected failures trigger a restart.</comment>

<file context>
@@ -690,6 +690,10 @@ Wants=network-online.target docker.service
+# \`serve\` traps SIGTERM, stops the container, and exits 143 (128+SIGTERM).
+# Without this, a normal \`systemctl stop\` leaves the unit "failed" instead of
+# "inactive". Genuine crashes exit with other codes and still trip Restart.
+SuccessExitStatus=143 SIGTERM
 Environment=PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
 Environment=LUCEBOX_IMAGE=$IMAGE_BASE
</file context>

[cubic-dev-ai]

1 issue found across 3 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/config.py">

<violation number="1" location="lucebox/src/lucebox/config.py:355">
P2: The `seed_dflash_from_host` function can accidentally block legacy `.env` migration. Because it calls `load_doc()` directly—which returns `{}` for a missing file and never checks for a legacy `.env`—it may create a brand-new `config.toml` containing only the heuristic dflash keys. Once that `config.toml` exists, the standard `load()` path will skip migration forever, silently dropping any legacy overrides (port, image, models_dir, prior DFLASH values, etc.). The current CLI call site happens to call `_load_or_build()` first, but the function is a standalone public API and this is a latent data-loss hazard for any future caller or refactor. Consider running the legacy migration check inside `seed_dflash_from_host` before calling `load_doc()`, or calling `load(path)` upfront to ensure any legacy `.env` is promoted first.</violation>
</file>

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

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: The seed_dflash_from_host function can accidentally block legacy .env migration. Because it calls load_doc() directly—which returns {} for a missing file and never checks for a legacy .env—it may create a brand-new config.toml containing only the heuristic dflash keys. Once that config.toml exists, the standard load() path will skip migration forever, silently dropping any legacy overrides (port, image, models_dir, prior DFLASH values, etc.). The current CLI call site happens to call _load_or_build() first, but the function is a standalone public API and this is a latent data-loss hazard for any future caller or refactor. Consider running the legacy migration check inside seed_dflash_from_host before calling load_doc(), or calling load(path) upfront to ensure any legacy .env is promoted first.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At lucebox/src/lucebox/config.py, line 355:

<comment>The `seed_dflash_from_host` function can accidentally block legacy `.env` migration. Because it calls `load_doc()` directly—which returns `{}` for a missing file and never checks for a legacy `.env`—it may create a brand-new `config.toml` containing only the heuristic dflash keys. Once that `config.toml` exists, the standard `load()` path will skip migration forever, silently dropping any legacy overrides (port, image, models_dir, prior DFLASH values, etc.). The current CLI call site happens to call `_load_or_build()` first, but the function is a standalone public API and this is a latent data-loss hazard for any future caller or refactor. Consider running the legacy migration check inside `seed_dflash_from_host` before calling `load_doc()`, or calling `load(path)` upfront to ensure any legacy `.env` is promoted first.</comment>

<file context>
@@ -334,6 +335,39 @@ def save(cfg: Config, path: Path | None = None, *, doc: dict[str, Any] | None =
+    import lucebox.autotune as autotune_mod
+
+    path = path or default_config_path()
+    doc = load_doc(path)
+    if "dflash" in doc:
+        return False
</file context>