Collect IOMMU group per PCIe device from sysfs

Reads the iommu_group symlink for each BDF and exposes the group number
as iommu_group in the hardware snapshot JSON.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

audit/cmd/bee/main.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"context"
+	"errors"
 	"flag"
 	"fmt"
 	"io"
@@ -67,6 +68,8 @@ func run(args []string, stdout, stderr io.Writer) (exitCode int) {
 		return runSupportBundle(args[1:], stdout, stderr)
 	case "web":
 		return runWeb(args[1:], stdout, stderr)
+	case "blackbox":
+		return runBlackbox(args[1:], stdout, stderr)
 	case "sat":
 		return runSAT(args[1:], stdout, stderr)
 	case "benchmark":
@@ -90,6 +93,7 @@ func printRootUsage(w io.Writer) {
   bee export  --target <device>
   bee support-bundle --output stdout|file:<path>
   bee web     --listen :80 [--audit-path `+app.DefaultAuditJSONPath+`]
+  bee blackbox --export-dir `+app.DefaultExportDir+` [--state-file `+app.DefaultBlackboxStatePath+`]
   bee sat nvidia|memory|storage|cpu [--duration <seconds>]
   bee benchmark nvidia [--profile standard|stability|overnight]
   bee bee-worker --export-dir `+app.DefaultExportDir+` --task-id TASK-001
@@ -109,6 +113,8 @@ func runHelp(args []string, stdout, stderr io.Writer) int {
 		return runSupportBundle([]string{"--help"}, stdout, stdout)
 	case "web":
 		return runWeb([]string{"--help"}, stdout, stdout)
+	case "blackbox":
+		return runBlackbox([]string{"--help"}, stdout, stdout)
 	case "sat":
 		return runSAT([]string{"--help"}, stdout, stderr)
 	case "benchmark":
@@ -340,6 +346,33 @@ func runWeb(args []string, stdout, stderr io.Writer) int {
 	return 0
 }
 
+func runBlackbox(args []string, stdout, stderr io.Writer) int {
+	fs := flag.NewFlagSet("blackbox", flag.ContinueOnError)
+	fs.SetOutput(stderr)
+	exportDir := fs.String("export-dir", app.DefaultExportDir, "directory with logs, SAT results, and support bundles")
+	statePath := fs.String("state-file", app.DefaultBlackboxStatePath, "blackbox state file")
+	fs.Usage = func() {
+		fmt.Fprintf(stderr, "usage: bee blackbox [--export-dir %s] [--state-file %s]\n", app.DefaultExportDir, app.DefaultBlackboxStatePath)
+		fs.PrintDefaults()
+	}
+	if err := fs.Parse(args); err != nil {
+		if err == flag.ErrHelp {
+			return 0
+		}
+		return 2
+	}
+	if fs.NArg() != 0 {
+		fs.Usage()
+		return 2
+	}
+	slog.Info("starting bee blackbox", "export_dir", *exportDir, "state_file", *statePath)
+	if err := app.RunBlackbox(context.Background(), *exportDir, *statePath, platform.New()); err != nil && !errors.Is(err, context.Canceled) {
+		slog.Error("run blackbox", "err", err)
+		return 1
+	}
+	return 0
+}
+
 func runSAT(args []string, stdout, stderr io.Writer) int {
 	if len(args) == 0 {
 		fmt.Fprintln(stderr, "usage: bee sat nvidia|memory|storage|cpu [--duration <seconds>]")

audit/internal/app/blackbox.go

@@ -0,0 +1,779 @@
+package app
+
+import (
+	"bytes"
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io/fs"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sort"
+	"strings"
+	"sync"
+	"time"
+
+	"bee/audit/internal/platform"
+)
+
+const (
+	blackboxMarkerName        = ".bee-blackbox"
+	blackboxDiscoverInterval  = 2 * time.Second
+	blackboxMinFlushPeriod    = 1 * time.Second
+	blackboxMaxFlushPeriod    = 30 * time.Second
+	blackboxRecoveryFastCount = 5
+)
+
+var DefaultBlackboxStatePath = DefaultExportDir + "/blackbox-state.json"
+
+var (
+	blackboxExecCommand = exec.Command
+	blackboxNow         = func() time.Time { return time.Now().UTC() }
+)
+
+type BlackboxMarker struct {
+	Version      int    `json:"version"`
+	EnrollmentID string `json:"enrollment_id"`
+	CreatedAtUTC string `json:"created_at_utc"`
+	Host         string `json:"host,omitempty"`
+}
+
+type BlackboxTargetStatus struct {
+	EnrollmentID      string                   `json:"enrollment_id"`
+	Device            string                   `json:"device"`
+	FS                platform.RemovableTarget `json:"fs"`
+	BootFolder        string                   `json:"boot_folder"`
+	Status            string                   `json:"status"`
+	LastSyncAtUTC     string                   `json:"last_sync_at_utc,omitempty"`
+	LastCycleDuration string                   `json:"last_cycle_duration,omitempty"`
+	FlushPeriod       string                   `json:"flush_period"`
+	LastError         string                   `json:"last_error,omitempty"`
+	Mountpoint        string                   `json:"mountpoint,omitempty"`
+}
+
+type BlackboxState struct {
+	Status           string                 `json:"status"`
+	BootStartedAtUTC string                 `json:"boot_started_at_utc"`
+	BootFolder       string                 `json:"boot_folder"`
+	UpdatedAtUTC     string                 `json:"updated_at_utc"`
+	Targets          []BlackboxTargetStatus `json:"targets"`
+}
+
+type blackboxRuntime struct {
+	exportDir   string
+	statePath   string
+	system      *platform.System
+	bootStarted time.Time
+	bootFolder  string
+
+	mu      sync.Mutex
+	workers map[string]*blackboxWorker
+}
+
+type discoveredBlackboxTarget struct {
+	marker       BlackboxMarker
+	target       platform.RemovableTarget
+	seenMount    string
+	mountedByBee bool
+}
+
+type blackboxWorker struct {
+	runtime      *blackboxRuntime
+	enrollmentID string
+
+	mu           sync.Mutex
+	target       platform.RemovableTarget
+	marker       BlackboxMarker
+	mountpoint   string
+	mountedByBee bool
+	status       string
+	lastSyncAt   time.Time
+	lastDuration time.Duration
+	flushPeriod  time.Duration
+	lastError    string
+	fastCycles   int
+	stopCh       chan struct{}
+	stoppedCh    chan struct{}
+}
+
+func RunBlackbox(ctx context.Context, exportDir, statePath string, system *platform.System) error {
+	exportDir = strings.TrimSpace(exportDir)
+	if exportDir == "" {
+		exportDir = DefaultExportDir
+	}
+	statePath = strings.TrimSpace(statePath)
+	if statePath == "" {
+		statePath = DefaultBlackboxStatePath
+	}
+	if system == nil {
+		system = platform.New()
+	}
+	bootStarted, err := bootStartedAtUTC()
+	if err != nil {
+		bootStarted = blackboxNow()
+	}
+	rt := &blackboxRuntime{
+		exportDir:   exportDir,
+		statePath:   statePath,
+		system:      system,
+		bootStarted: bootStarted,
+		bootFolder:  SupportBundleBaseName(bootStarted),
+		workers:     make(map[string]*blackboxWorker),
+	}
+	_ = os.MkdirAll(filepath.Dir(statePath), 0755)
+	rt.persistState()
+	ticker := time.NewTicker(blackboxDiscoverInterval)
+	defer ticker.Stop()
+	for {
+		rt.reconcile()
+		select {
+		case <-ctx.Done():
+			rt.stopAll()
+			return ctx.Err()
+		case <-ticker.C:
+		}
+	}
+}
+
+func ReadBlackboxState(path string) (BlackboxState, error) {
+	path = strings.TrimSpace(path)
+	if path == "" {
+		path = DefaultBlackboxStatePath
+	}
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return BlackboxState{}, err
+	}
+	var state BlackboxState
+	if err := json.Unmarshal(raw, &state); err != nil {
+		return BlackboxState{}, err
+	}
+	return state, nil
+}
+
+func EnableBlackboxTarget(target platform.RemovableTarget) (BlackboxMarker, error) {
+	target = sanitizeRemovableTarget(target)
+	if target.Device == "" {
+		return BlackboxMarker{}, fmt.Errorf("device is required")
+	}
+	mountpoint, mountedByBee, err := ensureMountedTarget(target, "marker")
+	if err != nil {
+		return BlackboxMarker{}, err
+	}
+	defer func() {
+		if mountedByBee {
+			_ = unmountTarget(mountpoint)
+		}
+	}()
+
+	marker, _, err := readBlackboxMarker(mountpoint)
+	if err != nil && !errors.Is(err, os.ErrNotExist) {
+		return BlackboxMarker{}, err
+	}
+	if marker.EnrollmentID == "" {
+		marker = BlackboxMarker{
+			Version:      1,
+			EnrollmentID: newBlackboxEnrollmentID(),
+			CreatedAtUTC: blackboxNow().Format(time.RFC3339),
+			Host:         hostnameOr("unknown"),
+		}
+	}
+	if err := writeBlackboxMarker(mountpoint, marker); err != nil {
+		return BlackboxMarker{}, err
+	}
+	return marker, nil
+}
+
+func DisableBlackboxTarget(device, enrollmentID string) error {
+	device = strings.TrimSpace(device)
+	enrollmentID = strings.TrimSpace(enrollmentID)
+	if device == "" && enrollmentID == "" {
+		return fmt.Errorf("device or enrollment_id is required")
+	}
+	system := platform.New()
+	targets, err := system.ListRemovableTargets()
+	if err != nil {
+		return err
+	}
+	for _, target := range targets {
+		target = sanitizeRemovableTarget(target)
+		mountpoint, mountedByBee, mountErr := ensureMountedTarget(target, "marker")
+		if mountErr != nil {
+			continue
+		}
+		remove := false
+		marker, _, err := readBlackboxMarker(mountpoint)
+		if err == nil {
+			if enrollmentID != "" && marker.EnrollmentID == enrollmentID {
+				remove = true
+			}
+			if device != "" && target.Device == device {
+				remove = true
+			}
+		}
+		if remove {
+			err = os.Remove(filepath.Join(mountpoint, blackboxMarkerName))
+		}
+		if mountedByBee {
+			_ = unmountTarget(mountpoint)
+		}
+		if remove {
+			return err
+		}
+	}
+	return os.ErrNotExist
+}
+
+func (rt *blackboxRuntime) reconcile() {
+	discovered, _ := rt.discoverMarkedTargets()
+
+	rt.mu.Lock()
+	defer rt.mu.Unlock()
+
+	seen := make(map[string]struct{}, len(discovered))
+	for _, found := range discovered {
+		seen[found.marker.EnrollmentID] = struct{}{}
+		worker, ok := rt.workers[found.marker.EnrollmentID]
+		if !ok {
+			worker = newBlackboxWorker(rt, found)
+			rt.workers[found.marker.EnrollmentID] = worker
+			go worker.run()
+			continue
+		}
+		worker.update(found)
+	}
+	for id, worker := range rt.workers {
+		if _, ok := seen[id]; ok {
+			continue
+		}
+		worker.stop()
+		delete(rt.workers, id)
+	}
+	rt.persistStateLocked()
+}
+
+func (rt *blackboxRuntime) stopAll() {
+	rt.mu.Lock()
+	workers := make([]*blackboxWorker, 0, len(rt.workers))
+	for _, worker := range rt.workers {
+		workers = append(workers, worker)
+	}
+	rt.workers = map[string]*blackboxWorker{}
+	rt.persistStateLocked()
+	rt.mu.Unlock()
+	for _, worker := range workers {
+		worker.stop()
+	}
+}
+
+func (rt *blackboxRuntime) discoverMarkedTargets() ([]discoveredBlackboxTarget, error) {
+	targets, err := rt.system.ListRemovableTargets()
+	if err != nil {
+		return nil, err
+	}
+	var out []discoveredBlackboxTarget
+	for _, rawTarget := range targets {
+		target := sanitizeRemovableTarget(rawTarget)
+		if target.Device == "" {
+			continue
+		}
+		mountpoint, mountedByBee, err := ensureMountedTarget(target, "probe")
+		if err != nil {
+			continue
+		}
+		marker, ok, err := readBlackboxMarker(mountpoint)
+		if mountedByBee && !ok {
+			_ = unmountTarget(mountpoint)
+		}
+		if err != nil || !ok || marker.EnrollmentID == "" {
+			continue
+		}
+		if mountedByBee {
+			_ = unmountTarget(mountpoint)
+		}
+		out = append(out, discoveredBlackboxTarget{
+			marker:       marker,
+			target:       target,
+			seenMount:    mountpoint,
+			mountedByBee: mountedByBee,
+		})
+	}
+	sort.Slice(out, func(i, j int) bool {
+		return out[i].marker.EnrollmentID < out[j].marker.EnrollmentID
+	})
+	return out, nil
+}
+
+func newBlackboxWorker(rt *blackboxRuntime, found discoveredBlackboxTarget) *blackboxWorker {
+	return &blackboxWorker{
+		runtime:      rt,
+		enrollmentID: found.marker.EnrollmentID,
+		target:       found.target,
+		marker:       found.marker,
+		flushPeriod:  blackboxMinFlushPeriod,
+		status:       "running",
+		stopCh:       make(chan struct{}),
+		stoppedCh:    make(chan struct{}),
+	}
+}
+
+func (w *blackboxWorker) run() {
+	defer close(w.stoppedCh)
+	for {
+		start := time.Now()
+		err := w.syncCycle()
+		duration := time.Since(start)
+		w.finishCycle(duration, err)
+
+		wait := w.currentFlushPeriod()
+		timer := time.NewTimer(wait)
+		select {
+		case <-w.stopCh:
+			timer.Stop()
+			w.cleanup()
+			return
+		case <-timer.C:
+		}
+	}
+}
+
+func (w *blackboxWorker) update(found discoveredBlackboxTarget) {
+	w.mu.Lock()
+	defer w.mu.Unlock()
+	w.target = found.target
+	w.marker = found.marker
+}
+
+func (w *blackboxWorker) stop() {
+	select {
+	case <-w.stopCh:
+	default:
+		close(w.stopCh)
+	}
+	<-w.stoppedCh
+}
+
+func (w *blackboxWorker) currentFlushPeriod() time.Duration {
+	w.mu.Lock()
+	defer w.mu.Unlock()
+	return w.flushPeriod
+}
+
+func (w *blackboxWorker) finishCycle(duration time.Duration, err error) {
+	w.mu.Lock()
+	defer w.mu.Unlock()
+	w.lastDuration = duration
+	if err != nil {
+		w.status = "degraded"
+		w.lastError = err.Error()
+		w.fastCycles = 0
+		w.flushPeriod = adjustFlushPeriod(w.flushPeriod, duration, false, 0)
+	} else {
+		w.status = "running"
+		w.lastSyncAt = blackboxNow()
+		w.lastError = ""
+		if duration <= w.flushPeriod/2 {
+			w.fastCycles++
+		} else {
+			w.fastCycles = 0
+		}
+		w.flushPeriod = adjustFlushPeriod(w.flushPeriod, duration, true, w.fastCycles)
+	}
+	w.runtime.persistState()
+}
+
+func adjustFlushPeriod(current, duration time.Duration, success bool, fastCycles int) time.Duration {
+	if current <= 0 {
+		current = blackboxMinFlushPeriod
+	}
+	if duration <= 0 {
+		duration = current
+	}
+	next := current
+	if duration > current {
+		growA := time.Duration(float64(current) * 1.25)
+		growB := time.Duration(float64(duration) * 1.25)
+		if growB > growA {
+			next = growB
+		} else {
+			next = growA
+		}
+	}
+	if success && fastCycles >= blackboxRecoveryFastCount {
+		next = time.Duration(float64(current) * 0.9)
+	}
+	if next < blackboxMinFlushPeriod {
+		next = blackboxMinFlushPeriod
+	}
+	if next > blackboxMaxFlushPeriod {
+		next = blackboxMaxFlushPeriod
+	}
+	return next
+}
+
+func (w *blackboxWorker) syncCycle() error {
+	target, marker := w.snapshotTarget()
+	mountpoint, mountedByBee, err := ensureMountedTarget(target, marker.EnrollmentID)
+	if err != nil {
+		return err
+	}
+	w.recordMountpoint(mountpoint, mountedByBee)
+
+	root := filepath.Join(mountpoint, w.runtime.bootFolder)
+	if err := os.MkdirAll(filepath.Join(root, "export"), 0755); err != nil {
+		return err
+	}
+	if err := syncDirectoryTree(w.runtime.exportDir, filepath.Join(root, "export")); err != nil {
+		return err
+	}
+	if err := w.captureSnapshots(root); err != nil {
+		return err
+	}
+	return syncFilesystem(root)
+}
+
+func (w *blackboxWorker) cleanup() {
+	w.mu.Lock()
+	mountpoint := w.mountpoint
+	mountedByBee := w.mountedByBee
+	w.mu.Unlock()
+	if mountedByBee && mountpoint != "" {
+		_ = unmountTarget(mountpoint)
+	}
+}
+
+func (w *blackboxWorker) snapshotTarget() (platform.RemovableTarget, BlackboxMarker) {
+	w.mu.Lock()
+	defer w.mu.Unlock()
+	return w.target, w.marker
+}
+
+func (w *blackboxWorker) recordMountpoint(mountpoint string, mountedByBee bool) {
+	w.mu.Lock()
+	defer w.mu.Unlock()
+	w.mountpoint = mountpoint
+	w.mountedByBee = mountedByBee
+}
+
+func (w *blackboxWorker) captureSnapshots(root string) error {
+	if err := captureCommandAtomic(filepath.Join(root, "systemd", "combined.journal.log"), "journalctl", "--no-pager", "--since", w.runtime.bootStarted.Format(time.RFC3339)); err != nil {
+		return err
+	}
+	for _, svc := range supportBundleServices {
+		if err := captureCommandAtomic(filepath.Join(root, "systemd", svc+".journal.log"), "journalctl", "--no-pager", "-u", svc, "--since", w.runtime.bootStarted.Format(time.RFC3339)); err != nil {
+			return err
+		}
+		if err := captureCommandAtomic(filepath.Join(root, "systemd", svc+".status.txt"), "systemctl", "status", svc, "--no-pager"); err != nil {
+			return err
+		}
+	}
+	if err := captureCommandAtomic(filepath.Join(root, "system", "dmesg.txt"), "dmesg"); err != nil {
+		return err
+	}
+	for _, item := range supportBundleOptionalFiles {
+		if err := copyFileIfChanged(item.src, filepath.Join(root, item.name)); err != nil && !errors.Is(err, os.ErrNotExist) {
+			return err
+		}
+	}
+	return nil
+}
+
+func (rt *blackboxRuntime) persistState() {
+	rt.mu.Lock()
+	defer rt.mu.Unlock()
+	rt.persistStateLocked()
+}
+
+func (rt *blackboxRuntime) persistStateLocked() {
+	state := BlackboxState{
+		Status:           "disabled",
+		BootStartedAtUTC: rt.bootStarted.Format(time.RFC3339),
+		BootFolder:       rt.bootFolder,
+		UpdatedAtUTC:     blackboxNow().Format(time.RFC3339),
+		Targets:          make([]BlackboxTargetStatus, 0, len(rt.workers)),
+	}
+	if len(rt.workers) > 0 {
+		state.Status = "running"
+	}
+	for _, worker := range rt.workers {
+		worker.mu.Lock()
+		targetState := BlackboxTargetStatus{
+			EnrollmentID: worker.enrollmentID,
+			Device:       worker.target.Device,
+			FS:           worker.target,
+			BootFolder:   rt.bootFolder,
+			Status:       worker.status,
+			FlushPeriod:  worker.flushPeriod.String(),
+			LastError:    worker.lastError,
+			Mountpoint:   worker.mountpoint,
+		}
+		if !worker.lastSyncAt.IsZero() {
+			targetState.LastSyncAtUTC = worker.lastSyncAt.Format(time.RFC3339)
+		}
+		if worker.lastDuration > 0 {
+			targetState.LastCycleDuration = worker.lastDuration.String()
+		}
+		if worker.status == "degraded" {
+			state.Status = "degraded"
+		}
+		worker.mu.Unlock()
+		state.Targets = append(state.Targets, targetState)
+	}
+	sort.Slice(state.Targets, func(i, j int) bool {
+		return state.Targets[i].EnrollmentID < state.Targets[j].EnrollmentID
+	})
+	_ = writeJSONAtomic(rt.statePath, state)
+}
+
+func bootStartedAtUTC() (time.Time, error) {
+	raw, err := os.ReadFile("/proc/stat")
+	if err != nil {
+		return time.Time{}, err
+	}
+	for _, line := range strings.Split(string(raw), "\n") {
+		line = strings.TrimSpace(line)
+		if !strings.HasPrefix(line, "btime ") {
+			continue
+		}
+		parts := strings.Fields(line)
+		if len(parts) != 2 {
+			break
+		}
+		sec, err := time.ParseDuration(parts[1] + "s")
+		if err != nil {
+			break
+		}
+		return time.Unix(int64(sec/time.Second), 0).UTC(), nil
+	}
+	return time.Time{}, fmt.Errorf("boot time not found")
+}
+
+func newBlackboxEnrollmentID() string {
+	var buf [8]byte
+	if _, err := rand.Read(buf[:]); err != nil {
+		return fmt.Sprintf("bb-%d", time.Now().UnixNano())
+	}
+	return "bb-" + hex.EncodeToString(buf[:])
+}
+
+func sanitizeRemovableTarget(target platform.RemovableTarget) platform.RemovableTarget {
+	target.Device = strings.TrimSpace(target.Device)
+	target.FSType = strings.TrimSpace(target.FSType)
+	target.Size = strings.TrimSpace(target.Size)
+	target.Label = strings.TrimSpace(target.Label)
+	target.Model = strings.TrimSpace(target.Model)
+	target.Mountpoint = strings.TrimSpace(target.Mountpoint)
+	return target
+}
+
+func ensureMountedTarget(target platform.RemovableTarget, suffix string) (mountpoint string, mountedByBee bool, retErr error) {
+	target = sanitizeRemovableTarget(target)
+	if target.Mountpoint != "" {
+		if err := ensureWritableBlackboxMountpoint(target.Mountpoint); err == nil {
+			return target.Mountpoint, false, nil
+		}
+	}
+	mountpoint = filepath.Join("/tmp", "bee-blackbox-"+sanitizeFilename(suffix))
+	if err := os.MkdirAll(mountpoint, 0755); err != nil {
+		return "", false, err
+	}
+	if raw, err := blackboxExecCommand("mount", target.Device, mountpoint).CombinedOutput(); err != nil {
+		return "", false, formatBlackboxMountTargetError(target, string(raw), err)
+	}
+	if err := ensureWritableBlackboxMountpoint(mountpoint); err != nil {
+		_ = unmountTarget(mountpoint)
+		return "", false, err
+	}
+	return mountpoint, true, nil
+}
+
+func unmountTarget(mountpoint string) error {
+	_ = blackboxExecCommand("sync").Run()
+	raw, err := blackboxExecCommand("umount", mountpoint).CombinedOutput()
+	if err != nil {
+		msg := strings.TrimSpace(string(raw))
+		if msg == "" {
+			return err
+		}
+		return fmt.Errorf("%s: %w", msg, err)
+	}
+	return nil
+}
+
+func readBlackboxMarker(mountpoint string) (BlackboxMarker, bool, error) {
+	raw, err := os.ReadFile(filepath.Join(mountpoint, blackboxMarkerName))
+	if err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			return BlackboxMarker{}, false, os.ErrNotExist
+		}
+		return BlackboxMarker{}, false, err
+	}
+	var marker BlackboxMarker
+	if err := json.Unmarshal(raw, &marker); err != nil {
+		return BlackboxMarker{}, false, err
+	}
+	return marker, true, nil
+}
+
+func writeBlackboxMarker(mountpoint string, marker BlackboxMarker) error {
+	if marker.Version == 0 {
+		marker.Version = 1
+	}
+	return writeJSONAtomic(filepath.Join(mountpoint, blackboxMarkerName), marker)
+}
+
+func syncDirectoryTree(srcDir, dstDir string) error {
+	seen := make(map[string]struct{})
+	err := filepath.WalkDir(srcDir, func(path string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		rel, err := filepath.Rel(srcDir, path)
+		if err != nil {
+			return err
+		}
+		rel = filepath.Clean(rel)
+		if rel == "." {
+			seen["."] = struct{}{}
+			return os.MkdirAll(dstDir, 0755)
+		}
+		seen[rel] = struct{}{}
+		dstPath := filepath.Join(dstDir, rel)
+		if d.IsDir() {
+			info, err := d.Info()
+			if err != nil {
+				return err
+			}
+			return os.MkdirAll(dstPath, info.Mode().Perm())
+		}
+		return copyFileIfChanged(path, dstPath)
+	})
+	if err != nil {
+		return err
+	}
+	return removeMissingPaths(dstDir, seen)
+}
+
+func removeMissingPaths(dstDir string, seen map[string]struct{}) error {
+	return filepath.WalkDir(dstDir, func(path string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		rel, err := filepath.Rel(dstDir, path)
+		if err != nil {
+			return err
+		}
+		rel = filepath.Clean(rel)
+		if rel == "." {
+			return nil
+		}
+		if _, ok := seen[rel]; ok {
+			return nil
+		}
+		return os.RemoveAll(path)
+	})
+}
+
+func copyFileIfChanged(src, dst string) error {
+	info, err := os.Stat(src)
+	if err != nil {
+		return err
+	}
+	if info.IsDir() {
+		return os.MkdirAll(dst, info.Mode().Perm())
+	}
+	srcData, err := os.ReadFile(src)
+	if err != nil {
+		return err
+	}
+	if dstData, err := os.ReadFile(dst); err == nil && bytes.Equal(dstData, srcData) {
+		return nil
+	}
+	return writeFileAtomic(dst, srcData, info.Mode().Perm())
+}
+
+func captureCommandAtomic(dst string, name string, args ...string) error {
+	raw, err := blackboxExecCommand(name, args...).CombinedOutput()
+	if len(raw) == 0 {
+		if err != nil {
+			raw = []byte(err.Error() + "\n")
+		} else {
+			raw = []byte("no output\n")
+		}
+	}
+	return writeFileAtomic(dst, raw, 0644)
+}
+
+func writeJSONAtomic(path string, v any) error {
+	raw, err := json.MarshalIndent(v, "", "  ")
+	if err != nil {
+		return err
+	}
+	raw = append(raw, '\n')
+	return writeFileAtomic(path, raw, 0644)
+}
+
+func writeFileAtomic(path string, data []byte, perm os.FileMode) error {
+	if err := os.MkdirAll(filepath.Dir(path), 0755); err != nil {
+		return err
+	}
+	if existing, err := os.ReadFile(path); err == nil && bytes.Equal(existing, data) {
+		return nil
+	}
+	tmp := path + ".tmp"
+	f, err := os.OpenFile(tmp, os.O_CREATE|os.O_TRUNC|os.O_WRONLY, perm)
+	if err != nil {
+		return err
+	}
+	if _, err := f.Write(data); err != nil {
+		_ = f.Close()
+		return err
+	}
+	if err := f.Sync(); err != nil {
+		_ = f.Close()
+		return err
+	}
+	if err := f.Close(); err != nil {
+		return err
+	}
+	if err := os.Rename(tmp, path); err != nil {
+		return err
+	}
+	return syncFilesystem(filepath.Dir(path))
+}
+
+func syncFilesystem(path string) error {
+	return blackboxExecCommand("sync").Run()
+}
+
+func ensureWritableBlackboxMountpoint(mountpoint string) error {
+	probe, err := os.CreateTemp(mountpoint, ".bee-blackbox-write-test-*")
+	if err != nil {
+		return fmt.Errorf("target filesystem is not writable: %w", err)
+	}
+	name := probe.Name()
+	if closeErr := probe.Close(); closeErr != nil {
+		_ = os.Remove(name)
+		return closeErr
+	}
+	if err := os.Remove(name); err != nil {
+		return err
+	}
+	return nil
+}
+
+func formatBlackboxMountTargetError(target platform.RemovableTarget, raw string, err error) error {
+	msg := strings.TrimSpace(raw)
+	fstype := strings.ToLower(strings.TrimSpace(target.FSType))
+	if fstype == "exfat" && strings.Contains(strings.ToLower(msg), "unknown filesystem type 'exfat'") {
+		return fmt.Errorf("mount %s: exFAT support is missing in this ISO build: %w", target.Device, err)
+	}
+	if msg == "" {
+		return err
+	}
+	return fmt.Errorf("%s: %w", msg, err)
+}

audit/internal/app/blackbox_test.go

@@ -0,0 +1,52 @@
+package app
+
+import (
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+func TestAdjustFlushPeriodGrowsOnSlowCycle(t *testing.T) {
+	current := 2 * time.Second
+	got := adjustFlushPeriod(current, 4*time.Second, false, 0)
+	if got <= current {
+		t.Fatalf("adjustFlushPeriod=%s want > %s", got, current)
+	}
+}
+
+func TestAdjustFlushPeriodShrinksAfterFastCycles(t *testing.T) {
+	current := 10 * time.Second
+	got := adjustFlushPeriod(current, 2*time.Second, true, blackboxRecoveryFastCount)
+	if got >= current {
+		t.Fatalf("adjustFlushPeriod=%s want < %s", got, current)
+	}
+	if got < blackboxMinFlushPeriod {
+		t.Fatalf("adjustFlushPeriod=%s below min %s", got, blackboxMinFlushPeriod)
+	}
+}
+
+func TestReadBlackboxState(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "blackbox-state.json")
+	want := BlackboxState{
+		Status:           "running",
+		BootStartedAtUTC: "2026-04-24T00:00:00Z",
+		BootFolder:       "boot-folder",
+		UpdatedAtUTC:     "2026-04-24T00:00:01Z",
+		Targets: []BlackboxTargetStatus{{
+			EnrollmentID: "bb-1",
+			Device:       "/dev/sdb1",
+			Status:       "running",
+			FlushPeriod:  "1s",
+		}},
+	}
+	if err := writeJSONAtomic(path, want); err != nil {
+		t.Fatalf("writeJSONAtomic: %v", err)
+	}
+	got, err := ReadBlackboxState(path)
+	if err != nil {
+		t.Fatalf("ReadBlackboxState: %v", err)
+	}
+	if got.Status != want.Status || got.BootFolder != want.BootFolder || len(got.Targets) != 1 || got.Targets[0].EnrollmentID != "bb-1" {
+		t.Fatalf("state=%+v", got)
+	}
+}

audit/internal/app/support_bundle.go

@@ -15,6 +15,7 @@ import (
 )
 
 var supportBundleServices = []string{
+	"bee-blackbox.service",
 	"bee-audit.service",
 	"bee-web.service",
 	"bee-network.service",
@@ -256,11 +257,6 @@ func BuildSupportBundle(exportDir string) (string, error) {
 	}
 
 	now := time.Now().UTC()
-	date := now.Format("2006-01-02")
-	tod := now.Format("150405")
-	ver := bundleVersion()
-	model := serverModelForBundle()
-	sn := serverSerialForBundle()
 
 	stageRoot := filepath.Join(os.TempDir(), fmt.Sprintf("bee-support-stage-%s-%s", sanitizeFilename(hostnameOr("unknown")), now.Format("20060102-150405")))
 	if err := os.MkdirAll(stageRoot, 0755); err != nil {
@@ -294,7 +290,7 @@ func BuildSupportBundle(exportDir string) (string, error) {
 		return "", err
 	}
 
-	archiveName := fmt.Sprintf("%s (BEE-SP v%s) %s %s %s.tar.gz", date, ver, model, sn, tod)
+	archiveName := SupportBundleBaseName(now) + ".tar.gz"
 	archivePath := filepath.Join(os.TempDir(), archiveName)
 	if err := createSupportTarGz(archivePath, stageRoot); err != nil {
 		return "", err
@@ -302,6 +298,16 @@ func BuildSupportBundle(exportDir string) (string, error) {
 	return archivePath, nil
 }
 
+func SupportBundleBaseName(at time.Time) string {
+	at = at.UTC()
+	date := at.Format("2006-01-02")
+	tod := at.Format("150405")
+	ver := bundleVersion()
+	model := serverModelForBundle()
+	sn := serverSerialForBundle()
+	return fmt.Sprintf("%s (BEE-SP v%s) %s %s %s", date, ver, model, sn, tod)
+}
+
 func LatestSupportBundlePath() (string, error) {
 	return latestSupportBundlePath(os.TempDir())
 }

audit/internal/collector/pcie.go

@@ -4,7 +4,9 @@ import (
 	"bee/audit/internal/schema"
 	"fmt"
 	"log/slog"
+	"os"
 	"os/exec"
+	"path/filepath"
 	"strconv"
 	"strings"
 )
@@ -140,6 +142,9 @@ func parseLspciDevice(fields map[string]string) schema.HardwarePCIeDevice {
 		} else if numaNode, ok := parsePCINumaNode(fields["NUMANode"]); ok {
 			dev.NUMANode = &numaNode
 		}
+		if group, ok := readPCIIOMMUGroup(bdf); ok {
+			dev.IOMMUGroup = &group
+		}
 		if width, ok := readPCIIntAttribute(bdf, "current_link_width"); ok {
 			dev.LinkWidth = &width
 		}
@@ -179,6 +184,21 @@ func parseLspciDevice(fields map[string]string) schema.HardwarePCIeDevice {
 	return dev
 }
 
+// readPCIIOMMUGroup resolves the IOMMU group number for a BDF via the
+// iommu_group symlink in sysfs: .../devices/<bdf>/iommu_group -> .../kernel/iommu_groups/<N>
+func readPCIIOMMUGroup(bdf string) (int, bool) {
+	link := "/sys/bus/pci/devices/" + bdf + "/iommu_group"
+	target, err := os.Readlink(link)
+	if err != nil {
+		return 0, false
+	}
+	n, err := strconv.Atoi(filepath.Base(target))
+	if err != nil {
+		return 0, false
+	}
+	return n, true
+}
+
 // readPCIIDs reads vendor and device IDs from sysfs for a given BDF.
 func readPCIIDs(bdf string) (vendorID, deviceID int) {
 	base := "/sys/bus/pci/devices/" + bdf

audit/internal/collector/storage.go

@@ -250,6 +250,8 @@ func enrichWithSmartctl(dev lsblkDevice) schema.HardwareStorage {
 	}
 
 	var info smartctlInfo
+	var raw map[string]any
+	_ = json.Unmarshal(out, &raw)
 	if err := json.Unmarshal(out, &info); err == nil {
 		if v := cleanDMIValue(info.ModelName); v != "" {
 			s.Model = &v
@@ -302,8 +304,11 @@ func enrichWithSmartctl(dev lsblkDevice) schema.HardwareStorage {
 				value := float64(attr.Raw.Value)
 				s.LifeRemainingPct = &value
 			case 241:
-				value := attr.Raw.Value
+				value := smartLBAsToBytes(attr.Raw.Value)
 				s.WrittenBytes = &value
+			case 242:
+				value := smartLBAsToBytes(attr.Raw.Value)
+				s.ReadBytes = &value
 			case 197:
 				pending = attr.Raw.Value
 				s.CurrentPendingSectors = &pending
@@ -321,6 +326,7 @@ func enrichWithSmartctl(dev lsblkDevice) schema.HardwareStorage {
 			offlineUncorrectable: uncorrectable,
 			lifeRemainingPct:     lifeRemaining,
 		}
+		applySCSISmartctlTelemetry(&s, raw, &status)
 		setStorageHealthStatus(&s, status)
 		return s
 	}
@@ -477,6 +483,127 @@ func nvmeDataUnitsToBytes(units int64) int64 {
 	return units * 512000
 }
 
+func smartLBAsToBytes(lbas int64) int64 {
+	if lbas <= 0 {
+		return 0
+	}
+	return lbas * 512
+}
+
+func applySCSISmartctlTelemetry(s *schema.HardwareStorage, raw map[string]any, status *storageHealthStatus) {
+	if s == nil || len(raw) == 0 {
+		return
+	}
+	if v, ok := firstInt64(raw,
+		"path:power_on_time.hours",
+		"path:accumulated_power_on_time.hours",
+		"path:power_on_time.hour",
+		"path:accumulated_power_on_time.hour",
+	); ok && v > 0 && s.PowerOnHours == nil {
+		s.PowerOnHours = &v
+	}
+	if v, ok := firstInt64(raw,
+		"path:power_cycle_count",
+		"path:start_stop_cycle_count",
+		"path:accumulated_start_stop_cycles",
+	); ok && v > 0 && s.PowerCycles == nil {
+		s.PowerCycles = &v
+	}
+	if v, ok := firstInt64(raw,
+		"path:scsi_grown_defect_list",
+		"path:grown_defect_list",
+	); ok && v > 0 && s.ReallocatedSectors == nil {
+		s.ReallocatedSectors = &v
+		if status != nil && status.reallocatedSectors == 0 {
+			status.reallocatedSectors = v
+		}
+	}
+	if v, ok := firstInt64(raw,
+		"path:percentage_used_endurance_indicator",
+		"path:scsi_percentage_used_endurance_indicator",
+	); ok && v > 0 {
+		if s.LifeUsedPct == nil {
+			fv := float64(v)
+			s.LifeUsedPct = &fv
+		}
+		if s.LifeRemainingPct == nil && v <= 100 {
+			remaining := float64(100 - v)
+			s.LifeRemainingPct = &remaining
+			if status != nil && status.lifeRemainingPct == 0 {
+				status.lifeRemainingPct = int64(remaining)
+			}
+		}
+	}
+	blockSize, hasBlockSize := firstInt64(raw,
+		"path:logical_block_size",
+		"path:block_size",
+		"path:user_capacity.block_size",
+	)
+	if hasBlockSize && blockSize > 0 {
+		if v, ok := firstInt64(raw,
+			"path:logical_blocks_written",
+			"path:total_lbas_written",
+		); ok && v > 0 && s.WrittenBytes == nil {
+			bytes := v * blockSize
+			s.WrittenBytes = &bytes
+		}
+		if v, ok := firstInt64(raw,
+			"path:logical_blocks_read",
+			"path:total_lbas_read",
+		); ok && v > 0 && s.ReadBytes == nil {
+			bytes := v * blockSize
+			s.ReadBytes = &bytes
+		}
+	}
+}
+
+func firstInt64(root map[string]any, candidates ...string) (int64, bool) {
+	for _, candidate := range candidates {
+		if !strings.HasPrefix(candidate, "path:") {
+			continue
+		}
+		path := strings.TrimPrefix(candidate, "path:")
+		if v, ok := nestedInt64(root, strings.Split(path, ".")); ok {
+			return v, true
+		}
+	}
+	return 0, false
+}
+
+func nestedInt64(root map[string]any, path []string) (int64, bool) {
+	var current any = root
+	for _, key := range path {
+		obj, ok := current.(map[string]any)
+		if !ok {
+			return 0, false
+		}
+		current, ok = obj[key]
+		if !ok {
+			return 0, false
+		}
+	}
+	switch v := current.(type) {
+	case float64:
+		return int64(v), true
+	case float32:
+		return int64(v), true
+	case int:
+		return int64(v), true
+	case int64:
+		return v, true
+	case int32:
+		return int64(v), true
+	case json.Number:
+		n, err := v.Int64()
+		return n, err == nil
+	case string:
+		n, err := strconv.ParseInt(strings.TrimSpace(v), 10, 64)
+		return n, err == nil
+	default:
+		return 0, false
+	}
+}
+
 type storageHealthStatus struct {
 	hasOverall           bool
 	overallPassed        bool

audit/internal/collector/storage_scsi_test.go

@@ -0,0 +1,89 @@
+package collector
+
+import (
+	"testing"
+
+	"bee/audit/internal/schema"
+)
+
+func TestApplySCSISmartctlTelemetry(t *testing.T) {
+	t.Parallel()
+
+	raw := map[string]any{
+		"power_on_time": map[string]any{
+			"hours": float64(32123),
+		},
+		"accumulated_start_stop_cycles":       float64(17),
+		"scsi_grown_defect_list":              float64(4),
+		"percentage_used_endurance_indicator": float64(12),
+		"logical_block_size":                  float64(4096),
+		"logical_blocks_written":              float64(1000),
+		"logical_blocks_read":                 float64(2000),
+	}
+
+	var disk schema.HardwareStorage
+	status := storageHealthStatus{}
+	applySCSISmartctlTelemetry(&disk, raw, &status)
+
+	if disk.PowerOnHours == nil || *disk.PowerOnHours != 32123 {
+		t.Fatalf("power_on_hours=%v want 32123", disk.PowerOnHours)
+	}
+	if disk.PowerCycles == nil || *disk.PowerCycles != 17 {
+		t.Fatalf("power_cycles=%v want 17", disk.PowerCycles)
+	}
+	if disk.ReallocatedSectors == nil || *disk.ReallocatedSectors != 4 {
+		t.Fatalf("reallocated=%v want 4", disk.ReallocatedSectors)
+	}
+	if disk.WrittenBytes == nil || *disk.WrittenBytes != 4096000 {
+		t.Fatalf("written_bytes=%v want 4096000", disk.WrittenBytes)
+	}
+	if disk.ReadBytes == nil || *disk.ReadBytes != 8192000 {
+		t.Fatalf("read_bytes=%v want 8192000", disk.ReadBytes)
+	}
+	if disk.LifeUsedPct == nil || *disk.LifeUsedPct != 12 {
+		t.Fatalf("life_used_pct=%v want 12", disk.LifeUsedPct)
+	}
+	if disk.LifeRemainingPct == nil || *disk.LifeRemainingPct != 88 {
+		t.Fatalf("life_remaining_pct=%v want 88", disk.LifeRemainingPct)
+	}
+	if status.reallocatedSectors != 4 {
+		t.Fatalf("status.reallocated=%d want 4", status.reallocatedSectors)
+	}
+	if status.lifeRemainingPct != 88 {
+		t.Fatalf("status.life_remaining_pct=%d want 88", status.lifeRemainingPct)
+	}
+}
+
+func TestApplySCSISmartctlTelemetryDoesNotOverwriteExistingValues(t *testing.T) {
+	t.Parallel()
+
+	powerOnHours := int64(10)
+	writtenBytes := int64(20)
+	lifeRemaining := 30.0
+	disk := schema.HardwareStorage{
+		PowerOnHours:     &powerOnHours,
+		WrittenBytes:     &writtenBytes,
+		LifeRemainingPct: &lifeRemaining,
+	}
+	raw := map[string]any{
+		"power_on_time":                       map[string]any{"hours": float64(999)},
+		"logical_block_size":                  float64(512),
+		"logical_blocks_written":              float64(999),
+		"percentage_used_endurance_indicator": float64(50),
+	}
+
+	applySCSISmartctlTelemetry(&disk, raw, nil)
+
+	if *disk.PowerOnHours != 10 {
+		t.Fatalf("power_on_hours overwritten: got %d want 10", *disk.PowerOnHours)
+	}
+	if *disk.WrittenBytes != 20 {
+		t.Fatalf("written_bytes overwritten: got %d want 20", *disk.WrittenBytes)
+	}
+	if *disk.LifeRemainingPct != 30 {
+		t.Fatalf("life_remaining_pct overwritten: got %v want 30", *disk.LifeRemainingPct)
+	}
+	if disk.LifeUsedPct == nil || *disk.LifeUsedPct != 50 {
+		t.Fatalf("life_used_pct=%v want 50", disk.LifeUsedPct)
+	}
+}

audit/internal/collector/storage_telemetry_test.go

@@ -0,0 +1,25 @@
+package collector
+
+import "testing"
+
+func TestSmartLBAsToBytes(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name string
+		lbas int64
+		want int64
+	}{
+		{name: "zero", lbas: 0, want: 0},
+		{name: "single lba", lbas: 1, want: 512},
+		{name: "multiple lbas", lbas: 2048, want: 1048576},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := smartLBAsToBytes(tt.lbas); got != tt.want {
+				t.Fatalf("smartLBAsToBytes(%d)=%d want %d", tt.lbas, got, tt.want)
+			}
+		})
+	}
+}

audit/internal/schema/hardware.go

@@ -211,6 +211,7 @@ type HardwarePCIeDevice struct {
 	Firmware               *string        `json:"firmware,omitempty"`
 	MacAddresses           []string       `json:"mac_addresses,omitempty"`
 	Present                *bool          `json:"present,omitempty"`
+	IOMMUGroup             *int           `json:"iommu_group,omitempty"`
 	Telemetry              map[string]any `json:"-"`
 }
 

audit/internal/schema/hardware_test.go

@@ -44,3 +44,48 @@ func TestHardwareSnapshotMarshalsNewContractFields(t *testing.T) {
 		t.Fatalf("missing event_logs payload: %s", text)
 	}
 }
+
+func TestHardwareSnapshotMarshalsStorageTelemetryFields(t *testing.T) {
+	powerOnHours := int64(12450)
+	writtenBytes := int64(9876543210)
+	readBytes := int64(1234567890)
+	lifeRemainingPct := 91.0
+
+	payload := HardwareIngestRequest{
+		CollectedAt: "2026-03-15T15:00:00Z",
+		Hardware: HardwareSnapshot{
+			Board: HardwareBoard{SerialNumber: "SRV-001"},
+			Storage: []HardwareStorage{
+				{
+					SerialNumber:     stringPtr("DISK-001"),
+					Model:            stringPtr("TestDisk"),
+					PowerOnHours:     &powerOnHours,
+					WrittenBytes:     &writtenBytes,
+					ReadBytes:        &readBytes,
+					LifeRemainingPct: &lifeRemainingPct,
+				},
+			},
+		},
+	}
+
+	data, err := json.Marshal(payload)
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	text := string(data)
+	for _, needle := range []string{
+		`"storage":[{`,
+		`"power_on_hours":12450`,
+		`"written_bytes":9876543210`,
+		`"read_bytes":1234567890`,
+		`"life_remaining_pct":91`,
+	} {
+		if !strings.Contains(text, needle) {
+			t.Fatalf("missing %q in payload: %s", needle, text)
+		}
+	}
+}
+
+func stringPtr(v string) *string {
+	return &v
+}

audit/internal/webui/api.go

@@ -1038,6 +1038,81 @@ func (h *handler) handleAPIExportUSBBundle(w http.ResponseWriter, r *http.Reques
 	writeJSON(w, map[string]string{"status": "ok", "message": result.Body})
 }
 
+func (h *handler) handleAPIBlackboxStatus(w http.ResponseWriter, _ *http.Request) {
+	state, err := app.ReadBlackboxState(filepath.Join(h.opts.ExportDir, "blackbox-state.json"))
+	if err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			writeJSON(w, app.BlackboxState{Status: "disabled", Targets: []app.BlackboxTargetStatus{}})
+			return
+		}
+		writeError(w, http.StatusInternalServerError, err.Error())
+		return
+	}
+	if state.Targets == nil {
+		state.Targets = []app.BlackboxTargetStatus{}
+	}
+	writeJSON(w, state)
+}
+
+func (h *handler) handleAPIBlackboxEnable(w http.ResponseWriter, r *http.Request) {
+	if h.opts.App == nil {
+		writeError(w, http.StatusServiceUnavailable, "app not configured")
+		return
+	}
+	var target platform.RemovableTarget
+	if err := json.NewDecoder(r.Body).Decode(&target); err != nil || strings.TrimSpace(target.Device) == "" {
+		writeError(w, http.StatusBadRequest, "device is required")
+		return
+	}
+	targets, err := h.opts.App.ListRemovableTargets()
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, err.Error())
+		return
+	}
+	allowed := false
+	for _, candidate := range targets {
+		if candidate.Device == target.Device {
+			target = candidate
+			allowed = true
+			break
+		}
+	}
+	if !allowed {
+		writeError(w, http.StatusBadRequest, "device not in removable target list")
+		return
+	}
+	marker, err := app.EnableBlackboxTarget(target)
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, err.Error())
+		return
+	}
+	writeJSON(w, map[string]any{
+		"status":        "ok",
+		"message":       "Black-box marker written.",
+		"enrollment_id": marker.EnrollmentID,
+	})
+}
+
+func (h *handler) handleAPIBlackboxDisable(w http.ResponseWriter, r *http.Request) {
+	var req struct {
+		Device       string `json:"device"`
+		EnrollmentID string `json:"enrollment_id"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeError(w, http.StatusBadRequest, "invalid request body")
+		return
+	}
+	if err := app.DisableBlackboxTarget(req.Device, req.EnrollmentID); err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			writeError(w, http.StatusNotFound, "black-box target not found")
+			return
+		}
+		writeError(w, http.StatusInternalServerError, err.Error())
+		return
+	}
+	writeJSON(w, map[string]string{"status": "ok", "message": "Black-box marker removed."})
+}
+
 // ── GPU presence ──────────────────────────────────────────────────────────────
 
 func (h *handler) handleAPIGNVIDIAGPUs(w http.ResponseWriter, _ *http.Request) {

audit/internal/webui/api_test.go

@@ -3,6 +3,8 @@ package webui
 import (
 	"encoding/json"
 	"net/http/httptest"
+	"os"
+	"path/filepath"
 	"strings"
 	"testing"
 
@@ -44,6 +46,45 @@ func TestHandleAPISATRunDecodesBodyWithoutContentLength(t *testing.T) {
 	}
 }
 
+func TestHandleAPIBlackboxStatusReturnsDisabledWhenStateMissing(t *testing.T) {
+	h := &handler{opts: HandlerOptions{ExportDir: t.TempDir()}}
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest("GET", "/api/blackbox/status", nil)
+
+	h.handleAPIBlackboxStatus(rec, req)
+
+	if rec.Code != 200 {
+		t.Fatalf("status=%d body=%s", rec.Code, rec.Body.String())
+	}
+	var state app.BlackboxState
+	if err := json.Unmarshal(rec.Body.Bytes(), &state); err != nil {
+		t.Fatalf("decode state: %v", err)
+	}
+	if state.Status != "disabled" {
+		t.Fatalf("status=%q want disabled", state.Status)
+	}
+}
+
+func TestHandleAPIBlackboxStatusReturnsPersistedState(t *testing.T) {
+	exportDir := t.TempDir()
+	statePath := filepath.Join(exportDir, "blackbox-state.json")
+	if err := os.WriteFile(statePath, []byte(`{"status":"running","boot_folder":"boot-folder","targets":[{"enrollment_id":"bb-1","device":"/dev/sdb1","status":"running","flush_period":"1s"}]}`), 0644); err != nil {
+		t.Fatalf("write state: %v", err)
+	}
+	h := &handler{opts: HandlerOptions{ExportDir: exportDir}}
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest("GET", "/api/blackbox/status", nil)
+
+	h.handleAPIBlackboxStatus(rec, req)
+
+	if rec.Code != 200 {
+		t.Fatalf("status=%d body=%s", rec.Code, rec.Body.String())
+	}
+	if !strings.Contains(rec.Body.String(), `"boot_folder":"boot-folder"`) {
+		t.Fatalf("body=%s", rec.Body.String())
+	}
+}
+
 func TestHandleAPIBenchmarkNvidiaRunQueuesSelectedGPUs(t *testing.T) {
 	globalQueue.mu.Lock()
 	originalTasks := globalQueue.tasks

audit/internal/webui/page_export_tools.go

@@ -102,47 +102,69 @@ window.supportBundleDownload = function() {
 
 func renderUSBExportCard() string {
 	return `<div class="card" style="margin-top:16px">
-  <div class="card-head">Export to USB
-    <button class="btn btn-sm btn-secondary" onclick="usbRefresh()" style="margin-left:auto">&#8635; Refresh</button>
+  <div class="card-head">USB Black-Box
+    <button class="btn btn-sm btn-secondary" onclick="blackboxRefresh()" style="margin-left:auto">&#8635; Refresh</button>
   </div>
   <div class="card-body">` + renderUSBExportInline() + `</div>
 </div>`
 }
 
 func renderUSBExportInline() string {
-	return `<p style="font-size:13px;color:var(--muted);margin-bottom:12px">Write audit JSON or support bundle directly to a removable USB drive.</p>
+	return `<p style="font-size:13px;color:var(--muted);margin-bottom:12px">Marks removable USB devices as black-box targets. The dedicated bee-blackbox service mirrors export files and system logs into a boot-scoped folder and resumes automatically after restart.</p>
 <div id="usb-status" style="font-size:13px;color:var(--muted)">Scanning for USB devices...</div>
+<div id="blackbox-summary" style="margin-top:8px;font-size:13px;color:var(--muted)">Loading black-box status...</div>
 <div id="usb-targets" style="margin-top:12px"></div>
 <div id="usb-msg" style="margin-top:10px;font-size:13px"></div>
 <script>
 (function(){
-function usbRefresh() {
+function blackboxRefresh() {
   document.getElementById('usb-status').textContent = 'Scanning...';
+  document.getElementById('blackbox-summary').textContent = 'Loading black-box status...';
   document.getElementById('usb-targets').innerHTML = '';
   document.getElementById('usb-msg').textContent = '';
-  fetch('/api/export/usb').then(r=>r.json()).then(targets => {
-    window._usbTargets = Array.isArray(targets) ? targets : [];
+  Promise.all([
+    fetch('/api/export/usb').then(r=>r.json()),
+    fetch('/api/blackbox/status').then(r=>r.json())
+  ]).then(function(values) {
+    const targets = Array.isArray(values[0]) ? values[0] : [];
+    const state = values[1] || {};
+    const active = Array.isArray(state.targets) ? state.targets : [];
+    window._usbTargets = targets;
+    window._blackboxTargets = active;
     const st = document.getElementById('usb-status');
     const ct = document.getElementById('usb-targets');
+    const summary = document.getElementById('blackbox-summary');
+    if (state.boot_folder) {
+      summary.textContent = 'Service state: ' + (state.status || 'unknown') + '. Boot folder: ' + state.boot_folder + '.';
+    } else {
+      summary.textContent = 'Service state: ' + (state.status || 'disabled') + '.';
+    }
     if (!targets || targets.length === 0) {
       st.textContent = 'No removable USB devices found.';
-      return;
+    } else {
+      st.textContent = targets.length + ' device(s) found:';
     }
-    st.textContent = targets.length + ' device(s) found:';
-    ct.innerHTML = '<table><tr><th>Device</th><th>FS</th><th>Size</th><th>Label</th><th>Model</th><th>Actions</th></tr>' +
+    const byDevice = {};
+    active.forEach(function(item) { byDevice[item.device] = item; });
+    ct.innerHTML = '<table><tr><th>Device</th><th>FS</th><th>Size</th><th>Label</th><th>Model</th><th>Black-Box</th><th>Actions</th></tr>' +
       targets.map((t, idx) => {
         const dev = t.device || '';
         const label = t.label || '';
         const model = t.model || '';
+        const state = byDevice[dev];
+        const status = state ? (state.status + (state.flush_period ? ', flush ' + state.flush_period : '')) : 'not enrolled';
+        const detail = state && state.last_error ? ('<div style="font-size:12px;color:var(--err,red)">'+state.last_error+'</div>') : '';
         return '<tr>' +
           '<td style="font-family:monospace">'+dev+'</td>' +
           '<td>'+t.fs_type+'</td>' +
           '<td>'+t.size+'</td>' +
           '<td>'+label+'</td>' +
           '<td style="font-size:12px;color:var(--muted)">'+model+'</td>' +
+          '<td style="font-size:12px">'+status+detail+'</td>' +
           '<td style="white-space:nowrap">' +
-            '<button class="btn btn-sm btn-primary" onclick="usbExport(\'audit\','+idx+',this)">Audit JSON</button> ' +
-            '<button class="btn btn-sm btn-secondary" onclick="usbExport(\'bundle\','+idx+',this)">Support Bundle</button>' +
+            (state
+              ? '<button class="btn btn-sm btn-secondary" onclick="blackboxDisable('+idx+',this)">Disable</button>'
+              : '<button class="btn btn-sm btn-primary" onclick="blackboxEnable('+idx+',this)">Enable</button>') +
             '<div class="usb-row-msg" style="margin-top:6px;font-size:12px;color:var(--muted)"></div>' +
           '</td></tr>';
       }).join('') + '</table>';
@@ -150,7 +172,7 @@ function usbRefresh() {
     document.getElementById('usb-status').textContent = 'Error: ' + e;
   });
 }
-window.usbExport = function(type, targetIndex, btn) {
+window.blackboxEnable = function(targetIndex, btn) {
   const target = (window._usbTargets || [])[targetIndex];
   if (!target) {
     const msg = document.getElementById('usb-msg');
@@ -164,15 +186,15 @@ window.usbExport = function(type, targetIndex, btn) {
   const originalText = btn ? btn.textContent : '';
   if (btn) {
     btn.disabled = true;
-    btn.textContent = 'Exporting...';
+    btn.textContent = 'Enabling...';
   }
   if (rowMsg) {
     rowMsg.style.color = 'var(--muted)';
     rowMsg.textContent = 'Working...';
   }
   msg.style.color = 'var(--muted)';
-  msg.textContent = 'Exporting ' + (type === 'bundle' ? 'support bundle' : 'audit JSON') + ' to ' + (target.device||'') + '...';
-  fetch('/api/export/usb/'+type, {
+  msg.textContent = 'Enabling black-box on ' + (target.device||'') + '...';
+  fetch('/api/blackbox/enable', {
     method: 'POST',
     headers: {'Content-Type':'application/json'},
     body: JSON.stringify(target)
@@ -199,10 +221,64 @@ window.usbExport = function(type, targetIndex, btn) {
       btn.disabled = false;
       btn.textContent = originalText;
     }
+    setTimeout(blackboxRefresh, 300);
   });
 };
-window.usbRefresh = usbRefresh;
-usbRefresh();
+window.blackboxDisable = function(targetIndex, btn) {
+  const target = (window._usbTargets || [])[targetIndex];
+  const active = (window._blackboxTargets || []).find(function(item){ return item.device === (target && target.device); });
+  if (!target || !active) {
+    const msg = document.getElementById('usb-msg');
+    msg.style.color = 'var(--err,red)';
+    msg.textContent = 'Error: black-box target not found. Refresh and try again.';
+    return;
+  }
+  const msg = document.getElementById('usb-msg');
+  const row = btn ? btn.closest('td') : null;
+  const rowMsg = row ? row.querySelector('.usb-row-msg') : null;
+  const originalText = btn ? btn.textContent : '';
+  if (btn) {
+    btn.disabled = true;
+    btn.textContent = 'Disabling...';
+  }
+  if (rowMsg) {
+    rowMsg.style.color = 'var(--muted)';
+    rowMsg.textContent = 'Working...';
+  }
+  msg.style.color = 'var(--muted)';
+  msg.textContent = 'Disabling black-box on ' + (target.device||'') + '...';
+  fetch('/api/blackbox/disable', {
+    method:'POST',
+    headers:{'Content-Type':'application/json'},
+    body: JSON.stringify({device: target.device, enrollment_id: active.enrollment_id})
+  }).then(async r => {
+    const d = await r.json();
+    if (!r.ok) throw new Error(d.error || ('HTTP ' + r.status));
+    return d;
+  }).then(d => {
+    msg.style.color = 'var(--ok,green)';
+    msg.textContent = d.message || 'Done.';
+    if (rowMsg) {
+      rowMsg.style.color = 'var(--ok,green)';
+      rowMsg.textContent = d.message || 'Done.';
+    }
+  }).catch(e => {
+    msg.style.color = 'var(--err,red)';
+    msg.textContent = 'Error: '+e;
+    if (rowMsg) {
+      rowMsg.style.color = 'var(--err,red)';
+      rowMsg.textContent = 'Error: ' + e;
+    }
+  }).finally(() => {
+    if (btn) {
+      btn.disabled = false;
+      btn.textContent = originalText;
+    }
+    setTimeout(blackboxRefresh, 300);
+  });
+};
+window.blackboxRefresh = blackboxRefresh;
+blackboxRefresh();
 })();
 </script>`
 }
@@ -382,7 +458,7 @@ function installToRAM() {
 <p style="font-size:13px;color:var(--muted);margin-bottom:12px">Downloads a tar.gz archive of all audit files, SAT results, and logs.</p>
 ` + renderSupportBundleInline() + `
 <div style="border-top:1px solid var(--border);margin-top:16px;padding-top:16px">
-  <div style="font-weight:600;margin-bottom:8px">Export to USB</div>
+  <div style="font-weight:600;margin-bottom:8px">USB Black-Box</div>
   ` + renderUSBExportInline() + `
 </div>
 </div></div>

audit/internal/webui/server.go

@@ -301,8 +301,9 @@ func NewHandler(opts HandlerOptions) http.Handler {
 	// Export
 	mux.HandleFunc("GET /api/export/list", h.handleAPIExportList)
 	mux.HandleFunc("GET /api/export/usb", h.handleAPIExportUSBTargets)
-	mux.HandleFunc("POST /api/export/usb/audit", h.handleAPIExportUSBAudit)
-	mux.HandleFunc("POST /api/export/usb/bundle", h.handleAPIExportUSBBundle)
+	mux.HandleFunc("GET /api/blackbox/status", h.handleAPIBlackboxStatus)
+	mux.HandleFunc("POST /api/blackbox/enable", h.handleAPIBlackboxEnable)
+	mux.HandleFunc("POST /api/blackbox/disable", h.handleAPIBlackboxDisable)
 
 	// Tools
 	mux.HandleFunc("GET /api/tools/check", h.handleAPIToolsCheck)

audit/internal/webui/server_test.go

@@ -671,11 +671,11 @@ func TestToolsPageRendersNvidiaSelfHealSection(t *testing.T) {
 	if !strings.Contains(body, `id="boot-source-text"`) {
 		t.Fatalf("tools page missing boot source field: %s", body)
 	}
-	if !strings.Contains(body, `Export to USB`) {
-		t.Fatalf("tools page missing export to usb section: %s", body)
+	if !strings.Contains(body, `USB Black-Box`) {
+		t.Fatalf("tools page missing usb black-box section: %s", body)
 	}
-	if !strings.Contains(body, `Support Bundle</button>`) {
-		t.Fatalf("tools page missing support bundle usb button: %s", body)
+	if !strings.Contains(body, `/api/blackbox/status`) {
+		t.Fatalf("tools page missing black-box status api usage: %s", body)
 	}
 }
 

bible-local/README.md

@@ -10,4 +10,4 @@ Generic engineering rules live in `bible/rules/patterns/`.
 | `architecture/system-overview.md` | What bee does, scope, tech stack |
 | `architecture/runtime-flows.md` | Boot sequence, audit flow, service order |
 | `docs/hardware-ingest-contract.md` | Current Reanimator hardware ingest JSON contract |
-| `decisions/` | Architectural decision log |
+| `decisions/` | Architectural decision log, including read-only submodule policy |

bible-local/architecture/system-overview.md

@@ -58,6 +58,8 @@ Fills gaps where Redfish/logpile is blind:
 - `bee` should populate current component state, hardware inventory, telemetry, and `status_checked_at`.
 - Historical status transitions and component replacement logic belong to the centralized ingest/lifecycle system, not to `bee`.
 - Contract fields that have no honest local source on a generic Linux host may remain empty.
+- Embedded submodules such as `internal/chart/` and `bible/` are read-only for `bee` feature work.
+- If the UI needs extra information, `bee` must emit it through the standard audit JSON contract rather than patching `chart`.
 
 ## Tech stack
 
@@ -101,7 +103,7 @@ Fills gaps where Redfish/logpile is blind:
 | `iso/builder/` | ISO build scripts and `live-build` profile |
 | `iso/overlay/` | Source overlay copied into a staged build overlay |
 | `iso/vendor/` | Optional pre-built vendor binaries (storcli64, sas2ircu, sas3ircu, arcconf, ssacli, …) |
-| `internal/chart/` | Git submodule with `reanimator/chart`, embedded into `bee web` |
+| `internal/chart/` | Git submodule with `reanimator/chart`, embedded into `bee web`; update by submodule pointer only, never by local `bee`-specific edits |
 | `iso/builder/VERSIONS` | Pinned versions: Debian, Go, NVIDIA driver, kernel ABI |
 | `iso/builder/smoketest.sh` | Post-boot smoke test — run via SSH to verify live ISO |
 | `iso/overlay/etc/profile.d/bee.sh` | tty1 welcome message with web UI URLs |

bible-local/decisions/2026-04-29-read-only-embedded-submodules.md

@@ -0,0 +1,39 @@
+# Decision: Treat embedded submodules as read-only
+
+## Context
+
+`bee` embeds external git submodules such as:
+
+- `internal/chart/` — `reanimator/chart`, a generic read-only viewer for Reanimator JSON snapshots
+- `bible/` — shared engineering rules and contracts
+
+These repositories are reused by other projects. A local feature request in `bee`
+must not be solved by silently changing shared submodule behavior.
+
+The concrete failure mode here was attempting to add project-specific storage
+telemetry presentation by editing `internal/chart/`. That couples a shared viewer
+to one host application's needs and creates hidden cross-project regressions.
+
+## Decision
+
+Embedded submodules are read-only from the point of view of `bee`.
+
+- Do not implement `bee`-specific behavior by editing `internal/chart/`.
+- Do not implement `bee`-specific behavior by editing `bible/`.
+- If `bee` needs new data in the report, produce it in the standard audit JSON
+  emitted by `bee` itself.
+- `chart` must continue to consume the canonical snapshot as an external viewer,
+  without host-specific forks.
+- Updating a submodule pointer to an upstream commit is allowed.
+- Carrying local unmerged submodule commits as part of a `bee` feature is forbidden.
+
+## Consequences
+
+- Audit/report features must be expressed through the contract in
+  `bible-local/docs/hardware-ingest-contract.md`.
+- `bee` owns collection, normalization, and serialization of storage telemetry in
+  `hardware.storage[]`.
+- `chart` remains a pure visualization module that reads the snapshot it is given.
+- If a capability is genuinely missing in a shared submodule, it must be proposed
+  and landed upstream as a generic change first, then pulled into `bee` via a
+  normal submodule update.

bible-local/decisions/README.md

@@ -6,3 +6,4 @@ One file per decision, named `YYYY-MM-DD-short-topic.md`.
 |---|---|---|
 | 2026-03-05 | Use NVIDIA proprietary driver | active |
 | 2026-04-01 | Treat memtest as explicit ISO content | active |
+| 2026-04-29 | Treat embedded submodules as read-only | active |

bible-local/rules/patterns/ascii-safe-text/contract.md

@@ -0,0 +1,31 @@
+# Contract: ASCII-Safe Text in Scripts and Boot Configs
+
+Version: 1.0
+
+## Principle
+
+Shell scripts, bootloader configs, and any text rendered on serial/SOL consoles must use only printable ASCII characters. Non-ASCII Unicode — including typographic punctuation such as the em-dash (U+2014 `—`), en-dash (U+2013 `–`), curly quotes, and ellipsis (U+2026 `…`) — breaks rendering on serial terminals, GRUB text/serial mode, IPMI SOL, and tooling that assumes ASCII.
+
+## Rules
+
+- Never use em-dash (`—`) or en-dash (`–`) in any shell script, GRUB config, syslinux/isolinux config, or service unit file. Use ASCII double-hyphen `--` or single hyphen `-` instead.
+- Never use curly quotes (`"` `"` `'` `'`) in shell scripts or configs. Use straight quotes `"` and `'`.
+- Never use the Unicode ellipsis (`…`). Use `...`.
+- GRUB `menuentry` and `submenu` titles must be ASCII-only — GRUB serial terminal output is ASCII; non-ASCII characters render as garbage or are dropped.
+- Comments in GRUB theme files (`.txt`) must also be ASCII-only, as GRUB may parse the entire file.
+
+## Why
+
+GRUB renders menus over both `gfxterm` (graphical, Unicode-capable) and `serial` (ASCII-only) simultaneously when `terminal_output gfxterm serial` is set. The serial output — used by IPMI SOL and BMC remote consoles — cannot display multi-byte UTF-8 sequences and shows raw bytes or drops characters. A menuentry title `"EASY-BEE — GSP=off"` appears as `"EASY-BEE â€" GSP=off"` or `"EASY-BEE  GSP=off"` on SOL, making the menu unreadable.
+
+## Anti-patterns
+
+- `menuentry "EASY-BEE — GSP=off"` — em-dash in GRUB title
+- `# bee logo — centered` — em-dash in GRUB theme comment
+- `echo "done — reboot"` in a shell script displayed over serial
+
+## Correct form
+
+- `menuentry "EASY-BEE -- GSP=off"`
+- `# bee logo - centered`
+- `echo "done - reboot"`

iso/README.md

@@ -31,10 +31,10 @@ Build with explicit SSH keys baked into the ISO:
 sh iso/builder/build-in-container.sh --authorized-keys ~/.ssh/id_ed25519.pub
 ```
 
-Rebuild the builder image:
+Force a clean rebuild of the builder image and build caches:
 
 ```sh
-sh iso/builder/build-in-container.sh --rebuild-image
+sh iso/builder/build-in-container.sh --clean-build
 ```
 
 Use a custom cache directory:

iso/builder/build-in-container.sh

@@ -10,7 +10,6 @@ IMAGE_TAG="${BEE_BUILDER_IMAGE:-bee-iso-builder}"
 BUILDER_PLATFORM="${BEE_BUILDER_PLATFORM:-linux/amd64}"
 CACHE_DIR="${BEE_BUILDER_CACHE_DIR:-${REPO_ROOT}/dist/container-cache}"
 AUTH_KEYS=""
-REBUILD_IMAGE=0
 CLEAN_CACHE=0
 VARIANT="all"
 
@@ -22,17 +21,12 @@ while [ $# -gt 0 ]; do
             CACHE_DIR="$2"
             shift 2
             ;;
-        --rebuild-image)
-            REBUILD_IMAGE=1
-            shift
-            ;;
         --authorized-keys)
             AUTH_KEYS="$2"
             shift 2
             ;;
         --clean-build)
             CLEAN_CACHE=1
-            REBUILD_IMAGE=1
             shift
             ;;
         --variant)
@@ -41,7 +35,7 @@ while [ $# -gt 0 ]; do
             ;;
         *)
             echo "unknown arg: $1" >&2
-            echo "usage: $0 [--cache-dir /path] [--rebuild-image] [--clean-build] [--authorized-keys /path/to/authorized_keys] [--variant nvidia|nvidia-legacy|amd|nogpu|all]" >&2
+            echo "usage: $0 [--cache-dir /path] [--clean-build] [--authorized-keys /path/to/authorized_keys] [--variant nvidia|nvidia-legacy|amd|nogpu|all]" >&2
             exit 1
             ;;
     esac
@@ -105,7 +99,7 @@ image_matches_platform() {
 }
 
 NEED_BUILD_IMAGE=0
-if [ "$REBUILD_IMAGE" = "1" ]; then
+if [ "$CLEAN_CACHE" = "1" ]; then
     NEED_BUILD_IMAGE=1
 elif ! "$CONTAINER_TOOL" image inspect "${IMAGE_REF}" >/dev/null 2>&1; then
     NEED_BUILD_IMAGE=1

iso/builder/build.sh

@@ -848,6 +848,72 @@ reset_live_build_stage() {
     done
 }
 
+# Marker written after every successful full lb build for this variant
+FULL_BUILD_MARKER="${BUILD_WORK_DIR}/.bee-full-build-marker"
+
+# Returns 0 if full lb build is needed, 1 if fast-path is safe.
+# Fast-path is safe when only light files changed since the last full build
+# (Go source, overlay scripts/configs). Heavy changes (VERSIONS, package lists,
+# hooks, archives, Dockerfile, auto/config) require a full lb build.
+needs_full_build() {
+    [ -f "${FULL_BUILD_MARKER}" ]                                        || return 0
+    [ -f "${BUILD_WORK_DIR}/binary/live/filesystem.squashfs" ]           || return 0
+    [ -f "${BUILD_WORK_DIR}/live-image-amd64.hybrid.iso" ]               || return 0
+
+    _heavy=$(find \
+        "${BUILDER_DIR}/VERSIONS" \
+        "${BUILDER_DIR}/auto/config" \
+        "${BUILDER_DIR}/Dockerfile" \
+        "${BUILDER_DIR}/config/package-lists" \
+        "${BUILDER_DIR}/config/hooks" \
+        "${BUILDER_DIR}/config/archives" \
+        -newer "${FULL_BUILD_MARKER}" 2>/dev/null | head -1)
+
+    if [ -n "$_heavy" ]; then
+        echo "=== full build required: heavy config changed: $(basename "$_heavy") ==="
+        return 0
+    fi
+
+    return 1
+}
+
+# Fast-path: unsquash existing filesystem, rsync overlay on top, repack.
+# Requires ~10 GB free in BEE_CACHE_DIR for the unpacked squashfs.
+fast_path_repack_squashfs() {
+    _sq="${BUILD_WORK_DIR}/binary/live/filesystem.squashfs"
+    _tmp="${BEE_CACHE_DIR}/fast-unsquash-${BUILD_VARIANT}"
+    echo "=== fast-path: unsquash ($(du -sh "$_sq" | cut -f1) compressed) ==="
+    rm -rf "$_tmp"
+    unsquashfs -d "$_tmp" "$_sq"
+    echo "=== fast-path: syncing overlay stage ==="
+    rsync -a --checksum "${OVERLAY_STAGE_DIR}/" "$_tmp/"
+    echo "=== fast-path: repacking squashfs ==="
+    _sq_new="${_sq}.new"
+    rm -f "$_sq_new"
+    mksquashfs "$_tmp" "$_sq_new" -comp zstd -b 1048576 -noappend -no-progress
+    mv "$_sq_new" "$_sq"
+    rm -rf "$_tmp"
+    echo "=== fast-path: squashfs repacked ($(du -sh "$_sq" | cut -f1)) ==="
+}
+
+# Fast-path: rebuild ISO by replacing only live/filesystem.squashfs via xorriso.
+# Boot structure (El Torito, EFI, MBR hybrid) is replayed from the prior ISO.
+fast_path_rebuild_iso() {
+    _sq="${BUILD_WORK_DIR}/binary/live/filesystem.squashfs"
+    _prior="${BUILD_WORK_DIR}/live-image-amd64.hybrid.iso"
+    _new="${BUILD_WORK_DIR}/live-image-amd64.hybrid.iso.new"
+    echo "=== fast-path: rebuilding ISO with xorriso ==="
+    rm -f "$_new"
+    xorriso \
+        -indev  "$_prior" \
+        -outdev "$_new" \
+        -map    "$_sq" /live/filesystem.squashfs \
+        -boot_image any replay \
+        -commit
+    mv "$_new" "$_prior"
+    echo "=== fast-path: ISO rebuilt ==="
+}
+
 recover_iso_memtest() {
     lb_dir="$1"
     iso_path="$2"
@@ -1487,6 +1553,21 @@ if [ -f "${LB_INCLUDES}/root/.ssh/authorized_keys" ]; then
     chmod 600 "${LB_INCLUDES}/root/.ssh/authorized_keys"
 fi
 
+# --- auto fast-path: squashfs surgery if only light files changed ---
+if ! needs_full_build; then
+    echo "=== fast-path build (no heavy config changes since last full build) ==="
+    fast_path_repack_squashfs
+    fast_path_rebuild_iso
+    ISO_RAW="${LB_DIR}/live-image-amd64.hybrid.iso"
+    validate_iso_live_boot_entries "$ISO_RAW"
+    validate_iso_nvidia_runtime "$ISO_RAW"
+    cp "$ISO_RAW" "$ISO_OUT"
+    echo ""
+    echo "=== done (${BUILD_VARIANT}, fast-path) ==="
+    echo "ISO: $ISO_OUT"
+    exit 0
+fi
+
 # --- build ISO using live-build ---
 echo ""
 echo "=== building ISO (variant: ${BUILD_VARIANT}) ==="
@@ -1535,6 +1616,7 @@ if [ -f "$ISO_RAW" ]; then
     validate_iso_live_boot_entries "$ISO_RAW"
     validate_iso_nvidia_runtime "$ISO_RAW"
     cp "$ISO_RAW" "$ISO_OUT"
+    touch "${FULL_BUILD_MARKER}"
     echo ""
     echo "=== done (${BUILD_VARIANT}) ==="
     echo "ISO: $ISO_OUT"

iso/overlay/etc/systemd/system/bee-audit.service

@@ -1,6 +1,6 @@
 [Unit]
 Description=Bee: hardware audit
-After=bee-preflight.service bee-network.service bee-nvidia.service
+After=bee-preflight.service bee-network.service bee-nvidia.service bee-blackbox.service
 
 [Service]
 Type=oneshot

iso/overlay/etc/systemd/system/bee-blackbox.service

@@ -0,0 +1,18 @@
+[Unit]
+Description=Bee: USB black-box log mirror
+After=local-fs.target
+Before=bee-network.service bee-nvidia.service bee-preflight.service bee-audit.service bee-web.service
+StartLimitIntervalSec=0
+
+[Service]
+Type=simple
+ExecStart=/usr/local/bin/bee-log-run /appdata/bee/export/bee-blackbox.log /usr/local/bin/bee blackbox --export-dir /appdata/bee/export --state-file /appdata/bee/export/blackbox-state.json
+Restart=always
+RestartSec=1
+StandardOutput=journal
+StandardError=journal
+OOMScoreAdjust=-900
+Nice=0
+
+[Install]
+WantedBy=multi-user.target

iso/overlay/etc/systemd/system/bee-network.service

@@ -1,6 +1,6 @@
 [Unit]
 Description=Bee: bring up network interfaces via DHCP
-After=local-fs.target
+After=local-fs.target bee-blackbox.service
 Before=network-online.target bee-audit.service
 
 [Service]

iso/overlay/etc/systemd/system/bee-nvidia.service

@@ -1,6 +1,6 @@
 [Unit]
 Description=Bee: load NVIDIA kernel modules and create device nodes
-After=local-fs.target udev.service
+After=local-fs.target udev.service bee-blackbox.service
 Before=bee-audit.service
 
 [Service]

iso/overlay/etc/systemd/system/bee-preflight.service

@@ -1,6 +1,6 @@
 [Unit]
 Description=Bee: runtime preflight self-check
-After=bee-network.service bee-nvidia.service
+After=bee-network.service bee-nvidia.service bee-blackbox.service
 Before=bee-audit.service
 
 [Service]

iso/overlay/etc/systemd/system/bee-web.service

@@ -1,5 +1,6 @@
 [Unit]
 Description=Bee: hardware audit web viewer
+After=bee-blackbox.service
 StartLimitIntervalSec=0
 
 [Service]