CB-559: re-read bridged.yaml without restarting the daemon

Tuning a fleet meant restarting bridged, and a restart tears down every lead and worker it owns. Changing one pool's weight cost the whole fleet's state, so in practice nobody changed it. ConfigRef holds the live BridgedConfig in an AtomicReference. Consumers read it at the point of use, so a change reaches the next spawn with nothing rebuilt. The launchers that used to capture config into fields now take suppliers: the fleet tabLabel template, the profile map, the placement policy and the fleet block. Keys fall into three classes, and the difference is what already exists when the reload happens: hot fleet: (pools + tabLabel), placement:, and an existing profile's weight / maxLoad / model / tabLabel — live on the next spawn. deferred lifecycle:, leadHeartbeat:, guard:, worktreeRoot:, spawnReady*, and adding/removing a profile — accepted, but the startup wiring keeps the old value. The reload logs these by name. cold bind:, herdrSocket:, broker:, auth: — refuses the WHOLE reload. A cold change refuses everything rather than applying the hot half. A half-applied reload leaves the daemon matching no file on disk, which is the worst thing a reload can do to an operator reading that file to work out what the daemon is doing. Refusing keeps the invariant that the live config is always some version of the file. A parse failure or a failed startup validator is refused the same way, and the running config stays live: a file being saved is sometimes read mid-write, and degrading a working daemon over a half-written file is a bad trade. The same four validators startup runs are re-run, so a config that could not have booted cannot slip in through a reload. ConfigWatcher polls the modified time on a daemon thread, opt-in through configReload.enabled (default off, so an upgraded daemon is unchanged). It stamps the timestamp BEFORE reloading, so a refused file is not retried every tick — the next save earns a fresh attempt. A missing file is skipped silently, because editors unlink briefly mid-save. MicroProfile Config was the first idea and does not fit: @ConfigMapping needs interfaces, resolves once at bootstrap, and reload would still mean rebuild and swap. The port would also lose the raw-YAML duplicate-key detection, since duplicates have already collapsed once the tree is flattened to properties. 634 tests.
2026-08-14 18:23:32 +02:00
parent 57f8fa257a
commit a2108a8a14
12 changed files with 942 additions and 41 deletions
@@ -1,6 +1,8 @@
 package dev.ltms.bridged;

 import dev.ltms.bridged.config.BridgedConfig;
+import dev.ltms.bridged.config.ConfigRef;
+import dev.ltms.bridged.config.ConfigWatcher;
 import dev.ltms.bridged.guard.SubscriptionGuard;
 import dev.ltms.bridged.herdr.AgentControl;
 import dev.ltms.bridged.herdr.HerdrClient;
@@ -37,7 +39,6 @@ import dev.ltms.bridged.session.SessionManager;
 import dev.ltms.bridged.peer.PeerLauncher;
 import dev.ltms.bridged.session.SessionReaper;
 import dev.ltms.bridged.member.ClaudeCodeLauncher;
-import dev.ltms.bridged.placement.PlacementPolicies;
 import dev.ltms.bridged.member.CompositePeerLauncher;
 import dev.ltms.bridged.member.HerdrPeerLauncher;
 import dev.ltms.bridged.member.OpenCodeLauncher;
@@ -79,6 +80,11 @@ public final class Bridged {
    static void main(String[] args) {
        Path configPath = Path.of(args.length > 0 ? args[0] : "bridged.yaml");
        BridgedConfig cfg = BridgedConfig.load(configPath);
+        // CB-559: `cfg` stays the startup snapshot — every validation and every piece of one-time
+        // wiring below reads it, and must, because those decisions cannot be unmade. `config` is the
+        // live reference the hot paths read per use. Which keys can actually move is ConfigRef's
+        // contract; adding a reader here does not make a key reloadable by itself.
+        ConfigRef config = new ConfigRef(configPath, cfg);

        // The primary/host env that launched bridged must not be tainted.
        SubscriptionGuard guard = new SubscriptionGuard(cfg.guard().hostSet());
@@ -125,22 +131,20 @@ public final class Bridged {
            adapters.add(new ClaudeCodeLauncher(agents, spaces, guard,
                    claudeProfiles, cfg.effectiveDefaultProfile(), System::getenv,
                    cfg.spawnReadyTimeoutMs(), cfg.spawnReadyPollMs(),
-                    cfg.fleet().tabLabel()));
+                    () -> config.get().fleet().tabLabel()));
        }
        if (!opencodeProfiles.isEmpty()) {
            adapters.add(new OpenCodeLauncher(agents, spaces,
                    opencodeProfiles, cfg.effectiveDefaultProfile(), System::getenv,
                    cfg.spawnReadyTimeoutMs(), cfg.spawnReadyPollMs(),
-                    cfg.fleet().tabLabel()));
+                    () -> config.get().fleet().tabLabel()));
        }
        AtomicReference<Function<String, Integer>> liveCountRef = new AtomicReference<>(_ -> 0);
        PeerLauncher workers = new CompositePeerLauncher(
                adapters,
                cfg.effectiveDefaultProfile(),
-                cfg.profiles(),
-                PlacementPolicies.fromName(cfg.placement()),
-                profileName -> liveCountRef.get().apply(profileName),
-                cfg.fleet());
+                config,
+                profileName -> liveCountRef.get().apply(profileName));
        // CB-504: under supervision (launchd/systemd) bridged can start before herdr's socket
        // exists. The client itself is lazy — it connects per call — but the orphan reap below is
        // the first thing that actually talks to herdr, so without this wait a boot-order race
@@ -384,6 +388,16 @@ public final class Bridged {
        BridgeMcp mcp = new BridgeMcp(messages, workers, sessions, identity, presence,
                primaryRegistry, callers, metrics);

+        // CB-559: opt-in config reload. With no `configReload:` block nothing is constructed, so an
+        // upgraded daemon behaves exactly as before — the file is read once at boot and never again.
+        final ConfigWatcher configWatcher;
+        if (cfg.configReload() != null && cfg.configReload().isEnabled()) {
+            configWatcher = new ConfigWatcher(config, cfg.configReload().intervalSeconds());
+            configWatcher.start();
+        } else {
+            configWatcher = null;
+        }
+
        // CB-303 part 3: single ordered shutdown hook. Drain sessions first while herdr is still
        // open (so releases reach the daemon), then stop poller/message/mcp/reaper, and close herdr
        // last. This replaces the earlier independent hooks that could race and close herdr early.
@@ -393,6 +407,7 @@ public final class Bridged {
            messages.close();
            pushLoop.close();
            if (heartbeat != null) heartbeat.close(); // CB-551: stop the idle-lead heartbeat scheduler
+            if (configWatcher != null) configWatcher.stop(); // CB-559: stop polling the config file
            mcp.close();
            if (reaper != null) reaper.stop();
            // Release the broker connection last among message resources (no-op for the in-memory inbox).
@@ -74,7 +74,17 @@ public record BridgedConfig(
        Fleet fleet,
        LeadHeartbeat leadHeartbeat,
        String placement,
-        Auth auth) {
+        Auth auth,
+        ConfigReload configReload) {
+
+    /** Back-compat 14-arg form — no {@code configReload:} block, so file watching stays off. */
+    public BridgedConfig(Bind bind, String herdrSocket, Map<String, Profile> profiles, Guard guard,
+                         String worktreeRoot, Lifecycle lifecycle, Integer spawnReadyTimeoutMs,
+                         Integer spawnReadyPollMs, Broker broker, Primary primary, Fleet fleet,
+                         LeadHeartbeat leadHeartbeat, String placement, Auth auth) {
+        this(bind, herdrSocket, profiles, guard, worktreeRoot, lifecycle, spawnReadyTimeoutMs,
+                spawnReadyPollMs, broker, primary, fleet, leadHeartbeat, placement, auth, null);
+    }

    /**
     * Normalize {@code profiles} once, at construction, so every reader sees the same map.
@@ -622,6 +632,31 @@ public record BridgedConfig(
        }
    }

+    /**
+     * Watch {@code bridged.yaml} and re-read it when it changes (CB-559).
+     *
+     * <p>Opt-in, like every other block that acts on its own initiative. A daemon that reloads
+     * whenever a file is saved would apply a half-finished edit the moment an editor writes it, and
+     * an operator who did not ask for that has no reason to expect it. Absent block = off, and the
+     * config is read exactly once at startup as it always was.
+     *
+     * <p>Which keys a reload can actually change — and which refuse it — is
+     * {@link ConfigRef}'s contract, not this block's. This only decides <em>when</em> to look.
+     *
+     * @param enabled         false (or an absent block) leaves the startup-only behaviour
+     * @param intervalSeconds how often the file's modified time is checked; defaults to 10
+     */
+    public record ConfigReload(Boolean enabled, Integer intervalSeconds) {
+        public ConfigReload {
+            enabled = enabled != null && enabled;
+            intervalSeconds = (intervalSeconds == null || intervalSeconds <= 0) ? 10 : intervalSeconds;
+        }
+
+        public boolean isEnabled() {
+            return Boolean.TRUE.equals(enabled);
+        }
+    }
+
    /**
     * The terminal → lead-name map that {@link dev.ltms.bridged.auth.CallerResolver} resolves
     * against, merging the {@code leaders:} registry with the legacy singular {@code primary:} pin.
@@ -749,7 +784,7 @@ public record BridgedConfig(
    private static final Set<String> KNOWN_TOP_LEVEL_KEYS = Set.of(
            "bind", "herdrSocket", "profiles", "guard", "worktreeRoot",
            "lifecycle", "spawnReadyTimeoutMs", "spawnReadyPollMs", "broker", "primary", "fleet",
-            "leadHeartbeat", "placement", "auth");
+            "leadHeartbeat", "placement", "auth", "configReload");

    /** Load and validate config from {@code path}. */
    public static BridgedConfig load(Path path) {
@@ -1015,8 +1050,11 @@ public record BridgedConfig(
        // leadHeartbeat is left as-is (CB-551): null is "off", and LeadHeartbeat's own compact
        // constructor defaults the fields of a block that IS present. Defaulting it here would
        // switch the feature on for every config that never mentioned it.
+        // configReload is left as-is: null is "off", and ConfigReload's own compact constructor
+        // defaults the fields of a block that IS present. Defaulting it here would start watching
+        // the file for every config that never asked to be watched.
        return new BridgedConfig(b, herdrSocket, profiles, g, worktreeRoot, l, timeout, pollMs,
-                broker, primary, f, leadHeartbeat, placementOrDefault, a);
+                broker, primary, f, leadHeartbeat, placementOrDefault, a, configReload);
    }

    /**
@@ -0,0 +1,219 @@
+package dev.ltms.bridged.config;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Objects;
+import java.util.Set;
+import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.Supplier;
+
+/**
+ * The daemon's live configuration, re-readable without a restart (CB-559).
+ *
+ * <p>Consumers hold this, not a {@link BridgedConfig}, and read through {@link #get()} at the point
+ * of use. A component that captures {@code ref.get()} into a field at construction has opted out of
+ * reload — which is sometimes right (see <em>deferred</em> below), but it must then be a deliberate
+ * choice rather than an accident of where the field was initialised.
+ *
+ * <h2>Not every key can change under a running daemon</h2>
+ * Keys fall into three classes, and the difference is about what already exists when the reload
+ * happens — not about how important the key is.
+ *
+ * <ul>
+ *   <li><strong>Hot</strong> — re-read per use, so a reload takes effect on the next spawn:
+ *       {@code fleet:} (every role pool and {@code tabLabel}), {@code placement:}, and an existing
+ *       profile's {@code weight} / {@code maxLoad} / {@code model} / {@code tabLabel}.</li>
+ *   <li><strong>Deferred</strong> — accepted into the new snapshot, but the wiring built at startup
+ *       keeps the old value until a restart: {@code lifecycle:}, {@code leadHeartbeat:},
+ *       {@code spawnReadyTimeoutMs} / {@code spawnReadyPollMs}, {@code guard:},
+ *       {@code worktreeRoot:}, and <em>adding or removing</em> a profile (a new backend needs its
+ *       own launcher, which is constructed once). A reload logs these rather than pretending they
+ *       applied.</li>
+ *   <li><strong>Cold</strong> — cannot change at all under a running daemon: {@code bind:},
+ *       {@code herdrSocket:}, {@code broker:} and {@code auth:}. The socket is bound, the broker
+ *       connection is open, and the auth mode decides who may reach the port that is already
+ *       listening.</li>
+ * </ul>
+ *
+ * <p><strong>A cold change refuses the whole reload.</strong> Not the hot half applied and the cold
+ * half warned about: that would leave the running daemon in a state matching no file on disk, which
+ * is the worst thing a reload can do to an operator debugging one. Refusing keeps the invariant that
+ * the live config is always some version of the file, and the message names the keys that must
+ * change through a restart.
+ *
+ * <p>A reload that fails to parse or fails validation is also refused, and the previous config keeps
+ * running. A config file being edited is normally read once mid-save; degrading a working daemon
+ * because it caught a half-written file would be a bad trade.
+ */
+public final class ConfigRef implements Supplier<BridgedConfig> {
+
+    private static final Logger log = LoggerFactory.getLogger(ConfigRef.class);
+
+    /** Keys that cannot change under a running daemon — see the class doc. */
+    private static final Set<String> COLD_KEYS =
+            Set.of("bind", "herdrSocket", "broker", "auth");
+
+    private final Path path;
+    private final AtomicReference<BridgedConfig> current;
+
+    public ConfigRef(Path path, BridgedConfig initial) {
+        this.path = path;
+        this.current = new AtomicReference<>(Objects.requireNonNull(initial, "initial config"));
+    }
+
+    /** A fixed reference that never reloads — for tests and for wiring built from a config in code. */
+    public static ConfigRef fixed(BridgedConfig cfg) {
+        return new ConfigRef(null, cfg);
+    }
+
+    /** The live configuration. Read this per use; do not cache it in a field. */
+    @Override
+    public BridgedConfig get() {
+        return current.get();
+    }
+
+    /** The file this ref reloads from, or {@code null} for a {@link #fixed} ref. */
+    public Path path() {
+        return path;
+    }
+
+    /**
+     * What a reload attempt did.
+     *
+     * @param applied  true when the new config is now live
+     * @param coldKeys cold keys whose value changed, which is why an unapplied reload was refused
+     * @param deferred keys that changed and were accepted, but whose effect waits for a restart
+     * @param error    the parse or validation failure that refused the reload, else {@code null}
+     */
+    public record Outcome(boolean applied, List<String> coldKeys, List<String> deferred,
+                          String error) {
+
+        public Outcome {
+            coldKeys = List.copyOf(coldKeys);
+            deferred = List.copyOf(deferred);
+        }
+
+        static Outcome refusedCold(List<String> keys) {
+            return new Outcome(false, keys, List.of(), null);
+        }
+
+        static Outcome failed(String error) {
+            return new Outcome(false, List.of(), List.of(), error);
+        }
+
+        /** A one-line summary for the operator — the reason, not just the verdict. */
+        public String summary() {
+            if (error != null) {
+                return "config reload refused — " + error;
+            }
+            if (!applied) {
+                return "config reload refused — these keys cannot change under a running daemon: "
+                        + String.join(", ", coldKeys) + ". Restart bridged to apply them.";
+            }
+            if (!deferred.isEmpty()) {
+                return "config reloaded; these changes need a restart to take effect: "
+                        + String.join(", ", deferred);
+            }
+            return "config reloaded";
+        }
+    }
+
+    /**
+     * Re-read the file, validate it, and swap it in when nothing cold changed.
+     *
+     * <p>Never throws: a reload is a best-effort operation on a daemon that is already serving, and
+     * a bad edit must not take it down. Every failure path leaves the previous config live and is
+     * reported through the returned {@link Outcome}.
+     */
+    public Outcome reload() {
+        if (path == null) {
+            return Outcome.failed("this config was built in code and has no file to reload from");
+        }
+        BridgedConfig old = current.get();
+        BridgedConfig fresh;
+        try {
+            fresh = BridgedConfig.load(path);
+            // The same gate startup runs. A config that would have refused to boot must not be able
+            // to slip in through a reload — that is how a daemon ends up in a state it could never
+            // have started in, which is the hardest kind to debug.
+            fresh.validateAuthExposure();
+            fresh.validateLeadTabPrefixes();
+            fresh.validateSubscriptionProfiles();
+            fresh.validateMembers();
+        } catch (RuntimeException e) {
+            String msg = e.getMessage() == null ? e.toString() : e.getMessage();
+            log.warn("config reload from {} refused, keeping the running config: {}", path, msg);
+            return Outcome.failed(msg);
+        }
+
+        List<String> cold = changedColdKeys(old, fresh);
+        if (!cold.isEmpty()) {
+            Outcome out = Outcome.refusedCold(cold);
+            log.warn(out.summary());
+            return out;
+        }
+
+        List<String> deferred = changedDeferredKeys(old, fresh);
+        current.set(fresh);
+        Outcome out = new Outcome(true, List.of(), deferred, null);
+        log.info(out.summary());
+        return out;
+    }
+
+    /** Cold keys whose value differs between the running config and the candidate. */
+    private static List<String> changedColdKeys(BridgedConfig old, BridgedConfig fresh) {
+        List<String> changed = new ArrayList<>();
+        if (!Objects.equals(old.bind(), fresh.bind())) {
+            changed.add("bind");
+        }
+        if (!Objects.equals(old.herdrSocket(), fresh.herdrSocket())) {
+            changed.add("herdrSocket");
+        }
+        if (!Objects.equals(old.broker(), fresh.broker())) {
+            changed.add("broker");
+        }
+        if (!Objects.equals(old.auth(), fresh.auth())) {
+            changed.add("auth");
+        }
+        // Kept in step with COLD_KEYS so the doc and the code cannot drift apart silently.
+        assert COLD_KEYS.containsAll(changed) : "a cold key was reported that COLD_KEYS omits";
+        return changed;
+    }
+
+    /** Changed keys that were accepted but whose effect waits for a restart. */
+    private static List<String> changedDeferredKeys(BridgedConfig old, BridgedConfig fresh) {
+        List<String> changed = new ArrayList<>();
+        if (!Objects.equals(old.lifecycle(), fresh.lifecycle())) {
+            changed.add("lifecycle");
+        }
+        if (!Objects.equals(old.leadHeartbeat(), fresh.leadHeartbeat())) {
+            changed.add("leadHeartbeat");
+        }
+        if (!Objects.equals(old.guard(), fresh.guard())) {
+            changed.add("guard");
+        }
+        if (!Objects.equals(old.worktreeRoot(), fresh.worktreeRoot())) {
+            changed.add("worktreeRoot");
+        }
+        if (!Objects.equals(old.spawnReadyTimeoutMs(), fresh.spawnReadyTimeoutMs())
+                || !Objects.equals(old.spawnReadyPollMs(), fresh.spawnReadyPollMs())) {
+            changed.add("spawnReady*");
+        }
+        // Only the profile SET is deferred: a new backend needs a launcher, and launchers are built
+        // once at startup. An existing profile's fields are read per spawn and so are hot.
+        Set<String> before = old.profiles() == null ? Set.of() : old.profiles().keySet();
+        Set<String> after = fresh.profiles() == null ? Set.of() : fresh.profiles().keySet();
+        if (!before.equals(after)) {
+            Set<String> diff = new LinkedHashSet<>(before);
+            diff.addAll(after);
+            diff.removeIf(p -> before.contains(p) && after.contains(p));
+            changed.add("profiles (added/removed: " + String.join(", ", diff) + ")");
+        }
+        return changed;
+    }
+}
@@ -0,0 +1,96 @@
+package dev.ltms.bridged.config;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.concurrent.Executors;
+import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * Polls {@code bridged.yaml}'s modified time and asks {@link ConfigRef} to reload when it moves
+ * (CB-559). Opt-in through {@code configReload.enabled}.
+ *
+ * <p><strong>Why polling and not a filesystem watch.</strong> {@code WatchService} on macOS has no
+ * native backend — it falls back to polling internally anyway, at an interval this code does not
+ * control — and editors save config files in ways that produce a different event mix per editor
+ * (write-in-place, write-and-rename, write-temp-and-swap). A modified-time check treats all of them
+ * the same and is a single {@code stat} per tick, which at a ten-second cadence costs nothing worth
+ * measuring.
+ *
+ * <p><strong>A missing or unreadable file is not a reason to act.</strong> Many editors briefly
+ * unlink the file during a save. Reloading on "it vanished" would mean reloading from a file that no
+ * longer exists; reporting an error every tick would bury the log. So an unreadable file is skipped
+ * silently and the next tick tries again — the running config stays live, which is the correct
+ * outcome either way.
+ */
+public final class ConfigWatcher {
+
+    private static final Logger log = LoggerFactory.getLogger(ConfigWatcher.class);
+
+    private final ConfigRef ref;
+    private final long intervalSeconds;
+    private final ScheduledExecutorService scheduler;
+
+    private volatile long lastSeenMillis;
+
+    public ConfigWatcher(ConfigRef ref, long intervalSeconds) {
+        this.ref = ref;
+        this.intervalSeconds = intervalSeconds;
+        this.lastSeenMillis = modifiedMillis(ref.path());
+        this.scheduler = Executors.newSingleThreadScheduledExecutor(r -> {
+            Thread t = new Thread(r, "config-watcher");
+            // A daemon thread: an operator's config watch must never be the reason the JVM refuses
+            // to exit after everything else has shut down.
+            t.setDaemon(true);
+            return t;
+        });
+    }
+
+    /** Begin watching. A ref with no file (a fixed one) is a no-op rather than an error. */
+    public void start() {
+        if (ref.path() == null) {
+            log.debug("config watch not started — this config has no file behind it");
+            return;
+        }
+        scheduler.scheduleWithFixedDelay(this::tick, intervalSeconds, intervalSeconds,
+                TimeUnit.SECONDS);
+        log.info("config watch: {} re-read when it changes (every {}s)", ref.path(), intervalSeconds);
+    }
+
+    /** One poll. Never throws — an exception here would silently cancel the schedule. */
+    void tick() {
+        try {
+            long now = modifiedMillis(ref.path());
+            if (now == 0 || now == lastSeenMillis) {
+                return;
+            }
+            // Stamp BEFORE reloading. A file whose reload is refused (a bad edit, or a cold key)
+            // must not be retried every tick — that would log the same refusal forever. The next
+            // save moves the timestamp again and earns a fresh attempt.
+            lastSeenMillis = now;
+            ref.reload();
+        } catch (RuntimeException e) {
+            log.warn("config watch tick failed, still watching: {}", e.getMessage());
+        }
+    }
+
+    private static long modifiedMillis(Path path) {
+        if (path == null) {
+            return 0;
+        }
+        try {
+            return Files.getLastModifiedTime(path).toMillis();
+        } catch (IOException e) {
+            return 0; // mid-save, or gone: say nothing and try again next tick
+        }
+    }
+
+    /** Stop polling. Called from the daemon's ordered shutdown hook, alongside the other loops. */
+    public void stop() {
+        scheduler.shutdownNow();
+    }
+}
@@ -16,6 +16,7 @@ import java.util.Set;
 import java.util.UUID;
 import java.util.function.Function;
 import java.util.function.LongSupplier;
+import java.util.function.Supplier;

 /**
 * The {@link HerdrPeerLauncher} adapter for <strong>Claude Code</strong> — the safe path from a
@@ -92,7 +93,7 @@ public final class ClaudeCodeLauncher extends HerdrPeerLauncher {
                              Map<String, BridgedConfig.Profile> profiles, String defaultProfile,
                              Function<String, String> env,
                              long spawnReadyTimeoutMs, long spawnReadyPollMs,
-                              String tabLabelTemplate) {
+                              Supplier<String> tabLabelTemplate) {
        this(agents, spaces, guard, profiles, defaultProfile, env,
                spawnReadyTimeoutMs,
                System::currentTimeMillis, () -> sleepUninterruptibly(spawnReadyPollMs),
@@ -136,7 +137,7 @@ public final class ClaudeCodeLauncher extends HerdrPeerLauncher {
                              Function<String, String> env,
                              long spawnReadyTimeoutMs,
                              LongSupplier nowMillis, Runnable sleeper,
-                              String tabLabelTemplate) {
+                              Supplier<String> tabLabelTemplate) {
        super(NAME_PREFIX, agents, spaces, profiles, defaultProfile, env,
                spawnReadyTimeoutMs, nowMillis, sleeper, tabLabelTemplate);
        this.guard = guard;
@@ -26,6 +26,7 @@ import java.util.Map;
 import java.util.Set;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.function.Function;
+import java.util.function.Supplier;

 /**
 * The {@link PeerLauncher} the core actually holds when more than one adapter is configured — a thin
@@ -65,16 +66,24 @@ public final class CompositePeerLauncher implements PeerLauncher {
    /** paneId → the delegate that spawned it, so {@link #stop} tears down through the right adapter. */
    private final Map<String, HerdrPeerLauncher> spawnedBy = new ConcurrentHashMap<>();

-    private final Map<String, BridgedConfig.Profile> profileConfigs;
-    private final PlacementPolicy placementPolicy;
    private final Function<String, Integer> liveCount;

    /**
-     * CB-557: the role pools an unqualified spawn draws its candidates from. Nullable, and an empty
-     * pool for a role means "no pool configured" — both fall back to every configured profile, which
-     * is the pre-CB-557 behaviour.
+     * CB-559: the placement inputs are read <em>per spawn</em>, not captured at construction, so a
+     * config reload changes where the next member lands without a restart. These are the hot keys —
+     * role pools, an existing profile's weight/maxLoad, and the placement policy. What cannot change
+     * this way is the set of adapters ({@link #byProfile}), because a new backend needs a launcher
+     * and launchers are built once; {@code ConfigRef} classifies that as deferred and says so.
     */
-    private final BridgedConfig.Fleet fleet;
+    private final Supplier<Map<String, BridgedConfig.Profile>> profileConfigs;
+    private final Supplier<PlacementPolicy> placementPolicy;
+
+    /**
+     * CB-557: the role pools an unqualified spawn draws its candidates from. A supplier that yields
+     * {@code null}, and an empty pool for a role, both fall back to every configured profile — the
+     * pre-CB-557 behaviour.
+     */
+    private final Supplier<BridgedConfig.Fleet> fleet;

    /**
     * Backward-compatible constructor: fixed placement, no live-counting. Use this for tests and
@@ -121,16 +130,45 @@ public final class CompositePeerLauncher implements PeerLauncher {
                                 PlacementPolicy placementPolicy,
                                 Function<String, Integer> liveCount,
                                 BridgedConfig.Fleet fleet) {
+        // LinkedHashMap, not Map.copyOf: candidates() promises definition order and the weighted
+        // policy breaks exact-weight ties on it, so a salted iteration order would make placement
+        // differ from one JVM run to the next.
+        this(delegates, defaultProfile,
+                constant(Collections.unmodifiableMap(new LinkedHashMap<>(profileConfigs))),
+                constant(placementPolicy), liveCount, constant(fleet));
+    }
+
+    /**
+     * Production constructor that re-reads its placement inputs per spawn (CB-559), so a config
+     * reload retargets the next member without a restart.
+     *
+     * @param config the live configuration — read at every spawn, never captured
+     */
+    public CompositePeerLauncher(List<HerdrPeerLauncher> delegates,
+                                 String defaultProfile,
+                                 Supplier<BridgedConfig> config,
+                                 Function<String, Integer> liveCount) {
+        this(delegates, defaultProfile,
+                () -> config.get().profiles(),
+                () -> PlacementPolicies.fromName(config.get().placement()),
+                liveCount,
+                () -> config.get().fleet());
+    }
+
+    /** The all-suppliers form every other constructor funnels into. */
+    private CompositePeerLauncher(List<HerdrPeerLauncher> delegates,
+                                  String defaultProfile,
+                                  Supplier<Map<String, BridgedConfig.Profile>> profileConfigs,
+                                  Supplier<PlacementPolicy> placementPolicy,
+                                  Function<String, Integer> liveCount,
+                                  Supplier<BridgedConfig.Fleet> fleet) {
        this.fleet = fleet;
        if (delegates.isEmpty()) {
            throw new IllegalArgumentException("at least one peer adapter must be configured");
        }
        this.delegates = List.copyOf(delegates);
        this.defaultProfile = defaultProfile;
-        // LinkedHashMap, not Map.copyOf: candidates() promises definition order and the weighted
-        // policy breaks exact-weight ties on it, so a salted iteration order would make placement
-        // differ from one JVM run to the next.
-        this.profileConfigs = Collections.unmodifiableMap(new LinkedHashMap<>(profileConfigs));
+        this.profileConfigs = profileConfigs;
        this.placementPolicy = placementPolicy;
        this.liveCount = liveCount;
        Map<String, HerdrPeerLauncher> index = new LinkedHashMap<>();
@@ -147,6 +185,22 @@ public final class CompositePeerLauncher implements PeerLauncher {
        this.byProfile = Collections.unmodifiableMap(index);
    }

+    /** A supplier of a value fixed at construction — how the non-reloading constructors funnel in. */
+    private static <T> Supplier<T> constant(T value) {
+        return () -> value;
+    }
+
+    /**
+     * The currently-configured profiles, never null.
+     *
+     * <p>Read fresh on every call so a reload is visible; a caller that needs two consistent reads
+     * takes one local, as {@link #poolFor} does.
+     */
+    private Map<String, BridgedConfig.Profile> profiles0() {
+        Map<String, BridgedConfig.Profile> m = profileConfigs.get();
+        return m == null ? Map.of() : m;
+    }
+
    /** The adapter owning {@code profileName} (null/blank → the default). Throws on an unknown profile. */
    private HerdrPeerLauncher route(String profileName) {
        String resolved = (profileName == null || profileName.isBlank()) ? defaultProfile : profileName;
@@ -191,7 +245,7 @@ public final class CompositePeerLauncher implements PeerLauncher {
            // Deliberately uncaught: when no candidate is left (all at cap, or all unreachable) the
            // policy already throws a clear message. Catching it to rethrow a generic
            // PeerUnreachableException would replace a precise diagnosis with a vague one.
-            PlacementCandidate chosen = placementPolicy.select(ctx);
+            PlacementCandidate chosen = placementPolicy.get().select(ctx);

            HerdrPeerLauncher d = byProfile.get(chosen.profile());
            if (d == null) {
@@ -247,7 +301,7 @@ public final class CompositePeerLauncher implements PeerLauncher {
    private void enforceMaxLoad(String profile) {
        // Absent config, or a config whose maxLoad normalized to null (non-positive ⇒ unlimited at
        // load), means no cap — never cap what wasn't configured.
-        BridgedConfig.Profile cfg = profileConfigs.get(profile);
+        BridgedConfig.Profile cfg = profiles0().get(profile);
        Integer cap = (cfg == null) ? null : cfg.maxLoad();
        if (cap == null) {
            return;
@@ -268,9 +322,11 @@ public final class CompositePeerLauncher implements PeerLauncher {
     * a pool entry with no profile, so a survivor is a profile this particular composite does not own.
     */
    private List<String> poolFor(MemberRole role) {
-        List<String> pool = (fleet == null) ? List.of() : fleet.profilesFor(role);
-        List<String> known = pool.stream().filter(profileConfigs::containsKey).toList();
-        return known.isEmpty() ? List.copyOf(profileConfigs.keySet()) : known;
+        Map<String, BridgedConfig.Profile> configured = profiles0();
+        BridgedConfig.Fleet f = fleet.get();
+        List<String> pool = (f == null) ? List.of() : f.profilesFor(role);
+        List<String> known = pool.stream().filter(configured::containsKey).toList();
+        return known.isEmpty() ? List.copyOf(configured.keySet()) : known;
    }

    /** The profile an unqualified spawn for {@code role} falls back to under {@code fixed} placement. */
@@ -283,7 +339,7 @@ public final class CompositePeerLauncher implements PeerLauncher {
    private List<PlacementCandidate> candidates(MemberRole role) {
        List<PlacementCandidate> out = new ArrayList<>();
        for (String name : poolFor(role)) {
-            BridgedConfig.Profile w = profileConfigs.get(name);
+            BridgedConfig.Profile w = profiles0().get(name);
            if (w != null) {
                out.add(new PlacementCandidate(name, null, w.weight(), w.maxLoad()));
            }
@@ -29,6 +29,7 @@ import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicLong;
 import java.util.function.Function;
 import java.util.function.LongSupplier;
+import java.util.function.Supplier;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;

@@ -79,10 +80,15 @@ public abstract class HerdrPeerLauncher implements PeerLauncher {
    private final AtomicLong nameSeq = new AtomicLong(); // per-peer counter (herdr agent names only)

    /**
-     * The {@code fleet.tabLabel} template; {@code null} ⇒ {@link BridgedConfig.Fleet#DEFAULT_TAB_LABEL}.
-     * A profile's own {@code tabLabel} still overrides it.
+     * The {@code fleet.tabLabel} template; a {@code null} supplier or a {@code null}/blank value ⇒
+     * {@link BridgedConfig.Fleet#DEFAULT_TAB_LABEL}. A profile's own {@code tabLabel} still
+     * overrides it.
+     *
+     * <p>CB-559: a supplier rather than a String, so a config reload renames the <em>next</em> tab
+     * without a restart. Existing tabs keep the label they were given — bridged does not rewrite a
+     * label it already wrote.
     */
-    private final String tabLabelTemplate;
+    private final Supplier<String> tabLabelTemplate;

    /**
     * Tab numbers, counted per {@code role/profile} pair (CB-557).
@@ -138,7 +144,8 @@ public abstract class HerdrPeerLauncher implements PeerLauncher {
    /**
     * As above, plus the {@code fleet.tabLabel} template (CB-557).
     *
-     * @param tabLabelTemplate fleet-wide tab-label template; {@code null}/blank ⇒
+     * @param tabLabelTemplate fleet-wide tab-label template, read per spawn (CB-559); {@code null},
+     *                         or a supplier yielding {@code null}/blank ⇒
     *                         {@link BridgedConfig.Fleet#DEFAULT_TAB_LABEL}. A separate constructor
     *                         rather than a new parameter on the one above, so every existing call
     *                         site keeps the default without an edit.
@@ -148,7 +155,7 @@ public abstract class HerdrPeerLauncher implements PeerLauncher {
                                Function<String, String> env,
                                long spawnReadyTimeoutMs,
                                LongSupplier nowMillis, Runnable sleeper,
-                                String tabLabelTemplate) {
+                                Supplier<String> tabLabelTemplate) {
        this.tabLabelTemplate = tabLabelTemplate;
        this.namePrefix = namePrefix;
        this.agents = agents;
@@ -407,7 +414,9 @@ public abstract class HerdrPeerLauncher implements PeerLauncher {
        // we log and still return it so the caller gets its paneId and can tear it down.
        tidy("label tab " + tab.tab().tabId(),
                () -> spaces.renameTab(tab.tab().tabId(),
-                        cfg.renderTabLabel(tabLabelTemplate, role, nextLabelSeq(role, cfg.profile()))));
+                        cfg.renderTabLabel(
+                                tabLabelTemplate == null ? null : tabLabelTemplate.get(),
+                                role, nextLabelSeq(role, cfg.profile()))));
        log.info("{} started pane={} tab={} terminal={}",
                namePrefix, started.agent().paneId(), started.agent().tabId(), started.agent().terminalId());
        return started.agent();
@@ -20,6 +20,7 @@ import java.util.Map;
 import java.util.Set;
 import java.util.function.Function;
 import java.util.function.LongSupplier;
+import java.util.function.Supplier;

 /**
 * The {@link HerdrPeerLauncher} adapter for <strong>opencode</strong> — an open-source,
@@ -125,7 +126,7 @@ public final class OpenCodeLauncher extends HerdrPeerLauncher {
                            Map<String, BridgedConfig.Profile> profiles, String defaultProfile,
                            Function<String, String> env,
                            long spawnReadyTimeoutMs, long spawnReadyPollMs,
-                            String tabLabelTemplate) {
+                            Supplier<String> tabLabelTemplate) {
        this(agents, spaces, profiles, defaultProfile, env, spawnReadyTimeoutMs,
                System::currentTimeMillis, () -> sleepUninterruptibly(spawnReadyPollMs),
                defaultConfigRoot(), defaultDiscoveryRoot(), tabLabelTemplate);
@@ -172,7 +173,7 @@ public final class OpenCodeLauncher extends HerdrPeerLauncher {
                            long spawnReadyTimeoutMs,
                            LongSupplier nowMillis, Runnable sleeper,
                            Path configRoot, Path discoveryRoot,
-                            String tabLabelTemplate) {
+                            Supplier<String> tabLabelTemplate) {
        super(NAME_PREFIX, agents, spaces, profiles, defaultProfile, env,
                spawnReadyTimeoutMs, nowMillis, sleeper, tabLabelTemplate);
        this.configRoot = configRoot;