CB-518: weighted placement policy for worker spawns

bridged/src/test/java/dev/ltms/bridged/config/BridgedConfigTest.java

@@ -333,6 +333,9 @@ class BridgedConfigTest {
                     parityOverlay: [".mcp.json", ".env"]
                     gitTokenEnv: GITEA_TOKEN
                     gitHostEnv: GITEA_HOST
+                    weight: 0.5
+                    maxLoad: 2
+                placement: weighted
                 lifecycle:
                   idleTtlSeconds: 300
                   contextCap: 10
@@ -356,7 +359,10 @@ class BridgedConfigTest {
         assertEquals(java.util.List.of(".mcp.json", ".env"), w.parityOverlay());
         assertTrue(w.hasGitToken(), "gitTokenEnv binds and enables the CB-302 PR grant");
         assertEquals("GITEA_HOST", w.gitHostEnv());
+        assertEquals(0.5f, w.weight(), 0.0001f, "weight binds as a float");
+        assertEquals(2, w.maxLoad(), "maxLoad binds as an integer");
 
+        assertEquals("weighted", cfg.placement(), "placement binds at the top level");
         assertEquals(300, cfg.lifecycle().idleTtlSeconds());
         assertEquals(10, cfg.lifecycle().contextCap());
         assertEquals(5, cfg.lifecycle().drainTimeoutSeconds());
@@ -365,4 +371,36 @@ class BridgedConfigTest {
         assertEquals(5, cfg.primary().remindersOrDefault());
         assertEquals(15000L, cfg.primary().backoffMsOrDefault());
     }
+
+    @Test
+    void placementDefaultsToFixedForExistingConfigs(@TempDir Path dir) throws Exception {
+        Path f = dir.resolve("no-placement.yaml");
+        Files.writeString(f, """
+                bind:
+                  port: 8080
+                workers:
+                  gx10:
+                    baseUrl: http://gx10.gw:8000
+                """);
+
+        BridgedConfig cfg = BridgedConfig.load(f);
+        assertEquals("fixed", cfg.placement(), "omitted placement must default to fixed");
+    }
+
+    @Test
+    void workerWeightAndMaxLoadDefaultSanely(@TempDir Path dir) throws Exception {
+        Path f = dir.resolve("no-weight.yaml");
+        Files.writeString(f, """
+                bind:
+                  port: 8080
+                workers:
+                  gx10:
+                    baseUrl: http://gx10.gw:8000
+                """);
+
+        BridgedConfig cfg = BridgedConfig.load(f);
+        BridgedConfig.Worker w = cfg.workerProfiles().get("gx10");
+        assertEquals(1.0f, w.weight(), 0.0001f, "absent weight defaults to 1.0");
+        assertNull(w.maxLoad(), "absent maxLoad defaults to unlimited (null)");
+    }
 }

bridged/src/test/java/dev/ltms/bridged/placement/PlacementPolicyTest.java

@@ -0,0 +1,183 @@
+package dev.ltms.bridged.placement;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.HashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.function.Function;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * Unit tests for the placement policies. They run with no herdr and no launcher — pure selection
+ * logic exercised through the descriptor type so CB-308 host expansion will not need to rewrite
+ * these assertions.
+ */
+class PlacementPolicyTest {
+
+    private static Function<String, Integer> noSessions() {
+        return name -> 0;
+    }
+
+    private static PlacementContext ctx(List<PlacementCandidate> candidates,
+                                        Function<String, Integer> liveCount,
+                                        Set<String> unreachable) {
+        return new PlacementContext("b", candidates, liveCount, unreachable);
+    }
+
+    private static PlacementContext ctx(List<PlacementCandidate> candidates,
+                                        Function<String, Integer> liveCount) {
+        return ctx(candidates, liveCount, Set.of());
+    }
+
+    @Test
+    void fixedReturnsDefaultEvenIfOtherProfilesExist() {
+        PlacementPolicy policy = PlacementPolicies.fixed();
+        PlacementContext ctx = ctx(List.of(
+                PlacementCandidate.profile("a"),
+                PlacementCandidate.profile("b")), noSessions());
+        assertEquals("b", policy.select(ctx).profile());
+    }
+
+    @Test
+    void fixedFallsBackToFirstCandidateWhenNoDefault() {
+        PlacementPolicy policy = PlacementPolicies.fixed();
+        PlacementContext ctx = new PlacementContext(null,
+                List.of(PlacementCandidate.profile("a"), PlacementCandidate.profile("b")),
+                noSessions(), Set.of());
+        assertEquals("a", policy.select(ctx).profile());
+    }
+
+    @Test
+    void fixedThrowsWhenNoProfilesAndNoDefault() {
+        PlacementPolicy policy = PlacementPolicies.fixed();
+        PlacementContext ctx = new PlacementContext(null, List.of(), noSessions(), Set.of());
+        assertThrows(PlacementException.class, () -> policy.select(ctx));
+    }
+
+    @Test
+    void roundRobinCyclesThroughAvailableProfiles() {
+        PlacementPolicy policy = PlacementPolicies.roundRobin();
+        List<PlacementCandidate> candidates = List.of(
+                PlacementCandidate.profile("a"),
+                PlacementCandidate.profile("b"),
+                PlacementCandidate.profile("c"));
+        assertEquals("a", policy.select(ctx(candidates, noSessions())).profile());
+        assertEquals("b", policy.select(ctx(candidates, noSessions())).profile());
+        assertEquals("c", policy.select(ctx(candidates, noSessions())).profile());
+        assertEquals("a", policy.select(ctx(candidates, noSessions())).profile());
+    }
+
+    @Test
+    void roundRobinSkipsProfilesAtMaxLoad() {
+        PlacementPolicy policy = PlacementPolicies.roundRobin();
+        List<PlacementCandidate> candidates = List.of(
+                PlacementCandidate.profile("a", 1.0f, 2),
+                PlacementCandidate.profile("b", 1.0f, null));
+        Function<String, Integer> liveCount = Map.of("a", 2)::get;
+        for (int i = 0; i < 5; i++) {
+            assertEquals("b", policy.select(ctx(candidates, liveCount)).profile());
+        }
+    }
+
+    @Test
+    void roundRobinThrowsWhenAllAtMaxLoad() {
+        PlacementPolicy policy = PlacementPolicies.roundRobin();
+        List<PlacementCandidate> candidates = List.of(
+                PlacementCandidate.profile("a", 1.0f, 1),
+                PlacementCandidate.profile("b", 1.0f, 1));
+        Function<String, Integer> liveCount = Map.of("a", 1, "b", 1)::get;
+        PlacementException e = assertThrows(PlacementException.class,
+                () -> policy.select(ctx(candidates, liveCount)));
+        assertTrue(e.getMessage().contains("maxLoad"), e.getMessage());
+    }
+
+    @Test
+    void weightedAlternatesEvenlyWithEqualWeights() {
+        PlacementPolicy policy = PlacementPolicies.weighted();
+        List<PlacementCandidate> candidates = List.of(
+                PlacementCandidate.profile("a", 0.5f, null),
+                PlacementCandidate.profile("b", 0.5f, null));
+        int a = 0, b = 0;
+        for (int i = 0; i < 100; i++) {
+            String p = policy.select(ctx(candidates, noSessions())).profile();
+            if ("a".equals(p)) a++;
+            else if ("b".equals(p)) b++;
+        }
+        assertEquals(50, a, "equal weights should split 50/50");
+        assertEquals(50, b);
+    }
+
+    @Test
+    void weightedHoldsThreeToOneRatio() {
+        PlacementPolicy policy = PlacementPolicies.weighted();
+        List<PlacementCandidate> candidates = List.of(
+                PlacementCandidate.profile("a", 0.75f, null),
+                PlacementCandidate.profile("b", 0.25f, null));
+        int a = 0, b = 0;
+        for (int i = 0; i < 40; i++) {
+            String p = policy.select(ctx(candidates, noSessions())).profile();
+            if ("a".equals(p)) a++;
+            else if ("b".equals(p)) b++;
+        }
+        assertEquals(30, a, "0.75/0.25 should yield a 3:1 ratio over a multiple of 4");
+        assertEquals(10, b);
+    }
+
+    @Test
+    void weightedSkipsProfileAtMaxLoad() {
+        PlacementPolicy policy = PlacementPolicies.weighted();
+        List<PlacementCandidate> candidates = List.of(
+                PlacementCandidate.profile("a", 1.0f, 1),
+                PlacementCandidate.profile("b", 1.0f, null));
+        Function<String, Integer> liveCount = name -> "a".equals(name) ? 1 : 0;
+        for (int i = 0; i < 5; i++) {
+            assertEquals("b", policy.select(ctx(candidates, liveCount)).profile());
+        }
+    }
+
+    @Test
+    void weightedThrowsWhenAllAtMaxLoad() {
+        PlacementPolicy policy = PlacementPolicies.weighted();
+        List<PlacementCandidate> candidates = List.of(
+                PlacementCandidate.profile("a", 1.0f, 1),
+                PlacementCandidate.profile("b", 1.0f, 1));
+        Function<String, Integer> liveCount = name -> 1;
+        PlacementException e = assertThrows(PlacementException.class,
+                () -> policy.select(ctx(candidates, liveCount)));
+        assertTrue(e.getMessage().contains("maxLoad"), e.getMessage());
+    }
+
+    @Test
+    void weightedThrowsWhenAllUnreachable() {
+        PlacementPolicy policy = PlacementPolicies.weighted();
+        List<PlacementCandidate> candidates = List.of(
+                PlacementCandidate.profile("a"),
+                PlacementCandidate.profile("b"));
+        PlacementException e = assertThrows(PlacementException.class,
+                () -> policy.select(ctx(candidates, noSessions(), Set.of("a", "b"))));
+        assertTrue(e.getMessage().contains("unreachable"), e.getMessage());
+    }
+
+    @Test
+    void mixedExclusionMessageNamesBothReasons() {
+        PlacementPolicy policy = PlacementPolicies.weighted();
+        List<PlacementCandidate> candidates = List.of(
+                PlacementCandidate.profile("a", 1.0f, 1),
+                PlacementCandidate.profile("b", 1.0f, null));
+        Function<String, Integer> liveCount = name -> "a".equals(name) ? 1 : 0;
+        Set<String> unreachable = new HashSet<>();
+        unreachable.add("b");
+        PlacementException e = assertThrows(PlacementException.class,
+                () -> policy.select(ctx(candidates, liveCount, unreachable)));
+        assertTrue(e.getMessage().contains("1 at maxLoad"), e.getMessage());
+        assertTrue(e.getMessage().contains("1 unreachable"), e.getMessage());
+    }
+
+    @Test
+    void unknownPolicyNameThrows() {
+        assertThrows(IllegalArgumentException.class, () -> PlacementPolicies.fromName("random"));
+    }
+}

bridged/src/test/java/dev/ltms/bridged/worker/ClaudeCodeLauncherTest.java

@@ -512,7 +512,7 @@ class ClaudeCodeLauncherTest {
         BridgedConfig.Worker cfg = new BridgedConfig.Worker(
                 "ltms-local", "http://gx00.gw:8000", "coder", null, "BRIDGED_WORKER_TOKEN",
                 List.of("claude"), "tab", "bridged-workers", "w #{n}", null, null, null, null, null,
-                null, Map.of("JAVA_HOME", "/opt/jdk", "PATH", "/profile/bin"));
+                null, Map.of("JAVA_HOME", "/opt/jdk", "PATH", "/profile/bin"), null, null);
         new ClaudeCodeLauncher(new AgentControl(herdr), new WorkspaceControl(herdr),
                 new SubscriptionGuard(Set.of("gx00.gw")), Map.of(cfg.profile(), cfg), cfg.profile(),
                 k -> "PATH".equals(k) ? "/daemon/bin" : null).spawn();
@@ -533,7 +533,7 @@ class ClaudeCodeLauncherTest {
         BridgedConfig.Worker cfg = new BridgedConfig.Worker(
                 "ltms-local", "http://gx00.gw:8000", "coder", null, "BRIDGED_WORKER_TOKEN",
                 List.of("claude"), "tab", "bridged-workers", "w #{n}", null, null, null, null, null,
-                null, Map.of("ANTHROPIC_BASE_URL", "http://evil.example.com"));
+                null, Map.of("ANTHROPIC_BASE_URL", "http://evil.example.com"), null, null);
         new ClaudeCodeLauncher(new AgentControl(herdr), new WorkspaceControl(herdr),
                 new SubscriptionGuard(Set.of("gx00.gw")), Map.of(cfg.profile(), cfg), cfg.profile(),
                 _ -> null).spawn();

bridged/src/test/java/dev/ltms/bridged/worker/CompositePeerLauncherTest.java

@@ -2,17 +2,26 @@ package dev.ltms.bridged.worker;
 
 import dev.ltms.bridged.config.BridgedConfig;
 import dev.ltms.bridged.guard.SubscriptionGuard;
+import dev.ltms.bridged.herdr.Agent;
 import dev.ltms.bridged.herdr.AgentControl;
 import dev.ltms.bridged.herdr.FakeHerdr;
 import dev.ltms.bridged.herdr.WorkspaceControl;
+import dev.ltms.bridged.peer.Capability;
 import dev.ltms.bridged.peer.PeerHandle;
 import dev.ltms.bridged.peer.PeerLauncher;
+import dev.ltms.bridged.peer.PeerUnreachableException;
 import dev.ltms.bridged.peer.SpawnRequest;
+import dev.ltms.bridged.placement.PlacementException;
+import dev.ltms.bridged.placement.PlacementPolicies;
 import org.junit.jupiter.api.Test;
 
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
+import java.util.function.Function;
 
 import static org.junit.jupiter.api.Assertions.*;
 
@@ -46,6 +55,73 @@ class CompositePeerLauncherTest {
                 List.of(claudeAdapter(herdr), opencodeAdapter(herdr)), "claude");
     }
 
+    /**
+     * A minimal concrete HerdrPeerLauncher for policy tests. It either returns a fake handle for the
+     * requested profile or throws, depending on {@code failProfiles}. buildLaunch is a stub; only
+     * spawn/stop/list/caps/reap are exercised by the composite.
+     */
+    private static final class StubLauncher extends HerdrPeerLauncher {
+        private final Set<String> failProfiles;
+        private final Map<String, Integer> spawnCounts = new HashMap<>();
+
+        StubLauncher(String prefix, FakeHerdr herdr,
+                     Map<String, BridgedConfig.Worker> profiles, String defaultProfile,
+                     Set<String> failProfiles) {
+            super(prefix, new AgentControl(herdr), new WorkspaceControl(herdr),
+                    profiles, defaultProfile, _ -> null, 0L, System::currentTimeMillis, () -> { });
+            this.failProfiles = Set.copyOf(failProfiles);
+        }
+
+        @Override
+        protected Launch buildLaunch(BridgedConfig.Worker cfg) {
+            return new Launch(Map.of(), List.of());
+        }
+
+        @Override
+        public PeerHandle spawn(SpawnRequest req) {
+            String p = (req.profileName() == null || req.profileName().isBlank())
+                    ? defaultProfile() : req.profileName();
+            spawnCounts.merge(p, 1, Integer::sum);
+            if (failProfiles.contains(p)) {
+                throw new PeerUnreachableException(p + " is down");
+            }
+            return new PeerHandle() {
+                @Override public String id() { return "pane-" + p; }
+                @Override public String terminalId() { return "term-" + p; }
+                @Override public String profile() { return p; }
+            };
+        }
+
+        @Override
+        public void stop(String id) { }
+
+        @Override
+        public List<Agent> list() { return List.of(); }
+
+        @Override
+        public Set<Capability> capabilities() { return EnumSet.noneOf(Capability.class); }
+
+        @Override
+        public int reapOrphanWorkers() { return 0; }
+
+        int spawnCount(String profile) {
+            return spawnCounts.getOrDefault(profile, 0);
+        }
+    }
+
+    private static BridgedConfig.Worker stubWorker(String profile) {
+        return new BridgedConfig.Worker(profile, "http://gx00.gw:8000", "coder",
+                null, "BRIDGED_WORKER_TOKEN", List.of("claude"), "tab", "bridged-workers",
+                "w #{n}", null, null, null, null, null, null, null, null, null);
+    }
+
+    private static BridgedConfig.Worker stubWorker(String profile, float weight, Integer maxLoad) {
+        return new BridgedConfig.Worker(profile, "http://gx00.gw:8000", "coder",
+                null, "BRIDGED_WORKER_TOKEN", List.of("claude"), "tab", "bridged-workers",
+                "w #{n}", null, null, null, null, null, null, null,
+                weight, maxLoad);
+    }
+
     @SuppressWarnings("unchecked")
     private static String startedName(FakeHerdr herdr) {
         return (String) ((Map<String, Object>) herdr.lastCall("agent.start").params()).get("name");
@@ -158,4 +234,99 @@ class CompositePeerLauncherTest {
                 () -> new CompositePeerLauncher(List.of(), "claude"),
                 "at least one adapter must be configured");
     }
+
+    @Test
+    void fixedDefaultIsNoOpForUnqualifiedSpawns() {
+        FakeHerdr herdr = new FakeHerdr();
+        CompositePeerLauncher composite = composite(herdr);
+
+        PeerHandle h = composite.spawn(new SpawnRequest(null, null, null));
+        assertTrue(startedName(herdr).startsWith("claude-"),
+                "fixed placement still routes an unqualified spawn to the default profile");
+        assertEquals("claude", h.profile(), "the returned handle carries the resolved default profile");
+    }
+
+    @Test
+    void weightedPolicyGatesProfileAtMaxLoad() {
+        FakeHerdr herdr = new FakeHerdr();
+        Map<String, BridgedConfig.Worker> profiles = Map.of(
+                "a", stubWorker("a", 1.0f, 1),
+                "b", stubWorker("b", 1.0f, null));
+        StubLauncher adapter = new StubLauncher("claude", herdr, profiles, "a", Set.of());
+        CompositePeerLauncher composite = new CompositePeerLauncher(
+                List.of(adapter), "a", profiles, PlacementPolicies.weighted(), name -> "a".equals(name) ? 1 : 0);
+
+        for (int i = 0; i < 5; i++) {
+            PeerHandle h = composite.spawn(new SpawnRequest(null, null, null));
+            assertEquals("b", h.profile(), "profile a is at maxLoad, so every spawn must land on b");
+        }
+    }
+
+    @Test
+    void weightedPolicyDistributesAccordingToWeightRatio() {
+        FakeHerdr herdr = new FakeHerdr();
+        Map<String, BridgedConfig.Worker> profiles = Map.of(
+                "a", stubWorker("a", 0.75f, null),
+                "b", stubWorker("b", 0.25f, null));
+        StubLauncher adapter = new StubLauncher("claude", herdr, profiles, "a", Set.of());
+        CompositePeerLauncher composite = new CompositePeerLauncher(
+                List.of(adapter), "a", profiles, PlacementPolicies.weighted(), name -> 0);
+
+        int a = 0, b = 0;
+        for (int i = 0; i < 40; i++) {
+            String p = composite.spawn(new SpawnRequest(null, null, null)).profile();
+            if ("a".equals(p)) a++;
+            else if ("b".equals(p)) b++;
+        }
+        assertEquals(30, a, "weighted distribution should hold the 3:1 ratio");
+        assertEquals(10, b);
+    }
+
+    @Test
+    void failoverRetriesNextCandidateWhenProfileIsUnreachable() {
+        FakeHerdr herdr = new FakeHerdr();
+        Map<String, BridgedConfig.Worker> profiles = Map.of(
+                "a", stubWorker("a"),
+                "b", stubWorker("b"));
+        StubLauncher adapter = new StubLauncher("claude", herdr, profiles, "a", Set.of("a"));
+        CompositePeerLauncher composite = new CompositePeerLauncher(
+                List.of(adapter), "a", profiles, PlacementPolicies.weighted(), name -> 0);
+
+        PeerHandle h = composite.spawn(new SpawnRequest(null, null, null));
+        assertEquals("b", h.profile(), "the spawn must fail over from unreachable a to b");
+        assertEquals(1, adapter.spawnCount("a"), "a was tried once and failed");
+        assertEquals(1, adapter.spawnCount("b"), "b was tried once and succeeded");
+    }
+
+    @Test
+    void failoverBoundedByCandidateCount() {
+        FakeHerdr herdr = new FakeHerdr();
+        Map<String, BridgedConfig.Worker> profiles = Map.of(
+                "a", stubWorker("a"),
+                "b", stubWorker("b"));
+        StubLauncher adapter = new StubLauncher("claude", herdr, profiles, "a", Set.of("a", "b"));
+        CompositePeerLauncher composite = new CompositePeerLauncher(
+                List.of(adapter), "a", profiles, PlacementPolicies.weighted(), name -> 0);
+
+        PeerUnreachableException e = assertThrows(PeerUnreachableException.class,
+                () -> composite.spawn(new SpawnRequest(null, null, null)));
+        assertTrue(e.getMessage().contains("no reachable worker profile"), e.getMessage());
+        assertEquals(1, adapter.spawnCount("a"));
+        assertEquals(1, adapter.spawnCount("b"));
+    }
+
+    @Test
+    void emptyCandidateSetThrowsClearException() {
+        FakeHerdr herdr = new FakeHerdr();
+        Map<String, BridgedConfig.Worker> profiles = Map.of(
+                "a", stubWorker("a", 1.0f, 1),
+                "b", stubWorker("b", 1.0f, 1));
+        StubLauncher adapter = new StubLauncher("claude", herdr, profiles, "a", Set.of());
+        CompositePeerLauncher composite = new CompositePeerLauncher(
+                List.of(adapter), "a", profiles, PlacementPolicies.weighted(), name -> 1);
+
+        PlacementException e = assertThrows(PlacementException.class,
+                () -> composite.spawn(new SpawnRequest(null, null, null)));
+        assertTrue(e.getMessage().contains("maxLoad"), e.getMessage());
+    }
 }