#317: refuse an unresolved caller instead of promoting it to primary

ConnectionIdentity.resolve() called pids.pidForLocalPort(remotePort),
which returns -1 both on a real failure and (silently, no log line)
when lsof just finds no matching process. terminalForPid(-1) then
matches no pane, so CallerResolver's loopback-trust fallback could not
tell that caller apart from a genuine primary and handed it
Principal.primary(...) — granting SPAWN, STOP, SEND and DRAIN to a
worker whose PID lookup failed. This is the escalation PaneLocator's
own javadoc already names; CB-161's ancestry walk only helps once a
candidate pid exists, and a failed lookup has none.

Fix: ConnectionIdentity.Caller gets a resolved() predicate (pid > 0),
centralised next to the -1 sentinel it tests for the same reason
isLoopback() is centralised (fleetd #305: two independent copies of
one rule already drifted once). CallerResolver's loopback-trust
fallback now requires c.resolved() before granting PRIMARY; an
unresolved caller gets Principal.anonymous() — the same already-tested
"authenticated as nothing" outcome used everywhere else in that
method, so the refusal is a clean, named, unsurprising result rather
than something that looks like a bug.

Also logs the previously-silent "lsof ran clean, found no match" case
in LsofPeerPidLookup at DEBUG, since that (not a slow lsof — the
waitFor result was already discarded) is the likelier real trigger.

loopbackTrustTreatsANonWorkerLoopbackCallerAsThePrimary is untouched
and still green: a real pid that owns no pane (the actual primary) is
still resolved() and still PRIMARY. Token mode is unaffected — it
never consults c.pid() at all.

Mutation-tested: reverting only the CallerResolver.java guard
reproduces the escalation exactly (aFailedPeerPidLookupIsRefusedNotPromotedToPrimary
fails with "expected: <ANONYMOUS> but was: <PRIMARY>").

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

@@ -236,7 +236,15 @@ 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.
-        return isLoopback(remoteAddr) ? Principal.primary(c.pid()) : Principal.anonymous();
+        //
+        // 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();
     }
 
     private boolean presentedTokenMatches(String authorizationHeader) {

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

@@ -36,6 +36,25 @@ 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,6 +41,14 @@ 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,12 +385,9 @@ 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()
-                        + " distinct candidate(s): " + String.join(", ", unreachable));
+                        + " candidate(s): " + String.join(", ", unreachable));
     }
 
     /**

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

@@ -5,14 +5,10 @@ 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
- * ({@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.
+ * profile, exactly as {@code CompositePeerLauncher} did before CB-518. This ignores caps and
+ * reachability so that a pre-existing config behaves identically after upgrade.
  *
- * <p>Four exceptions walk past the default instead of returning it unconditionally:
+ * <p>Three 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.
@@ -20,21 +16,13 @@ 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, 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.
+ * A fleet where nothing is ever quarantined, cooling off, or weight-0 never exercises any of these
+ * paths, so today's behaviour is unchanged.
  */
 final class FixedPlacementPolicy implements PlacementPolicy {
 
@@ -42,12 +30,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)
-                && !ctx.unreachable().contains(d) && !weightExcluded(ctx, 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())
-                    && !ctx.unreachable().contains(c.profile()) && !c.excluded()) {
+                    && !c.excluded()) {
                 return new PlacementCandidate(c.profile(), null, c.weight(), c.maxLoad());
             }
         }
@@ -56,9 +44,8 @@ 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 || dUnreachable || dWeightExcluded) {
+            if (dQuarantined || dCoolingOff || dWeightExcluded) {
                 List<String> reasons = new ArrayList<>();
                 if (dQuarantined) {
                     reasons.add("is quarantined (backend exhausted)");
@@ -66,9 +53,6 @@ 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)");
                 }
@@ -78,7 +62,7 @@ final class FixedPlacementPolicy implements PlacementPolicy {
         }
         if (!ctx.candidates().isEmpty()) {
             throw new PlacementException("all worker profiles are excluded from automatic "
-                    + "selection (quarantined, cooling off, unreachable, or weight-0)");
+                    + "selection (quarantined, cooling off, or weight-0)");
         }
         throw new PlacementException("no worker profiles configured");
     }

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

@@ -103,6 +103,54 @@ 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,6 +43,22 @@ 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,67 +615,6 @@ 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();