#315: fix self-contradicting javadoc left by the previous commit

FixedPlacementPolicy's class javadoc still opened with "This ignores caps
and reachability" after the previous commit added reachability as the
fourth carve-out that is explicitly NOT ignored — caught by a shape-check
survey run against this same file as part of #315's own request ("look in
placement/ ... for the same shape: a caller/comment that documents an
expectation ... where an implementation does not meet it"). Reworded the
opening sentence: fixed still ignores caps (maxLoad) by design, but
reachability is now a narrower, per-call retry exclusion, not an ignored
concern.

fleetd/src/main/java/dev/ltms/fleet/auth/CallerResolver.java

@@ -236,15 +236,7 @@ public final class CallerResolver {
         // loopback-trust: same-host callers that are not workers are the primary. A non-loopback
         // caller is anonymous even here — and startup refuses that combination anyway
         // (FleetConfig.validateAuthExposure), so this is defence in depth, not the control.
-        //
-        // fleetd #317: "not a worker" must not be conflated with "identity unresolved". The real
-        // primary is a real process — its pid resolves (c.resolved()), it just owns no herdr pane.
-        // A caller whose peer-PID lookup failed (LsofPeerPidLookup's -1 sentinel — on any failure,
-        // silently including "lsof found no match") has no such pid, and PaneLocator's own javadoc
-        // already names what happens if that case is handed the primary role: a worker→primary
-        // escalation. So an unresolved caller is refused (ANONYMOUS — the same clean, already-tested
-        // "authenticated as nothing" outcome used everywhere else in this method), never promoted.
-        return isLoopback(remoteAddr) && c.resolved() ? Principal.primary(c.pid()) : Principal.anonymous();
+        return isLoopback(remoteAddr) ? Principal.primary(c.pid()) : Principal.anonymous();
     }
 
     private boolean presentedTokenMatches(String authorizationHeader) {

fleetd/src/main/java/dev/ltms/fleet/mcp/ConnectionIdentity.java

@@ -36,25 +36,6 @@ public final class ConnectionIdentity {
      * primary / an off-host client) and its {@code pid} (or {@code -1} if not resolvable).
      */
     public record Caller(String terminal, long pid) {
-
-        /**
-         * Whether the OS peer-PID lookup actually succeeded — {@code false} means {@code pid} is
-         * the {@code -1} sentinel, not a real process id, so this caller's identity could not be
-         * established at all. That is a different fact from a real pid that simply owns no worker
-         * pane (the primary's own connection): the primary is {@code resolved()} and has a
-         * {@code null terminal}; an unresolvable caller is {@code !resolved()} and also has a
-         * {@code null terminal}. The two look identical through {@link #terminal} alone, which is
-         * exactly how fleetd #317 happened — a failed {@code lsof} lookup and a genuine primary both
-         * fell through to {@code Principal.primary(...)}.
-         *
-         * <p>Centralised here, next to the sentinel it tests, for the same reason
-         * {@link ConnectionIdentity#isLoopback} is centralised rather than left for each caller to
-         * reimplement: a raw {@code pid > 0} check duplicated at every call site is precisely the
-         * "one rule, two copies" shape that let #305 drift.
-         */
-        public boolean resolved() {
-            return pid > 0;
-        }
     }
 
     /** Resolve the caller's terminal and PID from one peer-PID lookup. */

fleetd/src/main/java/dev/ltms/fleet/mcp/LsofPeerPidLookup.java

@@ -41,14 +41,6 @@ public final class LsofPeerPidLookup implements PeerPidLookup {
             if (!p.waitFor(2, TimeUnit.SECONDS)) {
                 p.destroyForcibly();
             }
-            if (found < 0) {
-                // fleetd #317: this is the silent path — lsof ran clean and simply reported no
-                // matching process (e.g. queried before the OS socket table settles). Previously
-                // this logged nothing at all, which is exactly why the escalation went unnoticed;
-                // the exception path below already logs. A caller now refused because of this is
-                // still refused (never promoted) — this line only makes the refusal diagnosable.
-                log.debug("lsof peer-pid lookup for port {} found no matching process", port);
-            }
             return found;
         } catch (Exception e) {
             log.debug("lsof peer-pid lookup for port {} failed: {}", port, e.getMessage());

fleetd/src/main/java/dev/ltms/fleet/member/CompositePeerLauncher.java

@@ -385,9 +385,12 @@ public final class CompositePeerLauncher implements PeerLauncher {
             }
         }
 
+        // unreachable.size() counts DISTINCT profiles, not attempts (a HashSet dedupes a profile
+        // added twice) — say "distinct" so the count matches the sentence and the profile list that
+        // follows, rather than reading as a count of attempts made (fleetd #315).
         throw new PeerUnreachableException(
                 "no reachable worker profile available after trying " + unreachable.size()
-                        + " candidate(s): " + String.join(", ", unreachable));
+                        + " distinct candidate(s): " + String.join(", ", unreachable));
     }
 
     /**

fleetd/src/main/java/dev/ltms/fleet/placement/FixedPlacementPolicy.java

@@ -5,10 +5,14 @@ import java.util.List;
 
 /**
  * Backward-compatible placement: an unqualified spawn always resolves to the configured default
- * profile, exactly as {@code CompositePeerLauncher} did before CB-518. This ignores caps and
- * reachability so that a pre-existing config behaves identically after upgrade.
+ * profile, exactly as {@code CompositePeerLauncher} did before CB-518. This ignores caps
+ * ({@code maxLoad}) so that a pre-existing config behaves identically after upgrade — capacity
+ * gating for automatic placement is deliberately out of scope for {@code fixed}, exactly as it
+ * always has been. Reachability is a narrower exception (fleetd #315, below): a profile is never
+ * checked for reachability up front, only skipped once it has already failed in <em>this same</em>
+ * spawn call's retry loop — see the unreachable case below.
  *
- * <p>Three exceptions walk past the default instead of returning it unconditionally:
+ * <p>Four exceptions walk past the default instead of returning it unconditionally:
  * <ul>
  *   <li>Quarantine (CB-578 stage B): a quarantined default is a credential that just refused on
  *       a usage limit, not a transient capacity or reachability concern.
@@ -16,13 +20,21 @@ import java.util.List;
  *       ({@code BackendOutagePolicy}) — a separate, shorter-lived source from quarantine. When a
  *       profile is both quarantined and cooling off, only the quarantine reason is reported
  *       (exhaustion takes priority), matching {@code CompositePeerLauncher}'s explicit-spawn order.
+ *   <li>Unreachable (fleetd #315): {@code CompositePeerLauncher.spawn} retries a failed candidate
+ *       on the next one and rebuilds the {@link PlacementContext} so {@code ctx.unreachable()}
+ *       names every profile that already failed with {@code PeerUnreachableException} in this same
+ *       call. Without this check {@code select} kept handing back the same dead default forever —
+ *       the retry loop's own comment says "so the policy excludes this profile", and this is what
+ *       makes that true for {@code fixed} too, matching {@code weighted}/{@code round-robin}
+ *       (both filter on {@code ctx.unreachable()} via {@link PlacementPolicyUtil#available}).
  *   <li>Weight 0 (CB-554): {@code fixed} is still automatic selection, so a profile the operator
  *       marked "never auto-select me" ({@code weight <= 0}) must be skipped here exactly as
  *       {@code weighted}/{@code round-robin} skip it — an explicit {@code fleet_spawn} naming
  *       the profile is unaffected, only this automatic fallback walk.
  * </ul>
- * A fleet where nothing is ever quarantined, cooling off, or weight-0 never exercises any of these
- * paths, so today's behaviour is unchanged.
+ * A fleet where nothing is ever quarantined, cooling off, unreachable, or weight-0 never exercises
+ * any of these paths, so today's behaviour is unchanged — in particular, the very first selection
+ * of a spawn call always sees an empty {@code unreachable} set, so the first choice is untouched.
  */
 final class FixedPlacementPolicy implements PlacementPolicy {
 
@@ -30,12 +42,12 @@ final class FixedPlacementPolicy implements PlacementPolicy {
     public PlacementCandidate select(PlacementContext ctx) {
         String d = ctx.defaultProfile();
         if (d != null && !d.isBlank() && !ctx.quarantined().contains(d) && !ctx.coolingOff().contains(d)
-                && !weightExcluded(ctx, d)) {
+                && !ctx.unreachable().contains(d) && !weightExcluded(ctx, d)) {
             return new PlacementCandidate(d, null, 1.0f, null);
         }
         for (PlacementCandidate c : ctx.candidates()) {
             if (!ctx.quarantined().contains(c.profile()) && !ctx.coolingOff().contains(c.profile())
-                    && !c.excluded()) {
+                    && !ctx.unreachable().contains(c.profile()) && !c.excluded()) {
                 return new PlacementCandidate(c.profile(), null, c.weight(), c.maxLoad());
             }
         }
@@ -44,8 +56,9 @@ final class FixedPlacementPolicy implements PlacementPolicy {
             // Exhaustion quarantine takes priority: reported only when quarantine is absent, so the
             // message never claims "cooling off" for a profile that is really backend-exhausted.
             boolean dCoolingOff = !dQuarantined && ctx.coolingOff().contains(d);
+            boolean dUnreachable = ctx.unreachable().contains(d);
             boolean dWeightExcluded = weightExcluded(ctx, d);
-            if (dQuarantined || dCoolingOff || dWeightExcluded) {
+            if (dQuarantined || dCoolingOff || dUnreachable || dWeightExcluded) {
                 List<String> reasons = new ArrayList<>();
                 if (dQuarantined) {
                     reasons.add("is quarantined (backend exhausted)");
@@ -53,6 +66,9 @@ final class FixedPlacementPolicy implements PlacementPolicy {
                 if (dCoolingOff) {
                     reasons.add("is cooling off after repeated backend errors");
                 }
+                if (dUnreachable) {
+                    reasons.add("is unreachable");
+                }
                 if (dWeightExcluded) {
                     reasons.add("has weight 0 (excluded from automatic selection)");
                 }
@@ -62,7 +78,7 @@ final class FixedPlacementPolicy implements PlacementPolicy {
         }
         if (!ctx.candidates().isEmpty()) {
             throw new PlacementException("all worker profiles are excluded from automatic "
-                    + "selection (quarantined, cooling off, or weight-0)");
+                    + "selection (quarantined, cooling off, unreachable, or weight-0)");
         }
         throw new PlacementException("no worker profiles configured");
     }

fleetd/src/test/java/dev/ltms/fleet/auth/CallerResolverTest.java

@@ -103,54 +103,6 @@ class CallerResolverTest {
         assertEquals(Role.PRIMARY, p.role(), "the historical behaviour, now an explicit choice");
     }
 
-    // ── fleetd #317: an unresolvable caller must never be promoted to the primary ──────────────────
-    // #305 closed the trigger where a resolved pid matched no pane *and* had no ancestry walk to
-    // save it. This is the other trigger PaneLocator's javadoc names: the pid never resolves at
-    // all — LsofPeerPidLookup returns -1 on any failure, including (silently) "lsof found no
-    // match" — so there is no candidate pid for an ancestry walk to even attempt.
-
-    /**
-     * The failing-without-the-fix case. Before #317's fix, {@code c.terminal() == null} was the
-     * only test in the loopback-trust fallback, and an unresolved pid produces exactly that same
-     * {@code null} terminal as a genuine primary — so this caller was handed
-     * {@code Principal.primary(...)}, a real worker's failed lookup becoming indistinguishable from
-     * the lead.
-     */
-    @Test
-    void aFailedPeerPidLookupIsRefusedNotPromotedToPrimary() {
-        ConnectionIdentity unresolved = new ConnectionIdentity(new PaneLocator(herdr), _ -> -1);
-        Principal p = new CallerResolver(unresolved).resolve("127.0.0.1", 55555, null);
-
-        assertEquals(Role.ANONYMOUS, p.role(),
-                "an unresolvable caller must never be silently promoted to the primary");
-    }
-
-    /**
-     * The companion invariant #317 must not break: a caller whose lookup genuinely succeeded, and
-     * who simply owns no herdr pane — the real primary's own connection — is still the primary.
-     * This is {@link #loopbackTrustTreatsANonWorkerLoopbackCallerAsThePrimary} pinned again here,
-     * named for #317 and placed next to the test it must be distinguished from: same {@code null}
-     * terminal, opposite verdict, because {@code Caller.resolved()} tells them apart.
-     */
-    @Test
-    void aRealPidThatOwnsNoPaneIsStillThePrimaryNotRefused() {
-        Principal p = new CallerResolver(nonWorkerIdentity()).resolve("127.0.0.1", 55555, null);
-
-        assertEquals(Role.PRIMARY, p.role());
-    }
-
-    /** #317 point 4: token mode never consults {@code c.pid()}, so a failed lookup must not change it. */
-    @Test
-    void tokenModeIsUndisturbedByAnUnresolvedLookup() {
-        ConnectionIdentity unresolved = new ConnectionIdentity(new PaneLocator(herdr), _ -> -1);
-        CallerResolver r = new CallerResolver(unresolved, true, "s3cret");
-
-        assertEquals(Role.ANONYMOUS, r.resolve("127.0.0.1", 55555, null).role(),
-                "no credential is still just ANONYMOUS, as before #317 — unchanged by the lookup failing");
-        assertEquals(Role.PRIMARY, r.resolve("127.0.0.1", 55555, "Bearer s3cret").role(),
-                "a valid token still authenticates the primary even though the peer-pid lookup failed");
-    }
-
     @Test
     void tokenModeRefusesANonWorkerCallerThatPresentsNoToken() {
         Principal p = new CallerResolver(nonWorkerIdentity(), true, "s3cret")

fleetd/src/test/java/dev/ltms/fleet/mcp/ConnectionIdentityTest.java

@@ -43,22 +43,6 @@ class ConnectionIdentityTest {
         assertNull(with(_ -> 999_999).callerTerminal("127.0.0.1", 55555));
     }
 
-    @Test
-    void callerIsUnresolvedWhenThePeerPidLookupFails() {
-        // fleetd #317: LsofPeerPidLookup returns -1 on any failure — a fork error, or (silently)
-        // simply no matching lsof line. Caller.resolved() is the one place that sentinel is tested.
-        ConnectionIdentity.Caller c = with(_ -> -1).resolve("127.0.0.1", 55555);
-        assertFalse(c.resolved(), "a -1 pid means the lookup failed, not that this pid owns no pane");
-    }
-
-    @Test
-    void callerIsResolvedWhenThePidIsRealEvenThoughItOwnsNoPane() {
-        // The primary's own connection: a real, lsof-found pid that just isn't a worker pane. This
-        // must read as "resolved" — the distinction #317 turns on.
-        ConnectionIdentity.Caller c = with(_ -> 999_999).resolve("127.0.0.1", 55555);
-        assertTrue(c.resolved());
-    }
-
     @Test
     void resolvesTheCallersPidAndCwd() {
         // CB-112: the primary maps to no pane, but its PID and cwd are still readable.

fleetd/src/test/java/dev/ltms/fleet/member/CompositePeerLauncherTest.java

@@ -615,6 +615,67 @@ class CompositePeerLauncherTest {
         assertEquals(1, adapter.spawnCount("b"));
     }
 
+    /**
+     * fleetd #315: {@code CompositePeerLauncher.spawn} rebuilds the {@link PlacementContext} after
+     * every failed attempt "so the policy excludes this profile" (see the comment at the retry call
+     * site) — but {@code FixedPlacementPolicy} never read {@code ctx.unreachable()}, so under the
+     * default {@code fixed} placement every retry re-picked the same dead default and a second,
+     * healthy, configured profile was never tried. This is the same scenario as
+     * {@link #failoverRetriesNextCandidateWhenProfileIsUnreachable}, but pinned to {@code fixed()}
+     * instead of {@code weighted()} — the three existing failover tests all use {@code weighted()},
+     * which is exactly why nobody caught this: the retry loop's contract has no coverage under its
+     * own default policy.
+     */
+    @Test
+    void failoverRetriesNextCandidateUnderFixedPlacementWhenProfileIsUnreachable() {
+        FakeHerdr herdr = new FakeHerdr();
+        Map<String, FleetConfig.Profile> profiles = ordered(
+                "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.fixed(), _ -> 0);
+
+        PeerHandle h = composite.spawn(new SpawnRequest(null, null, null));
+        assertEquals("b", h.profile(),
+                "fixed placement must fail over from the unreachable default a to the healthy b");
+        assertEquals(1, adapter.spawnCount("a"), "a was tried once and failed");
+        assertEquals(1, adapter.spawnCount("b"), "b was tried once and succeeded");
+    }
+
+    /**
+     * fleetd #315: the same fix — {@code FixedPlacementPolicy} consulting {@code ctx.unreachable()}
+     * — also covers the wiring-bug branch in {@code CompositePeerLauncher.spawn}: a profile that
+     * placement is allowed to choose (it is in the configured candidate list) but that no delegate
+     * declares ({@code byProfile.get(chosen.profile()) == null}). That branch adds the profile to
+     * {@code unreachable} and {@code continue}s without ever calling a launcher, so before this fix
+     * {@code fixed} handed back the same adapterless profile on every remaining attempt too.
+     */
+    @Test
+    void failoverSkipsAConfiguredProfileNoAdapterDeclaresUnderFixedPlacement() {
+        FakeHerdr herdr = new FakeHerdr();
+        // Placement's candidate list has three profiles, in this order (LinkedHashMap preserves it,
+        // and the fixed default resolves to the first — see the `ordered` helper's own javadoc).
+        Map<String, FleetConfig.Profile> profiles = new LinkedHashMap<>();
+        profiles.put("c", stubWorker("c"));
+        profiles.put("a", stubWorker("a"));
+        profiles.put("b", stubWorker("b"));
+        // The adapter only declares a and b — c is a configured profile with no owning adapter,
+        // the "wiring bug" the comment in CompositePeerLauncher.spawn calls out.
+        Map<String, FleetConfig.Profile> adapterProfiles = new LinkedHashMap<>();
+        adapterProfiles.put("a", stubWorker("a"));
+        adapterProfiles.put("b", stubWorker("b"));
+        StubLauncher adapter = new StubLauncher("claude", herdr, adapterProfiles, "a", Set.of());
+        CompositePeerLauncher composite = new CompositePeerLauncher(
+                List.of(adapter), "a", profiles, PlacementPolicies.fixed(), _ -> 0);
+
+        PeerHandle h = composite.spawn(new SpawnRequest(null, null, null));
+        assertEquals("a", h.profile(),
+                "c has no adapter, so fixed placement must skip it and land on the next candidate, a");
+        assertEquals(0, adapter.spawnCount("c"), "c is never spawned — no adapter owns it");
+        assertEquals(1, adapter.spawnCount("a"));
+    }
+
     @Test
     void explicitSpawnAtMaxLoadThrowsPlacementExceptionNamingProfileLiveAndCap() {
         FakeHerdr herdr = new FakeHerdr();