signal+lnd: exit with non-zero code on internal shutdown

When lnd auto-shuts down due to an internal error such as a chain
backend health check failure, Main() previously returned nil, causing
the process to exit with code 0. This made it impossible for process
supervisors to distinguish a crash from a clean shutdown.

Add a shutdownRequested flag to signal.Interceptor that is set inside
mainInterruptHandler only when an internal RequestShutdown() is the
first shutdown trigger. This avoids a race where a late internal
request could override an earlier OS signal shutdown. Main() now
returns ErrShutdownRequested in that case, which flows to os.Exit(1)
in cmd/lnd/main.go. User-initiated shutdowns (SIGINT, SIGTERM)
continue to exit with code 0.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Ralf

lnd.go

@@ -141,6 +141,14 @@ var errStreamIsolationWithProxySkip = errors.New(
 	"while stream isolation is enabled, the TOR proxy may not be skipped",
 )
 
+// ErrShutdownRequested is returned from Main when lnd shuts down due to an
+// internal error condition such as a backend health check failure. This
+// ensures the process exits with a non-zero code.
+var ErrShutdownRequested = errors.New(
+	"lnd was shut down due to an internal request (e.g. chain backend " +
+		"failure)",
+)
+
 // Main is the true entry point for lnd. It accepts a fully populated and
 // validated main configuration struct and an optional listener config struct.
 // This function starts all main system components then blocks until a signal
@@ -778,6 +786,10 @@ func Main(cfg *Config, lisCfg ListenerCfg, implCfg *ImplementationCfg,
 		return mkErr("unable to start server", err)
 
 	case <-interceptor.ShutdownChannel():
+		if interceptor.ShutdownWasRequested() {
+			return ErrShutdownRequested
+		}
+
 		return nil
 	}
 
@@ -803,6 +815,11 @@ func Main(cfg *Config, lisCfg ListenerCfg, implCfg *ImplementationCfg,
 	// Wait for shutdown signal from either a graceful server stop or from
 	// the interrupt handler.
 	<-interceptor.ShutdownChannel()
+
+	if interceptor.ShutdownWasRequested() {
+		return ErrShutdownRequested
+	}
+
 	return nil
 }
 

signal/signal.go

@@ -111,6 +111,14 @@ type Interceptor struct {
 	// close this channel.
 	quit chan struct{}
 
+	// shutdownRequested is atomically set to 1 when an internal shutdown
+	// request is the first to trigger shutdown, indicating that the daemon
+	// is shutting down due to an internal error (e.g. backend health check
+	// failure) rather than an external signal. This is a pointer so that
+	// it is shared between the Interceptor value returned by Intercept()
+	// and the goroutine running mainInterruptHandler.
+	shutdownRequested *int32
+
 	// Notifier handles sending shutdown notifications.
 	Notifier Notifier
 }
@@ -127,6 +135,7 @@ func Intercept() (Interceptor, error) {
 		shutdownChannel:        make(chan struct{}),
 		shutdownRequestChannel: make(chan struct{}),
 		quit:                   make(chan struct{}),
+		shutdownRequested:      new(int32),
 	}
 
 	signalsToCatch := []os.Signal{
@@ -179,6 +188,14 @@ func (c *Interceptor) mainInterruptHandler() {
 
 		case <-c.shutdownRequestChannel:
 			log.Infof("Received shutdown request.")
+
+			// Only mark the shutdown as internally requested if
+			// this is the first shutdown trigger. This prevents
+			// a late internal request from overriding a
+			// user-initiated signal shutdown.
+			if !isShutdown {
+				atomic.StoreInt32(c.shutdownRequested, 1)
+			}
 			shutdown()
 
 		case <-c.quit:
@@ -222,6 +239,13 @@ func (c *Interceptor) RequestShutdown() {
 	}
 }
 
+// ShutdownWasRequested returns true if the shutdown was initiated internally
+// via RequestShutdown (e.g. due to a health check failure) rather than by an
+// external OS signal.
+func (c *Interceptor) ShutdownWasRequested() bool {
+	return atomic.LoadInt32(c.shutdownRequested) != 0
+}
+
 // ShutdownChannel returns the channel that will be closed once the main
 // interrupt handler has exited.
 func (c *Interceptor) ShutdownChannel() <-chan struct{} {

signal/signal_test.go

@@ -0,0 +1,81 @@
+package signal
+
+import (
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+// waitForShutdown waits for the interceptor's shutdown channel to close.
+func waitForShutdown(t *testing.T, interceptor Interceptor) {
+	t.Helper()
+
+	select {
+	case <-interceptor.ShutdownChannel():
+	case <-time.After(time.Second):
+		t.Fatal("timed out waiting for shutdown channel")
+	}
+
+	// Allow mainInterruptHandler goroutine to fully exit and reset
+	// the global started flag so the next test can call Intercept().
+	time.Sleep(50 * time.Millisecond)
+}
+
+// TestRequestShutdownSetsFlag tests that calling RequestShutdown sets the
+// shutdownRequested flag, which is used to distinguish internal shutdown
+// requests (e.g. chain backend failure) from external OS signals.
+func TestRequestShutdownSetsFlag(t *testing.T) {
+	interceptor, err := Intercept()
+	require.NoError(t, err)
+
+	// Before any shutdown, the flag should not be set.
+	require.False(t, interceptor.ShutdownWasRequested())
+
+	// Request an internal shutdown.
+	interceptor.RequestShutdown()
+
+	waitForShutdown(t, interceptor)
+
+	// The flag should now be set after the handler processed the request.
+	require.True(t, interceptor.ShutdownWasRequested())
+}
+
+// TestOSSignalDoesNotSetRequestedFlag tests that an OS signal based shutdown
+// does not set the shutdownRequested flag, ensuring a clean exit code 0.
+func TestOSSignalDoesNotSetRequestedFlag(t *testing.T) {
+	interceptor, err := Intercept()
+	require.NoError(t, err)
+
+	// Simulate an OS signal.
+	interceptor.interruptChannel <- nil
+
+	waitForShutdown(t, interceptor)
+
+	// The flag should NOT be set for OS signal shutdowns.
+	require.False(t, interceptor.ShutdownWasRequested())
+}
+
+// TestOSSignalThenRequestShutdownNoFlag tests the race condition where a user
+// sends SIGINT first, and then an internal component calls RequestShutdown.
+// The first shutdown cause (OS signal) should win, so the flag must remain
+// unset and the process should exit with code 0.
+func TestOSSignalThenRequestShutdownNoFlag(t *testing.T) {
+	interceptor, err := Intercept()
+	require.NoError(t, err)
+
+	// Simulate an OS signal to initiate shutdown first.
+	interceptor.interruptChannel <- nil
+
+	// Give mainInterruptHandler time to process the signal and set
+	// isShutdown=true before the internal request arrives.
+	time.Sleep(50 * time.Millisecond)
+
+	// Now an internal component also requests shutdown (late arrival).
+	interceptor.RequestShutdown()
+
+	waitForShutdown(t, interceptor)
+
+	// The flag must NOT be set — the OS signal arrived first.
+	require.False(t, interceptor.ShutdownWasRequested())
+}