engage: add -r flag to reload config of a running squadron (#103)

* engage: add -r flag to reload config of a running squadron

A second `squadron engage` against a config dir that already has a
running instance now errors out with a hint, instead of attempting a
fork that would have failed later in daemon.Fork's IsRunning check.

Passing `-r` / `--reload` to a second `engage` signals the running
daemon over SIGHUP to re-read and validate its config. The reload runs
through the same wsbridge.Client.ReloadConfig path the command center
uses, so it inherits the validate-then-atomic-swap semantics: a broken
config is rejected and the running daemon keeps its previous config.

If `-r` is passed when nothing is running, the flag is noted and ignored
and engage starts squadron normally.

Includes tests for daemon.Reload covering: missing PID file, malformed
PID file, stale PID, and actual SIGHUP delivery to a live process.

* engage -r: notify command center on reload, harden PID checks, ginkgo tests

- Forked daemon now removes its own PID file on graceful shutdown so the
  next `engage` doesn't see a stale PID after a non-`disengage` exit.

- IsRunning gained a ps-based liveness check: the PID file is rejected
  (and cleaned up) unless the live process's command line contains
  `squadron` or `squadtest`. Prevents PID reuse from masking a dead
  daemon as alive.

- Early IsRunning check in runEngage is now gated on !engageForeground so
  the forked child (which runs --foreground and would otherwise see the
  parent-written PID file pointing at itself) doesn't bail out as
  "already running".

- wsbridge.Client.NotifyConfigReloaded(err) pushes an unsolicited
  TypeReloadConfigResult envelope to the command center after every
  SIGHUP-driven reload, reusing the existing wire message shape. Empty
  RequestID signals it's a one-way event, not a response. CC needs to
  handle this push (CC-side change is the user's call).

- Tests converted to ginkgo/gomega:
  * internal/daemon/daemon_ginkgo_test.go covers ClearPid + Reload
  * wsbridge/notify_reload_test.go covers NotifyConfigReloaded (added to
    the existing internal-package suite so we don't add a second
    RunSpecs).

* Docs: document `squadron engage -r` for config reload

- cli/engage.mdx: add -r/--reload to the flags table, a Reloading
  configuration section showing success/failure output, the four-case
  behavior matrix, and what a successful reload actually does (re-reads
  HCL, swaps plugin set, pushes scheduler config, notifies command
  center, leaves in-flight missions untouched).
- cli/disengage.mdx: cross-link to the reload flow so readers who reach
  for `disengage` to apply a config edit see the cheaper alternative.
- compare/langgraph.mdx: replace "restart Squadron" with
  "squadron engage -r" in the plugin auto-build pitch.

* Docs: trim engage -r section

Author: mlund01

cmd/engage.go

@@ -40,6 +40,7 @@ var (
 	engageCCPort     int
 	engageAutoInit   bool
 	engageForeground bool
+	engageReload     bool
 )
 
 const (
@@ -82,6 +83,7 @@ func init() {
 	engageCmd.Flags().IntVar(&engageCCPort, "cc-port", 8080, "Port for the command center")
 	engageCmd.Flags().BoolVar(&engageAutoInit, "init", false, "Auto-initialize Squadron if not already initialized")
 	engageCmd.Flags().BoolVar(&engageForeground, "foreground", false, "Run in foreground (default: run as background service)")
+	engageCmd.Flags().BoolVarP(&engageReload, "reload", "r", false, "Reload the config of an already-running squadron (no-op if not running)")
 }
 
 func runEngage(cmd *cobra.Command, args []string) {
@@ -95,6 +97,24 @@ func runEngage(cmd *cobra.Command, args []string) {
 		os.Exit(1)
 	}
 
+	// Only the user-invoked parent process should check IsRunning. The forked
+	// child runs with --foreground and would otherwise see the PID file the
+	// parent just wrote for it and bail out as "already running".
+	if !engageForeground {
+		running, pid := daemon.IsRunning(engageConfigPath)
+		switch {
+		case running && engageReload:
+			reloadRunningSquadron(pid)
+			return
+		case running:
+			fmt.Fprintf(os.Stderr, "Error: squadron is already running (PID %d).\n", pid)
+			fmt.Fprintln(os.Stderr, "Use 'squadron engage -r' to reload the config, or 'squadron disengage' to stop it.")
+			os.Exit(1)
+		case engageReload:
+			fmt.Println("Squadron is not running — ignoring -r and starting it now.")
+		}
+	}
+
 	if warning, err := validateConfigDir(engageConfigPath); err != nil {
 		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
 		os.Exit(1)
@@ -191,6 +211,13 @@ func runEngage(cmd *cobra.Command, args []string) {
 
 	daemon.ClearReady(engageConfigPath)
 
+	// Forked daemons need to clean up the PID file when they exit so the next
+	// `engage` doesn't see a stale PID. (`disengage` removes it on its own
+	// path, but a crash or signal-driven shutdown would otherwise leave it.)
+	if os.Getenv("SQUADRON_FORKED") == "1" {
+		defer daemon.ClearPid(engageConfigPath)
+	}
+
 	// Resolve the vault passphrase once at startup and keep it in memory for
 	// all later var operations on this process.
 	if config.IsVaultInitialized() {
@@ -392,6 +419,27 @@ func runEngage(cmd *cobra.Command, args []string) {
 		client.Close()
 	}()
 
+	reloads := make(chan os.Signal, 1)
+	signal.Notify(reloads, syscall.SIGHUP)
+	go func() {
+		for {
+			select {
+			case <-shutdown:
+				return
+			case <-reloads:
+				log.Println("SIGHUP received — reloading config")
+				err := client.ReloadConfig()
+				if err != nil {
+					log.Printf("Config reload failed: %v", err)
+					daemon.SignalFailed(engageConfigPath, err)
+				} else {
+					log.Println("Config reload succeeded")
+				}
+				client.NotifyConfigReloaded(err)
+			}
+		}
+	}()
+
 	// Periodic sweep of expired per-run ephemeral memory directories.
 	// Runs hourly; walks the filesystem so the live config isn't needed.
 	go runScratchpadCleanupLoop(shutdown)
@@ -503,6 +551,35 @@ func isContainer() bool {
 	return os.Getenv("SQUADRON_CONTAINER") == "1"
 }
 
+func reloadRunningSquadron(pid int) {
+	absConfigPath, err := filepath.Abs(engageConfigPath)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Error resolving config path: %v\n", err)
+		os.Exit(1)
+	}
+
+	fmt.Printf("Squadron is already running (PID %d). Reloading config from %s...\n", pid, absConfigPath)
+
+	daemon.ClearReady(absConfigPath)
+
+	if _, err := daemon.Reload(absConfigPath); err != nil {
+		fmt.Fprintf(os.Stderr, "Error signaling squadron (PID %d): %v\n", pid, err)
+		os.Exit(1)
+	}
+
+	sp := startSpinner("Validating and applying")
+	ready := daemon.WaitReady(absConfigPath, 30*time.Second, 500*time.Millisecond)
+	sp.Stop()
+
+	if !ready.OK {
+		fmt.Fprintf(os.Stderr, "Config reload failed: %s\n", ready.Error)
+		fmt.Fprintf(os.Stderr, "Squadron is still running with the previous config (PID %d). Fix the error above and re-run 'squadron engage'.\n", pid)
+		os.Exit(1)
+	}
+
+	fmt.Println("Config reloaded successfully.")
+}
+
 func hasHCLFiles(configPath string) bool {
 	info, err := os.Stat(configPath)
 	if err != nil {

docs/content/cli/disengage.mdx

@@ -39,4 +39,4 @@ squadron disengage -c /path/to/other-project
 
 ## See Also
 
-- [engage](/cli/engage) — Start the daemon
+- [engage](/cli/engage) — Start the daemon, or reload its config with `-r`

docs/content/cli/engage.mdx

@@ -39,6 +39,7 @@ Multiple projects can run simultaneously on the same host — each gets its own
 | Flag | Description |
 |------|-------------|
 | `-c, --config` | Path to config directory (default: `.`) |
+| `-r, --reload` | Reload the config of an already-running Squadron (see [Reloading configuration](#reloading-configuration)) |
 | `--headless` | Skip launching the local command center UI |
 | `--cc-port` | Port for the local command center (default: `8080`) |
 | `--foreground` | Run in the terminal instead of forking to background |
@@ -89,6 +90,16 @@ Keeps the process attached to the terminal. Useful for debugging or when running
 squadron engage --cc-port 9090
 ```
 
+## Reloading configuration
+
+After editing your HCL files, reload the running daemon in place:
+
+```bash
+squadron engage -r
+```
+
+The new config is validated first; if it's bad, the running daemon keeps its previous config and the command prints the error. In-flight missions and chat sessions keep running on the config they started with.
+
 ## Stopping
 
 ```bash

docs/content/compare/langgraph.mdx

@@ -122,7 +122,7 @@ Why plugins matter relative to LangGraph's "tools are Python functions in the sa
 
 - **Two languages, picked per problem.** Go for performance-critical or systems-level tools (a browser controller, a network scanner, anything CPU-heavy or needing static binary distribution). Python for things that lean on the existing PyPI ecosystem (a pandas pipeline, a model adapter, a domain SDK).
 - **Process isolation.** A misbehaving plugin can't crash the runtime — gRPC failure mode is a clean error returned to the agent, not a Python exception unwinding through your orchestrator.
-- **Auto-build from source.** Edit `./plugin_scraper/main.go`, restart Squadron, and the plugin rebuilds. Content-hash caching skips the rebuild when nothing changed. No `pip install -e .` cycle, no Docker layer to rebuild.
+- **Auto-build from source.** Edit `./plugin_scraper/main.go`, reload Squadron with `squadron engage -r`, and the plugin rebuilds. Content-hash caching skips the rebuild when nothing changed. No `pip install -e .` cycle, no Docker layer to rebuild.
 - **Stateful across tasks.** Plugins are cached globally for the lifetime of the process. A Playwright plugin can open a browser in task 1 and reuse it in task 5 — the runtime tracks the plugin connection, not the per-task call.
 - **Typed schemas.** Each plugin declares tool input/output schemas; Squadron uses those for native LLM function-calling and for output validation.
 - **Distributable.** Plugins compile to a single binary (Go) or a venv (Python) and are publishable as GitHub releases. Other Squadron configs reference them via `source = "github.com/owner/repo"` and Squadron auto-installs.

internal/daemon/daemon.go

@@ -51,6 +51,12 @@ func ClearReady(configPath string) {
 	os.Remove(ReadyFilePath(configPath))
 }
 
+// ClearPid removes the PID file. Called by the forked daemon on graceful
+// shutdown so the next `engage` doesn't see a stale PID.
+func ClearPid(configPath string) {
+	os.Remove(PidFilePath(configPath))
+}
+
 // CleanupFailedFork removes the PID and ready files for a fork where the child
 // signaled failure (and has already exited on its own).
 func CleanupFailedFork(configPath string) {
@@ -180,6 +186,36 @@ func Fork(configPath string, extraFlags []string) (int, error) {
 	return pid, nil
 }
 
+// Reload sends SIGHUP to the running daemon to trigger a config reload.
+func Reload(configPath string) (int, error) {
+	absConfig, err := filepath.Abs(configPath)
+	if err != nil {
+		return 0, fmt.Errorf("could not resolve config path: %w", err)
+	}
+
+	pidPath := PidFilePath(absConfig)
+	data, err := os.ReadFile(pidPath)
+	if err != nil {
+		return 0, fmt.Errorf("no PID file found — squadron may not be running")
+	}
+
+	pid, err := strconv.Atoi(strings.TrimSpace(string(data)))
+	if err != nil {
+		return 0, fmt.Errorf("invalid PID file")
+	}
+
+	process, err := os.FindProcess(pid)
+	if err != nil {
+		return 0, fmt.Errorf("process %d not found", pid)
+	}
+
+	if err := process.Signal(syscall.SIGHUP); err != nil {
+		return 0, fmt.Errorf("could not signal process %d: %w", pid, err)
+	}
+
+	return pid, nil
+}
+
 // Stop reads the PID file and gracefully stops the background process.
 func Stop(configPath string) error {
 	absConfig, err := filepath.Abs(configPath)
@@ -230,6 +266,8 @@ func Stop(configPath string) error {
 }
 
 // IsRunning checks if a Squadron process is running for the given config path.
+// Verifies via ps that the PID belongs to a squadron-ish binary, so a recycled
+// PID from an unrelated process isn't mistaken for a live daemon.
 func IsRunning(configPath string) (bool, int) {
 	absConfig, _ := filepath.Abs(configPath)
 	pidPath := PidFilePath(absConfig)
@@ -249,16 +287,36 @@ func IsRunning(configPath string) (bool, int) {
 		return false, 0
 	}
 
-	// Check if process is actually alive
 	if err := process.Signal(syscall.Signal(0)); err != nil {
-		// Stale PID file — clean up
+		os.Remove(pidPath)
+		return false, 0
+	}
+
+	if !isSquadronProcess(pid) {
 		os.Remove(pidPath)
 		return false, 0
 	}
 
 	return true, pid
 }
 
+// isSquadronProcess returns true if the given PID belongs to a squadron-like
+// binary (matches "squadron" or "squadtest" in its command line). Falls back
+// to permissive true if ps is unavailable.
+func isSquadronProcess(pid int) bool {
+	out, err := exec.Command("ps", "-p", strconv.Itoa(pid), "-o", "command=").Output()
+	if err != nil {
+		// ps not available (unusual on macOS/Linux) — skip the check rather
+		// than refuse to reload.
+		return true
+	}
+	cmd := strings.ToLower(strings.TrimSpace(string(out)))
+	if cmd == "" {
+		return false
+	}
+	return strings.Contains(cmd, "squadron") || strings.Contains(cmd, "squadtest")
+}
+
 // resolveConfigDir returns the directory component of a config path.
 func resolveConfigDir(configPath string) string {
 	info, err := os.Stat(configPath)

internal/daemon/daemon_ginkgo_test.go

@@ -0,0 +1,88 @@
+package daemon
+
+import (
+	"fmt"
+	"os"
+	"os/signal"
+	"path/filepath"
+	"syscall"
+	"testing"
+	"time"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+func TestDaemonSpecs(t *testing.T) {
+	RegisterFailHandler(Fail)
+	RunSpecs(t, "Daemon Suite")
+}
+
+var _ = Describe("ClearPid", func() {
+	It("removes the PID file", func() {
+		dir := GinkgoT().TempDir()
+		Expect(os.MkdirAll(filepath.Join(dir, ".squadron"), 0755)).To(Succeed())
+		Expect(os.WriteFile(PidFilePath(dir), []byte("12345"), 0644)).To(Succeed())
+
+		ClearPid(dir)
+
+		_, err := os.Stat(PidFilePath(dir))
+		Expect(os.IsNotExist(err)).To(BeTrue(), "PID file should be gone after ClearPid")
+	})
+
+	It("is a no-op when no PID file exists", func() {
+		Expect(func() { ClearPid(GinkgoT().TempDir()) }).NotTo(Panic())
+	})
+})
+
+var _ = Describe("Reload", func() {
+	Context("when the PID file is missing", func() {
+		It("returns an error", func() {
+			_, err := Reload(GinkgoT().TempDir())
+			Expect(err).To(HaveOccurred())
+		})
+	})
+
+	Context("when the PID file is malformed", func() {
+		It("returns an error", func() {
+			dir := GinkgoT().TempDir()
+			Expect(os.MkdirAll(filepath.Join(dir, ".squadron"), 0755)).To(Succeed())
+			Expect(os.WriteFile(PidFilePath(dir), []byte("not-a-pid"), 0644)).To(Succeed())
+
+			_, err := Reload(dir)
+			Expect(err).To(HaveOccurred())
+		})
+	})
+
+	Context("when the target process does not exist", func() {
+		It("returns an error", func() {
+			dir := GinkgoT().TempDir()
+			Expect(os.MkdirAll(filepath.Join(dir, ".squadron"), 0755)).To(Succeed())
+			// A high PID that almost certainly doesn't exist.
+			Expect(os.WriteFile(PidFilePath(dir), []byte("999999"), 0644)).To(Succeed())
+
+			_, err := Reload(dir)
+			Expect(err).To(HaveOccurred())
+		})
+	})
+
+	Context("when the target process is alive", func() {
+		It("delivers SIGHUP to the recorded PID", func() {
+			dir := GinkgoT().TempDir()
+			Expect(os.MkdirAll(filepath.Join(dir, ".squadron"), 0755)).To(Succeed())
+
+			pid := os.Getpid()
+			Expect(os.WriteFile(PidFilePath(dir), []byte(fmt.Sprintf("%d", pid)), 0644)).To(Succeed())
+
+			sigs := make(chan os.Signal, 1)
+			signal.Notify(sigs, syscall.SIGHUP)
+			DeferCleanup(func() { signal.Stop(sigs) })
+
+			gotPID, err := Reload(dir)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(gotPID).To(Equal(pid))
+
+			Eventually(sigs, 2*time.Second).Should(Receive())
+		})
+	})
+})

internal/daemon/daemon_test.go

@@ -205,18 +205,20 @@ func TestIsRunning_LiveProcess(t *testing.T) {
 		t.Fatal(err)
 	}
 
-	// The current test process is definitely alive.
+	// The current test process is definitely alive. Its command line will be
+	// the `go test` binary (e.g. /tmp/.../daemon.test) — not "squadron", so
+	// IsRunning should reject it.
 	pid := os.Getpid()
 	if err := os.WriteFile(PidFilePath(dir), []byte(fmt.Sprintf("%d", pid)), 0644); err != nil {
 		t.Fatal(err)
 	}
 
-	running, got := IsRunning(dir)
-	if !running {
-		t.Error("IsRunning false for a live process")
+	running, _ := IsRunning(dir)
+	if running {
+		t.Error("IsRunning should reject a live non-squadron PID (PID-reuse protection)")
 	}
-	if got != pid {
-		t.Errorf("pid = %d, want %d", got, pid)
+	if _, err := os.Stat(PidFilePath(dir)); !os.IsNotExist(err) {
+		t.Errorf("PID file should be cleaned up after rejection")
 	}
 }