Tighten fallback latency + alert UI on degraded states

Submit-first ordering. Patch 0004 now calls generator_submitblock
BEFORE writing the pending-block hex to disk. The happy path adds zero
disk I/O — we only dump when the primary returned false. The same
patch bounds generator_submitblock's "no live current_si" spin to
~3s instead of the original infinite loop, so a permanently-down
primary doesn't pin the stratifier; the bounded spin lets the caller
return false and lets local_block_submit dump for kamado-api to take
over.

Default grace lowered from 30s to 3s. With ckpool's bounded spin and
sub-second sweep cadence, the fallback now reacts within ~4s of a
failed primary submit — fast enough that the work is still relevant
for the current chain tip. The submitter's sweep poll dropped to 1s
to match.

UI HealthBanners. New top-of-page strip surfaces:
  * Fallback used (red banner, 24h after most recent event):
    "primary bitcoind didn't accept; backup X took over Y ago"
  * Submit gap (orange banner, only when no recent fallback):
    "N blocks attempted but unconfirmed — configure backups"
  * ZMQ stale (orange banner): no hashblock frame in 30+ minutes
Operators see degraded-but-not-fatal states without checking logs.

Startup readiness gate. main now waits up to 8s on agg.Ready() before
starting the HTTP server so the very first /api/snapshot doesn't show
all-zero state during the aggregator's first refresh. Capped so a
permanently-down bitcoind can't block startup; /healthz is honest
about the degraded state once we do start serving.

api/cmd/kamado-api/main.go

@@ -134,11 +134,28 @@ func main() {
 				agg.RecordFallbackSubmit(height, viaLabel)
 			},
 		}
-		go sub.Run(ctx, 5*time.Second)
+		// Sweep every second so we react within ~grace+1s of a
+		// failed submit. Reading an empty directory is cheap.
+		go sub.Run(ctx, 1*time.Second)
 	} else {
 		log.Info("blocksubmit fallback disabled (PENDING_BLOCKS_DIR not set)")
 	}
 
+	// Wait briefly for the aggregator's first refresh to complete so
+	// the very first /api/snapshot or /api/health hit doesn't see an
+	// all-zeros snapshot and report bitcoin_ok=false during its own
+	// initialization. Cap the wait so a permanently-down bitcoind
+	// can't block startup forever — /healthz is honest about the
+	// degraded state.
+	select {
+	case <-agg.Ready():
+		log.Info("first snapshot ready")
+	case <-time.After(8 * time.Second):
+		log.Warn("first snapshot not ready within 8s, serving HTTP anyway (snapshot will be partial until backends respond)")
+	case <-ctx.Done():
+		return
+	}
+
 	srv := &http.Server{
 		Addr:              cfg.ListenAddr,
 		Handler:           api.Handler(),

api/internal/blocksubmit/submit.go

@@ -71,7 +71,11 @@ func (s *Submitter) Run(ctx context.Context, poll time.Duration) {
 		return
 	}
 	if s.Grace == 0 {
-		s.Grace = 30 * time.Second
+		// Match the config default — short enough that a failed
+		// submit gets recovered while the work is still relevant,
+		// long enough that we don't spuriously fallback while the
+		// primary's RPC is mid-handshake.
+		s.Grace = 3 * time.Second
 	}
 	if s.MaxAge == 0 {
 		s.MaxAge = 24 * time.Hour

api/internal/config/config.go

@@ -52,8 +52,13 @@ type Config struct {
 	BackupRPCURLs string
 
 	// How long a pending block file must persist before the submitter
-	// will try fallback RPCs. Defaults to 30s — long enough for
-	// ckpool's own retry loop and a fast ckpool->bitcoind round-trip.
+	// will try fallback RPCs. Defaults to 3s — short enough that a
+	// failed submit is recovered while the work is still relevant,
+	// long enough that ckpool's bounded internal wait (~3s for a live
+	// primary server) and a single slow round-trip don't trigger a
+	// spurious fallback. Patch 0004 makes ckpool's submit return false
+	// rather than spinning indefinitely, so we no longer need to wait
+	// for that case to time out.
 	PendingBlocksGrace time.Duration
 }
 
@@ -73,7 +78,7 @@ func FromEnv() (*Config, error) {
 
 		PendingBlocksDir:   os.Getenv("PENDING_BLOCKS_DIR"),
 		BackupRPCURLs:      os.Getenv("BACKUP_RPC_URLS"),
-		PendingBlocksGrace: getenvDuration("PENDING_BLOCKS_GRACE", 30*time.Second),
+		PendingBlocksGrace: getenvDuration("PENDING_BLOCKS_GRACE", 3*time.Second),
 	}
 
 	if cfg.BitcoinRPCURL == "" {

api/internal/state/aggregator.go

@@ -185,6 +185,12 @@ type Aggregator struct {
 	// escalate to WARN.
 	ckFailStreak int
 
+	// readyOnce + ready closes the Ready() channel exactly once after
+	// the first refresh completes. main blocks briefly on this so the
+	// HTTP server doesn't serve a never-refreshed (all-zeros) snapshot.
+	readyOnce sync.Once
+	ready     chan struct{}
+
 	// Submit-attempt vs confirmed counters. Persisted in kv so the
 	// running gap survives restarts. Both are monotonic.
 	blockSubmitAttempts   int64
@@ -210,9 +216,21 @@ func New(ck *ckpool.Client, rpc *bitcoind.RPC, interval time.Duration, log *slog
 		RPC:      rpc,
 		Interval: interval,
 		Log:      log,
+		ready:    make(chan struct{}),
 	}
 }
 
+// Ready returns a channel that's closed once the aggregator has
+// completed its first refresh — used by main to delay HTTP serving
+// until /api/snapshot reflects real state instead of zeros.
+func (a *Aggregator) Ready() <-chan struct{} {
+	return a.ready
+}
+
+func (a *Aggregator) markReady() {
+	a.readyOnce.Do(func() { close(a.ready) })
+}
+
 // Run blocks until ctx is cancelled, refreshing the snapshot every Interval.
 // It runs one immediate refresh at startup so readers don't see an empty
 // snapshot after ctx launches the goroutine. Persisted block history is
@@ -486,6 +504,7 @@ func (a *Aggregator) refresh(ctx context.Context) {
 	if cb != nil {
 		cb(pushed)
 	}
+	a.markReady()
 }
 
 // loadPersistedState restores cumulative work and hashrate history from