fleetd #492 : teach redeploy-fleetd.sh systemd --user as a third supervisor

launchd, systemd --user, and unsupervised are three different answers, not two. Refuse (die) rather than fall through to kill+nohup when a supervisor is detected that this script cannot drive (e.g. both signals fire at once), and add a post-restart check that fails the run if more than one fleetd process is alive. detect_supervisor()/require_drivable_supervisor()/ count_daemon_pids()/assert_single_daemon() are pure, overridable functions so scripts/test-redeploy-fleetd.sh can exercise them without a real launchd or systemd.
2026-09-12 09:00:59 +07:00
4 changed files with 314 additions and 371 deletions
@@ -80,7 +80,6 @@ import java.util.concurrent.ScheduledExecutorService;
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.atomic.AtomicReference;
 import java.util.function.Function;
-import java.util.function.LongSupplier;
 import java.util.function.Predicate;
 import java.util.function.Supplier;
 import java.util.regex.Pattern;
@@ -271,12 +270,15 @@ public final class Fleetd {
        // the first thing that actually talks to herdr, so without this wait a boot-order race
        // would crash the daemon into a restart loop. Wait, then degrade rather than die: serving
        // with /healthz reporting "degraded" is strictly more useful than exiting.
-        HerdrAwaitOutcome herdrOutcome = awaitHerdr(herdr, System::nanoTime, Fleetd::sleepHerdrPoll);
-        boolean herdrUp = logHerdrWaitOutcomeAndShouldReap(herdrOutcome);
+        boolean herdrUp = awaitHerdr(herdr);
        if (herdrUp) {
            // CB-117: herdr keeps worker panes alive across a daemon restart, and their ids died
            // with the previous process — reap those leaked orphans now, before we start serving.
            workers.reapOrphanWorkers();
+        } else {
+            log.warn("herdr did not answer within {}s — starting anyway; /healthz will report "
+                    + "degraded until it comes up. Orphaned worker panes (if any) were NOT reaped.",
+                    HERDR_WAIT_SECONDS);
        }

        // CB-301: authoritative session registry + lifecycle FSM on top of ClaudeCodeLauncher.
@@ -1694,70 +1696,12 @@ public final class Fleetd {
    }

    /**
-     * How {@link #awaitHerdr} ended (fleetd #498). The old code returned a bare {@code boolean},
-     * which collapsed two different facts onto the same {@code false}: the configured wait budget
-     * genuinely running out, and the waiting thread being interrupted possibly milliseconds in.
-     * Those need different operator messages — see {@link #logHerdrWaitOutcomeAndShouldReap} — so
-     * this is a third state, not a better number (the same shape fleetd #497 named). Never treat
-     * {@link #INTERRUPTED} as if it were {@link #DEADLINE_PASSED}: only the latter means herdr was
-     * actually given the full {@link #HERDR_WAIT_SECONDS} and still failed to answer.
-     */
-    enum HerdrWaitResult {
-        /** herdr answered {@code ping} before the deadline. */
-        ANSWERED,
-        /** the configured {@link #HERDR_WAIT_SECONDS} budget elapsed with no answer. */
-        DEADLINE_PASSED,
-        /**
-         * the waiting thread was interrupted before the budget ran out — a different event from
-         * {@link #DEADLINE_PASSED} and must never be reported as "did not answer within Ns".
-         */
-        INTERRUPTED
-    }
-
-    /**
-     * The outcome of one {@link #awaitHerdr} call, carrying the MEASURED elapsed wait time
-     * alongside {@link #result}. {@code elapsedNanos} is always measured against the {@code nanos}
-     * supplier passed to {@link #awaitHerdr} — never assume it equals the configured budget, the
-     * same defect fleetd #494 already fixed once in {@code LeadRollover}.
-     */
-    record HerdrAwaitOutcome(HerdrWaitResult result, long elapsedNanos) {}
-
-    /**
-     * The real per-poll wait {@link #main} passes to {@link #awaitHerdr}: sleep
-     * {@link #HERDR_WAIT_POLL_MILLIS}, and on interruption re-set the thread's interrupt flag
-     * rather than throwing — {@link #awaitHerdr} detects an interruption by checking {@link
-     * Thread#isInterrupted()} right after this returns, so a poller that swallowed the flag
-     * instead of restoring it would make that check silently miss the interruption.
-     */
-    private static void sleepHerdrPoll() {
-        try {
-            Thread.sleep(HERDR_WAIT_POLL_MILLIS);
-        } catch (InterruptedException ie) {
-            Thread.currentThread().interrupt();
-        }
-    }
-
-    /**
-     * Poll herdr's {@code ping} until it answers, the configured {@link #HERDR_WAIT_SECONDS}
-     * budget elapses, or the waiting thread is interrupted (CB-504, fleetd #498).
+     * Poll herdr's {@code ping} until it answers or {@link #HERDR_WAIT_SECONDS} elapses (CB-504).
     *
-     * <p>{@code nanos} and {@code poller} are required parameters with no defaulted overload
-     * (fleetd #415's shape: a defaulted overload is a silent survivor a green suite would vouch
-     * for) — the previous version read {@link System#nanoTime()} and called {@link Thread#sleep}
-     * directly, so nothing could drive it from a test. The one production call site in {@link
-     * #main} passes {@code System::nanoTime} and {@link #sleepHerdrPoll}.
-     *
-     * @param nanos  a monotonic elapsed-time clock, e.g. {@code System::nanoTime} — never a
-     *               wall-clock source, since only elapsed time (not a timestamp) is measured here
-     * @param poller called once per failed ping while the budget remains; must, on an
-     *               {@link InterruptedException}, re-set the thread's interrupt flag rather than
-     *               throw or swallow it — this method's interruption check reads that flag right
-     *               after {@code poller.run()} returns
-     * @return the outcome and the measured elapsed wait time — see {@link HerdrAwaitOutcome}
+     * @return true if herdr answered, false if it never did
     */
-    static HerdrAwaitOutcome awaitHerdr(HerdrClient herdr, LongSupplier nanos, Runnable poller) {
-        long start = nanos.getAsLong();
-        long deadline = start + HERDR_WAIT_SECONDS * 1_000_000_000L;
+    private static boolean awaitHerdr(HerdrClient herdr) {
+        long deadline = System.nanoTime() + HERDR_WAIT_SECONDS * 1_000_000_000L;
        boolean waited = false;
        while (true) {
            try {
@@ -1765,57 +1709,25 @@ public final class Fleetd {
                if (waited) {
                    log.info("herdr is up");
                }
-                return new HerdrAwaitOutcome(HerdrWaitResult.ANSWERED, nanos.getAsLong() - start);
+                return true;
            } catch (HerdrException e) {
-                if (nanos.getAsLong() >= deadline) {
-                    return new HerdrAwaitOutcome(HerdrWaitResult.DEADLINE_PASSED, nanos.getAsLong() - start);
+                if (System.nanoTime() >= deadline) {
+                    return false;
                }
                if (!waited) {
                    log.info("waiting up to {}s for the herdr socket…", HERDR_WAIT_SECONDS);
                    waited = true;
                }
-                poller.run();
-                if (Thread.currentThread().isInterrupted()) {
-                    return new HerdrAwaitOutcome(HerdrWaitResult.INTERRUPTED, nanos.getAsLong() - start);
+                try {
+                    Thread.sleep(HERDR_WAIT_POLL_MILLIS);
+                } catch (InterruptedException ie) {
+                    Thread.currentThread().interrupt();
+                    return false;
                }
            }
        }
    }

-    /**
-     * Log the right message for {@code outcome} — never the configured {@link #HERDR_WAIT_SECONDS}
-     * budget alone, always the measured elapsed time next to it — and say whether {@link #main}
-     * should now reap orphan worker panes (fleetd #498).
-     *
-     * <p>Extracted out of {@link #main} so this decision is drivable from a test: {@link #main}
-     * boots the whole daemon and cannot itself be run in a unit test, but this is the exact,
-     * unmodified code {@link #main} calls for the decision, not a re-derivation of it.
-     *
-     * @return true only for {@link HerdrWaitResult#ANSWERED} — orphan workers are reaped only
-     *         then, exactly as before this ticket
-     */
-    static boolean logHerdrWaitOutcomeAndShouldReap(HerdrAwaitOutcome outcome) {
-        long elapsedMillis = TimeUnit.NANOSECONDS.toMillis(outcome.elapsedNanos());
-        if (outcome.result() == HerdrWaitResult.ANSWERED) {
-            return true;
-        }
-        if (outcome.result() == HerdrWaitResult.DEADLINE_PASSED) {
-            log.warn("herdr did not answer within the configured wait (configured={}s elapsed={}ms) "
-                    + "— starting anyway; /healthz will report degraded until it comes up. Orphaned "
-                    + "worker panes (if any) were NOT reaped.",
-                    HERDR_WAIT_SECONDS, elapsedMillis);
-            return false;
-        }
-        // HerdrWaitResult.INTERRUPTED — a different fact from DEADLINE_PASSED (fleetd #498): the
-        // wait was cut short, not exhausted, and must never be reported as "did not answer within
-        // Ns" — that claim would be false and would send an operator to debug herdr for nothing.
-        log.warn("herdr wait was interrupted before the configured wait ran out (configured={}s "
-                + "elapsed={}ms) — starting anyway; /healthz will report degraded until it comes "
-                + "up. Orphaned worker panes (if any) were NOT reaped.",
-                HERDR_WAIT_SECONDS, elapsedMillis);
-        return false;
-    }
-
    private Fleetd() {
    }
 }
@@ -1,212 +0,0 @@
-package dev.ltms.fleet;
-
-import ch.qos.logback.classic.Level;
-import ch.qos.logback.classic.Logger;
-import ch.qos.logback.classic.spi.ILoggingEvent;
-import ch.qos.logback.core.read.ListAppender;
-import com.fasterxml.jackson.databind.JsonNode;
-import dev.ltms.fleet.herdr.HerdrClient;
-import dev.ltms.fleet.herdr.HerdrException;
-import org.junit.jupiter.api.Test;
-import org.slf4j.LoggerFactory;
-
-import java.util.concurrent.atomic.AtomicBoolean;
-import java.util.function.LongSupplier;
-
-import static org.junit.jupiter.api.Assertions.assertEquals;
-import static org.junit.jupiter.api.Assertions.assertFalse;
-import static org.junit.jupiter.api.Assertions.assertTrue;
-import static org.junit.jupiter.api.Assertions.fail;
-
-/**
- * fleetd #498: {@code Fleetd.awaitHerdr} used to return a bare {@code boolean}, collapsing "the
- * configured wait budget genuinely ran out" and "the waiting thread was interrupted, possibly
- * milliseconds in" onto the same {@code false} — and the caller's log line printed only the
- * configured budget, never how long the wait actually ran. This class covers both halves of the
- * fix:
- * <ul>
- *   <li>the seam — {@link Fleetd#awaitHerdr} itself, driven with an injected clock and a stub
- *       {@link HerdrClient}, one test per {@link Fleetd.HerdrWaitResult};</li>
- *   <li>the call site — {@link Fleetd#logHerdrWaitOutcomeAndShouldReap}, the exact decision {@code
- *       main} calls (extracted here because {@code main} itself boots the whole daemon and cannot
- *       be driven from a unit test), pinning the three distinct log messages it emits.</li>
- * </ul>
- * Every expected message below is a plain literal, not built from {@code HERDR_WAIT_SECONDS} or
- * any other production constant — a test that derives its expectation the way the code does
- * cannot see a change to either (fleetd #496's identical trap).
- */
-class FleetdAwaitHerdrTest {
-
-    // ---- the seam: Fleetd.awaitHerdr ----------------------------------------------------------
-
-    @Test
-    void answeredReturnsImmediatelyWithZeroElapsedAndNeverPolls() {
-        HerdrStub herdr = new HerdrStub(0); // succeeds on the very first call
-        LongSupplier clock = fixedClock(1_000L);
-        AtomicBoolean polled = new AtomicBoolean(false);
-        Runnable poller = () -> polled.set(true);
-
-        Fleetd.HerdrAwaitOutcome outcome = Fleetd.awaitHerdr(herdr, clock, poller);
-
-        assertEquals(Fleetd.HerdrWaitResult.ANSWERED, outcome.result());
-        assertEquals(0L, outcome.elapsedNanos(), "a fixed clock must measure zero elapsed time");
-        assertFalse(polled.get(), "herdr answering on the first try must never poll");
-    }
-
-    @Test
-    void deadlinePassedIsMeasuredNotAssumed() {
-        HerdrStub herdr = new HerdrStub(-1); // never succeeds
-        // call order inside awaitHerdr: start, then per failed attempt: deadline-check, elapsed-calc
-        ScriptedClock clock = new ScriptedClock(0L, 30_500_000_000L, 30_500_000_000L);
-        Runnable poller = () -> fail("the deadline was already exceeded on the first attempt — must not poll");
-
-        Fleetd.HerdrAwaitOutcome outcome = Fleetd.awaitHerdr(herdr, clock, poller);
-
-        assertEquals(Fleetd.HerdrWaitResult.DEADLINE_PASSED, outcome.result());
-        assertEquals(30_500_000_000L, outcome.elapsedNanos(),
-                "elapsed must be the MEASURED clock delta, not the configured budget");
-    }
-
-    @Test
-    void interruptedIsDistinctFromDeadlinePassedAndPreservesTheInterruptFlag() {
-        HerdrStub herdr = new HerdrStub(-1); // never succeeds
-        // start=0, deadline-check returns 500ms (well under the 30s budget) -> not deadline-passed,
-        // then the poller interrupts, and the elapsed-calc call returns 750ms.
-        ScriptedClock clock = new ScriptedClock(0L, 500_000_000L, 750_000_000L);
-        Runnable poller = () -> Thread.currentThread().interrupt();
-
-        try {
-            Fleetd.HerdrAwaitOutcome outcome = Fleetd.awaitHerdr(herdr, clock, poller);
-
-            assertEquals(Fleetd.HerdrWaitResult.INTERRUPTED, outcome.result());
-            assertEquals(750_000_000L, outcome.elapsedNanos(),
-                    "elapsed must be measured even when the wait ends via interruption, not the deadline");
-            assertTrue(Thread.currentThread().isInterrupted(),
-                    "the interrupt flag the old code re-set must still be set on return");
-        } finally {
-            Thread.interrupted(); // clear it so it cannot leak into another test on this thread
-        }
-    }
-
-    // ---- the call site: Fleetd.logHerdrWaitOutcomeAndShouldReap -------------------------------
-
-    @Test
-    void answeredLogsNothingAndSaysReap() {
-        ListAppender<ILoggingEvent> events = attach();
-        try {
-            boolean shouldReap = Fleetd.logHerdrWaitOutcomeAndShouldReap(
-                    new Fleetd.HerdrAwaitOutcome(Fleetd.HerdrWaitResult.ANSWERED, 0L));
-
-            assertTrue(shouldReap, "only ANSWERED should tell main to reap orphan workers");
-            assertEquals(0, events.list.size(), "the answered path logs nothing itself");
-        } finally {
-            detach(events);
-        }
-    }
-
-    @Test
-    void deadlinePassedLogsConfiguredAndMeasuredElapsedTogether() {
-        ListAppender<ILoggingEvent> events = attach();
-        try {
-            boolean shouldReap = Fleetd.logHerdrWaitOutcomeAndShouldReap(
-                    new Fleetd.HerdrAwaitOutcome(Fleetd.HerdrWaitResult.DEADLINE_PASSED, 30_500_000_000L));
-
-            assertFalse(shouldReap, "a deadline-passed wait must not tell main to reap");
-            assertEquals(1, events.list.size());
-            ILoggingEvent event = events.list.getFirst();
-            assertEquals(Level.WARN, event.getLevel());
-            assertEquals("herdr did not answer within the configured wait (configured=30s "
-                    + "elapsed=30500ms) — starting anyway; /healthz will report degraded until it "
-                    + "comes up. Orphaned worker panes (if any) were NOT reaped.",
-                    event.getFormattedMessage());
-        } finally {
-            detach(events);
-        }
-    }
-
-    @Test
-    void interruptedLogsItsOwnMessageAndNeverClaimsTheBudgetElapsed() {
-        ListAppender<ILoggingEvent> events = attach();
-        try {
-            // 3ms: the ticket's own example of "a few milliseconds in", not the 30s budget.
-            boolean shouldReap = Fleetd.logHerdrWaitOutcomeAndShouldReap(
-                    new Fleetd.HerdrAwaitOutcome(Fleetd.HerdrWaitResult.INTERRUPTED, 3_000_000L));
-
-            assertFalse(shouldReap, "an interrupted wait must not tell main to reap");
-            assertEquals(1, events.list.size());
-            ILoggingEvent event = events.list.getFirst();
-            assertEquals(Level.WARN, event.getLevel());
-            String message = event.getFormattedMessage();
-            assertEquals("herdr wait was interrupted before the configured wait ran out "
-                    + "(configured=30s elapsed=3ms) — starting anyway; /healthz will report "
-                    + "degraded until it comes up. Orphaned worker panes (if any) were NOT reaped.",
-                    message);
-            assertFalse(message.contains("did not answer"),
-                    "an interrupted wait must not be reported as if herdr failed to answer within the budget");
-        } finally {
-            detach(events);
-        }
-    }
-
-    // ---- fixtures --------------------------------------------------------------------------
-
-    /** Always returns the same value, i.e. a clock that measures zero elapsed time. */
-    private static LongSupplier fixedClock(long value) {
-        return () -> value;
-    }
-
-    /** Returns each value in order, then repeats the last one for any call beyond the list. */
-    private static final class ScriptedClock implements LongSupplier {
-        private final long[] values;
-        private int index;
-
-        ScriptedClock(long... values) {
-            this.values = values;
-        }
-
-        @Override
-        public long getAsLong() {
-            long v = values[Math.min(index, values.length - 1)];
-            if (index < values.length - 1) {
-                index++;
-            }
-            return v;
-        }
-    }
-
-    /** Fails {@code failuresBeforeSuccess} times, then succeeds forever; {@code -1} never succeeds. */
-    private static final class HerdrStub implements HerdrClient {
-        private final int failuresBeforeSuccess;
-        private int calls;
-
-        HerdrStub(int failuresBeforeSuccess) {
-            this.failuresBeforeSuccess = failuresBeforeSuccess;
-        }
-
-        @Override
-        public JsonNode call(String method, Object params) throws HerdrException {
-            calls++;
-            if (failuresBeforeSuccess < 0 || calls <= failuresBeforeSuccess) {
-                throw new HerdrException("herdr not up yet");
-            }
-            return null;
-        }
-
-        @Override
-        public void close() {
-        }
-    }
-
-    private static ListAppender<ILoggingEvent> attach() {
-        Logger logger = (Logger) LoggerFactory.getLogger(Fleetd.class);
-        logger.setLevel(Level.DEBUG);
-        ListAppender<ILoggingEvent> appender = new ListAppender<>();
-        appender.start();
-        logger.addAppender(appender);
-        return appender;
-    }
-
-    private static void detach(ListAppender<ILoggingEvent> appender) {
-        ((Logger) LoggerFactory.getLogger(Fleetd.class)).detachAppender(appender);
-    }
-}
@@ -5,7 +5,7 @@
 # A merge is not a deployment: the running daemon holds the jar it was started with, so code merged
 # to main does nothing until this runs. See CLAUDE.md -> "Redeploying the daemon".
 #
-# This script exists to turn six remembered traps into one auditable command:
+# This script exists to turn eight remembered traps into one auditable command:
 #
 #   1. A piped `mvn` hides BUILD FAILURE behind a zero exit, so the build here is never piped.
 #   2. The daemon must start from a LOGIN shell, or the tokens it hands to members are empty:
@@ -27,6 +27,17 @@
 #      restart of the OLD jar. So this script detects whether the agent is loaded and, only then,
 #      swaps `kill` + manual `nohup` for `launchctl unload`/`load` — the one supervisor in control
 #      at any moment is whichever one you asked to act, never both.
+#   7. fleetd #492 — a systemd --user unit is a THIRD possible supervisor (seen on a second host):
+#      Restart=on-failure treats this JVM's SIGTERM exit code (143, per CB-594 above) as a failure
+#      too, so a bare `kill` there would race systemd's own restart of the OLD jar exactly like
+#      launchd would. This script now tells launchd, systemd, and "genuinely unsupervised" apart as
+#      three different answers, drives whichever one it finds through its own control plane
+#      (`launchctl` / `systemctl --user`), and REFUSES outright — never falls back to `kill` — when
+#      it finds a supervision signal it cannot map to exactly one of the two it knows how to drive.
+#      A wrong guess here is how two daemons end up running against one herdr session.
+#   8. fleetd #492 — a post-restart check counts running fleetd processes and fails the whole run if
+#      more than one is alive. That is the one thing none of the checks above (healthz 200, jar id,
+#      the fresh "listening" line) can see: every one of them is satisfied by EITHER daemon.
 #
 # Usage:
 #   scripts/redeploy-fleetd.sh              # build, confirm, restart, verify
@@ -55,13 +66,18 @@ HEALTH_WAIT=60    # seconds to wait for /healthz to answer after start
 LAUNCHD_LABEL='dev.ltms.fleetd'
 LAUNCHD_PLIST="$HOME/Library/LaunchAgents/$LAUNCHD_LABEL.plist"

+# fleetd #492: the systemd --user unit this script must not fight with either (see trap 7 above).
+# Measured on the second host: `systemctl --user cat fleetd` names the unit "fleetd" (not
+# "dev.ltms.fleetd" — systemd user units here are not namespaced the way the launchd label is).
+SYSTEMD_UNIT='fleetd'
+
 DO_BUILD=1; ASSUME_YES=0; CHECK_ONLY=0
 for arg in "$@"; do
  case "$arg" in
    --yes|-y)   ASSUME_YES=1 ;;
    --no-build) DO_BUILD=0 ;;
    --check)    CHECK_ONLY=1 ;;
-    -h|--help)  sed -n '3,37p' "${BASH_SOURCE[0]}"; exit 0 ;;
+    -h|--help)  sed -n '3,48p' "${BASH_SOURCE[0]}"; exit 0 ;;
    *) echo "unknown option: $arg (try --help)" >&2; exit 2 ;;
  esac
 done
@@ -79,6 +95,91 @@ running_pid() { pgrep -f "$PATTERN" || true; }
 launchd_installed() { [ -f "$LAUNCHD_PLIST" ]; }
 launchd_loaded() { launchctl list "$LAUNCHD_LABEL" >/dev/null 2>&1; }

+# fleetd #492: same two questions for systemd --user. Kept as separate, overridable functions
+# (never an inline `systemctl` call at each use site) so a test on a box with no systemd at all
+# (this repo is developed on macOS) can substitute each one independently — the same seam
+# launchd_installed/launchd_loaded above already use.
+#
+# "installed": a unit FILE by this name exists, regardless of its current state — the systemd
+# analogue of the plist file existing on disk. `list-unit-files` reads unit definitions without
+# depending on runtime state, so this stays read-only and safe under --check.
+systemd_installed() {
+  command -v systemctl >/dev/null 2>&1 \
+    && systemctl --user list-unit-files "$SYSTEMD_UNIT.service" --no-legend 2>/dev/null | grep -q .
+}
+# "loaded": systemd currently supervises this unit as an active job — the systemd analogue of
+# `launchctl list <label>` succeeding. Measured on the second host: `systemctl --user is-active
+# fleetd` -> "active".
+systemd_loaded() {
+  command -v systemctl >/dev/null 2>&1 && systemctl --user is-active "$SYSTEMD_UNIT" >/dev/null 2>&1
+}
+
+# fleetd #492: three real answers, not two — launchd, systemd, or genuinely unsupervised — plus a
+# fourth, "ambiguous", for the one case this script cannot tell apart: both signals firing at once.
+# That is exactly "I cannot tell who supervises this process", and guessing wrong here is how two
+# daemons end up running against one herdr session (see trap 7 in the header). Pure and
+# side-effect-free: reads the two probes above and decides — never mutates anything, so it is safe
+# under --check and testable by overriding launchd_loaded/systemd_loaded after sourcing.
+detect_supervisor() {
+  local ld=0 sd=0
+  launchd_loaded && ld=1
+  systemd_loaded && sd=1
+  if [ "$ld" = 1 ] && [ "$sd" = 1 ]; then
+    echo "ambiguous"
+  elif [ "$ld" = 1 ]; then
+    echo "launchd"
+  elif [ "$sd" = 1 ]; then
+    echo "systemd"
+  else
+    echo "none"
+  fi
+}
+
+# fleetd #492: turns anything detect_supervisor returns that is NOT exactly one of the two
+# supervisors this script knows how to drive into a die() — never a fall-through to the `kill`
+# path. Kept as its own function so a test can call it directly (in a subshell, since it die()s)
+# without running the whole report-state flow or needing a real launchd/systemd.
+require_drivable_supervisor() {
+  local kind="$1"
+  case "$kind" in
+    launchd|systemd|none) ;;
+    ambiguous)
+      die "both launchd ($LAUNCHD_LABEL) and systemd --user ($SYSTEMD_UNIT) report themselves as
+          loaded for this daemon at the same time. This script cannot tell which one actually
+          supervises the running process, and driving either alone risks the OTHER reviving the
+          OLD jar out from under it — the exact failure this ticket (fleetd #492) exists to
+          prevent. Stop one of the two supervisors by hand, confirm only one remains loaded, then
+          rerun." ;;
+    *)
+      die "detect_supervisor returned an unrecognized value '$kind' — refusing to guess which
+          supervisor, if any, controls this daemon." ;;
+  esac
+}
+
+# fleetd #492: the exact symptom a racing supervisor produces — count how many fleetd processes are
+# alive right now. Takes the pid list as a parameter (rather than calling running_pid() itself) so a
+# test can pass a canned two-line string without a real second process running. Pure except for the
+# die() in assert_single_daemon below.
+count_daemon_pids() {
+  local pids="$1"
+  if [ -z "$pids" ]; then
+    echo 0
+  else
+    printf '%s\n' "$pids" | grep -c .
+  fi
+}
+assert_single_daemon() {
+  local pids="$1" count
+  count="$(count_daemon_pids "$pids")"
+  if [ "$count" -gt 1 ]; then
+    die "more than one fleetd process is running after this restart (pids: $(printf '%s' "$pids" | tr '\n' ' ')).
+        This is the exact failure a racing supervisor produces: the OLD jar was revived by its
+        supervisor while this script started a NEW copy. Two daemons on one herdr session kill
+        each other's members. Investigate with 'pgrep -f \"$PATTERN\"' and stop the wrong one by
+        hand — do not assume either pid is the one you want."
+  fi
+}
+
 # CB-600: the script computes its own log path from where it sits on disk (REPO, above); the
 # plist hard-codes an absolute StandardOutPath. Nothing forced the two to agree — if this script
 # were ever run from a checkout other than the one the loaded plist names, launchd would start and
@@ -182,25 +283,45 @@ fi
 ok "jar on disk: $(jar_id)  ($([ -f "$JAR" ] && date -r "$JAR" '+%Y-%m-%d %H:%M:%S' || echo 'none'))"
 ok "HEAD: $(git -C "$REPO" log --oneline -1)"

-# CB-594: supervision state. Installed and loaded are different facts — a copied-but-never-loaded
-# plist supervises nothing, and a loaded label with no file backing it (rare, but possible after an
-# edited/moved plist) is still what launchd will act on.
+# CB-594 / fleetd #492: supervision state. Installed and loaded are different facts — a
+# copied-but-never-loaded plist (or an unloaded systemd unit) supervises nothing, and a loaded
+# label/unit with no file backing it is still what its supervisor will act on.
 if launchd_installed; then
  ok "launchd agent installed: $LAUNCHD_PLIST"
 else
-  warn "launchd agent NOT installed (no supervision — a crash will not restart the daemon)."
+  warn "launchd agent NOT installed."
 fi
-SUPERVISED=0
-if launchd_loaded; then
-  SUPERVISED=1
-  ok "launchd agent loaded ($LAUNCHD_LABEL) — launchd supervises this daemon"
-  # CB-600: fail loudly here, before ANY other check runs, if this script and the loaded plist
-  # would read different log files — every check after this point is worthless otherwise.
-  check_log_path_matches_plist "$OUT" "$LAUNCHD_PLIST"
+if systemd_installed; then
+  ok "systemd --user unit installed: $SYSTEMD_UNIT"
 else
-  warn "launchd agent not loaded — this script is the only thing that will restart the daemon."
+  warn "systemd --user unit NOT installed ($SYSTEMD_UNIT)."
 fi

+# fleetd #492: decide which of the two (if either) actually supervises this daemon, and refuse
+# outright — before touching anything — if that cannot be told apart (see require_drivable_
+# supervisor above). --check reaches this same line, so a host with an undrivable supervisor is
+# reported as a failure even in --check, without ever reaching the build/stop/start steps.
+SUPERVISOR_KIND="$(detect_supervisor)"
+require_drivable_supervisor "$SUPERVISOR_KIND"
+ok "supervisor detected: $SUPERVISOR_KIND"
+SUPERVISED=0
+case "$SUPERVISOR_KIND" in
+  launchd)
+    SUPERVISED=1
+    ok "launchd agent loaded ($LAUNCHD_LABEL) — launchd supervises this daemon"
+    # CB-600: fail loudly here, before ANY other check runs, if this script and the loaded plist
+    # would read different log files — every check after this point is worthless otherwise.
+    check_log_path_matches_plist "$OUT" "$LAUNCHD_PLIST"
+    ;;
+  systemd)
+    SUPERVISED=1
+    ok "systemd --user unit active ($SYSTEMD_UNIT) — systemd supervises this daemon"
+    ;;
+  none)
+    warn "no supervisor loaded — this script is the only thing that will restart the daemon."
+    ;;
+esac
+
 # The trap with no log line. Checked in a LOGIN shell, because that is how the daemon is started
 # below. Never prints the value — only whether it resolved.
 if zsh -lc '[ -n "${WORKER_GITEA_TOKEN:-}" ]' 2>/dev/null; then
@@ -281,25 +402,39 @@ fi

 # ------------------------------------------------------------------ stop
 #
-# CB-594: when SUPERVISED, launchd owns the stop — never a raw `kill` here. A bare SIGTERM makes
-# this JVM exit 143 even with its shutdown hook running to completion (verified separately: a
-# throwaway Java process with an equivalent shutdown hook, sent SIGTERM from a login shell that
-# could `wait` on it directly, reported exit code 143 every time — never 0). launchd's
-# KeepAlive.SuccessfulExit=false treats any nonzero exit as a crash and restarts the OLD jar,
-# which would race this script's own restart of the NEW one. `launchctl unload` avoids that race
-# by deregistering the job first, so no KeepAlive is left armed when the process actually stops.
+# CB-594 / fleetd #492: when SUPERVISED, the supervisor owns the stop — never a raw `kill` here. A
+# bare SIGTERM makes this JVM exit 143 even with its shutdown hook running to completion (verified
+# separately: a throwaway Java process with an equivalent shutdown hook, sent SIGTERM from a login
+# shell that could `wait` on it directly, reported exit code 143 every time — never 0). launchd's
+# KeepAlive.SuccessfulExit=false and systemd's Restart=on-failure both treat any nonzero exit as a
+# crash and restart the OLD jar, which would race this script's own restart of the NEW one.
+# `launchctl unload` avoids that race by deregistering the job first, so no KeepAlive is left
+# armed when the process actually stops. `systemctl --user stop` needs no such dance: unlike
+# KeepAlive, systemd's Restart= does not fire on a deliberate stop, only on an unexpected exit of
+# an active unit.

 if [ -n "$OLD_PID" ]; then
  say "stop"
  RESTART_MARK="$(wc -l < "$OUT" 2>/dev/null || echo 0)"   # verify a FRESH line appears later
-  if [ "$SUPERVISED" = 1 ]; then
-    echo "   supervision is ON: using 'launchctl unload' (not kill) so launchd's own KeepAlive"
-    echo "   cannot restart the OLD jar out from under this script — see the CB-594 comment above."
-    launchctl unload -w "$LAUNCHD_PLIST" \
-      || die "launchctl unload failed — the daemon may still be under supervision; investigate before retrying"
-  else
-    kill "$OLD_PID"
-  fi
+  case "$SUPERVISOR_KIND" in
+    launchd)
+      echo "   supervision is ON (launchd): using 'launchctl unload' (not kill) so launchd's own"
+      echo "   KeepAlive cannot restart the OLD jar out from under this script — see the CB-594"
+      echo "   comment above."
+      launchctl unload -w "$LAUNCHD_PLIST" \
+        || die "launchctl unload failed — the daemon may still be under supervision; investigate before retrying"
+      ;;
+    systemd)
+      echo "   supervision is ON (systemd --user): using 'systemctl --user stop' (not kill) so"
+      echo "   systemd's own Restart=on-failure cannot restart the OLD jar out from under this"
+      echo "   script — see the fleetd #492 comment above."
+      systemctl --user stop "$SYSTEMD_UNIT" \
+        || die "'systemctl --user stop $SYSTEMD_UNIT' failed — the daemon may still be under supervision; investigate before retrying"
+      ;;
+    none)
+      kill "$OLD_PID"
+      ;;
+  esac
  for _ in $(seq "$STOP_WAIT"); do
    [ -z "$(running_pid)" ] && break
    sleep 1
@@ -310,13 +445,20 @@ if [ -n "$OLD_PID" ]; then
        leave worktrees and panes behind. Investigate, then kill -9 by hand if you accept that."
  fi
  ok "pid $OLD_PID exited"
-elif [ "$SUPERVISED" = 1 ]; then
+elif [ "$SUPERVISOR_KIND" = "launchd" ]; then
  # Loaded but not currently running (e.g. throttled after a crash loop). Unload it anyway so the
  # start step below does a clean load, never a load stacked on an already-loaded label.
  say "stop"
  RESTART_MARK="$(wc -l < "$OUT" 2>/dev/null || echo 0)"
  launchctl unload -w "$LAUNCHD_PLIST" 2>/dev/null || true
  ok "launchd agent unloaded (was already not running)"
+elif [ "$SUPERVISOR_KIND" = "systemd" ]; then
+  # Same case for systemd: the unit is known/active-capable but not currently running. `stop` on an
+  # already-stopped unit is a harmless no-op — kept for symmetry with the launchd branch above.
+  say "stop"
+  RESTART_MARK="$(wc -l < "$OUT" 2>/dev/null || echo 0)"
+  systemctl --user stop "$SYSTEMD_UNIT" 2>/dev/null || true
+  ok "systemd --user unit stopped (was already not running)"
 else
  RESTART_MARK="$(wc -l < "$OUT" 2>/dev/null || echo 0)"
 fi
@@ -324,34 +466,48 @@ fi
 # ------------------------------------------------------------------ start
 # Unsupervised: login shell (zsh -l) is what puts the secrets on the daemon's environment, and cwd
 # must be fleetd/ because the daemon resolves fleetd.yaml, logs/ and target/ relative to it.
-# Supervised: launchd does both — deploy/dev.ltms.fleetd.plist points ProgramArguments at
+# Supervised (launchd): launchd does both — deploy/dev.ltms.fleetd.plist points ProgramArguments at
 # scripts/fleetd-launchd-wrapper.sh (CB-594), which is what execs the login shell in launchd's
 # place, and WorkingDirectory in the plist already pins fleetd/.
+# Supervised (systemd --user): the unit does both too — measured on the second host, ExecStart is
+# `/bin/zsh -lc "exec java -jar target/fleetd.jar fleetd.yaml"` (a login shell, same reason as
+# above) and WorkingDirectory is already pinned to fleetd/.

 say "start"
-if [ "$SUPERVISED" = 1 ]; then
-  echo "   supervision is ON: using 'launchctl load' so launchd starts and keeps supervising this"
-  echo "   process, instead of a manual nohup that launchd would know nothing about."
-  # CB-600: 'launchctl unload -w' above already persisted Disabled=true for this label. A load -w
-  # that succeeds clears it; a load -w that FAILS leaves the agent both stopped and disabled — worse
-  # than before this script ran, because a later reboot or login will not bring it back either. One
-  # retry covers a transient race (e.g. launchd not yet fully done deregistering); if it still fails,
-  # die with the exact recovery command rather than a bare "failed".
-  if ! launchctl load -w "$LAUNCHD_PLIST" 2>/dev/null; then
-    warn "launchctl load failed on the first attempt — retrying once after a short pause"
-    sleep 2
-    launchctl load -w "$LAUNCHD_PLIST" || die "launchctl load failed twice.
-        The agent is now STOPPED and DISABLED — it will NOT come back on its own, not even after a
-        reboot or login, because 'launchctl unload -w' above persisted Disabled=true and load -w
-        never got the chance to clear it. Recover with:
-            launchctl load -w \"$LAUNCHD_PLIST\"
-        If that still fails, check 'launchctl list $LAUNCHD_LABEL', validate the plist with
-        'plutil -lint \"$LAUNCHD_PLIST\"', and check $OUT before assuming a retry will succeed."
-  fi
-else
-  # Absolute jar path so `ps` names which checkout is running.
-  ( cd "$MODULE" && zsh -lc "nohup java -jar '$JAR' >> fleetd.out 2>&1 &" )
-fi
+case "$SUPERVISOR_KIND" in
+  launchd)
+    echo "   supervision is ON (launchd): using 'launchctl load' so launchd starts and keeps"
+    echo "   supervising this process, instead of a manual nohup that launchd would know nothing"
+    echo "   about."
+    # CB-600: 'launchctl unload -w' above already persisted Disabled=true for this label. A load -w
+    # that succeeds clears it; a load -w that FAILS leaves the agent both stopped and disabled — worse
+    # than before this script ran, because a later reboot or login will not bring it back either. One
+    # retry covers a transient race (e.g. launchd not yet fully done deregistering); if it still fails,
+    # die with the exact recovery command rather than a bare "failed".
+    if ! launchctl load -w "$LAUNCHD_PLIST" 2>/dev/null; then
+      warn "launchctl load failed on the first attempt — retrying once after a short pause"
+      sleep 2
+      launchctl load -w "$LAUNCHD_PLIST" || die "launchctl load failed twice.
+          The agent is now STOPPED and DISABLED — it will NOT come back on its own, not even after a
+          reboot or login, because 'launchctl unload -w' above persisted Disabled=true and load -w
+          never got the chance to clear it. Recover with:
+              launchctl load -w \"$LAUNCHD_PLIST\"
+          If that still fails, check 'launchctl list $LAUNCHD_LABEL', validate the plist with
+          'plutil -lint \"$LAUNCHD_PLIST\"', and check $OUT before assuming a retry will succeed."
+    fi
+    ;;
+  systemd)
+    echo "   supervision is ON (systemd --user): using 'systemctl --user start' so systemd starts"
+    echo "   and keeps supervising this process, instead of a manual nohup it would know nothing"
+    echo "   about."
+    systemctl --user start "$SYSTEMD_UNIT" || die "'systemctl --user start $SYSTEMD_UNIT' failed.
+        Check 'systemctl --user status $SYSTEMD_UNIT' and $OUT before assuming a retry will succeed."
+    ;;
+  none)
+    # Absolute jar path so `ps` names which checkout is running.
+    ( cd "$MODULE" && zsh -lc "nohup java -jar '$JAR' >> fleetd.out 2>&1 &" )
+    ;;
+esac

 for _ in $(seq 10); do
  NEW_PID="$(running_pid)"
@@ -411,6 +567,13 @@ FRESH_LOG="$(mktemp -t fleetd-fresh-log)"
 trap 'rm -f "$FRESH_LOG"' EXIT
 tail -n "+$((RESTART_MARK + 1))" "$OUT" > "$FRESH_LOG" 2>/dev/null || true
 classify_amqp_connection_errors "$FRESH_LOG"
+
+# fleetd #492: checked here, after healthz and the fresh-log check have both had time to run, so a
+# supervisor that revives the OLD jar a few seconds late is caught too. Every check above (healthz
+# 200, jar id, the fresh 'listening' line) is satisfied by EITHER daemon if two are alive — this is
+# the only one that can tell.
+assert_single_daemon "$(running_pid)"
+
 say "result"
 ok "pid $NEW_PID, jar $(jar_id)"
 if [ "$REDEPLOY_ERROR_COUNT" -eq 0 ]; then
@@ -25,6 +25,78 @@ classify_fixture() {
  classify_amqp_connection_errors "$TMP/$name"
 }

+
+# fleetd #492 — supervisor detection. Detect_supervisor() reads launchd_loaded/systemd_loaded, so
+# each test overrides BOTH pairs (installed + loaded) explicitly, rather than relying on either
+# being naturally absent: this machine may itself be running a real fleetd under launchd right now
+# (see CLAUDE.md/MEMORY.md — launchd supervision has been live here since 2026-08-26), so leaving
+# launchd_loaded unmocked in a "systemd only" test would silently read this host's own live state
+# instead of the fixture.
+test_detect_supervisor_launchd_only() {
+  launchd_installed() { return 0; }
+  launchd_loaded()    { return 0; }
+  systemd_installed() { return 1; }
+  systemd_loaded()    { return 1; }
+  assert_equals "launchd" "$(detect_supervisor)" "launchd-only detection"
+}
+
+test_detect_supervisor_systemd_only() {
+  launchd_installed() { return 1; }
+  launchd_loaded()    { return 1; }
+  systemd_installed() { return 0; }
+  systemd_loaded()    { return 0; }
+  assert_equals "systemd" "$(detect_supervisor)" "systemd-only detection"
+}
+
+test_detect_supervisor_none() {
+  launchd_installed() { return 1; }
+  launchd_loaded()    { return 1; }
+  systemd_installed() { return 1; }
+  systemd_loaded()    { return 1; }
+  assert_equals "none" "$(detect_supervisor)" "unsupervised detection"
+}
+
+# The heart of the ticket: a supervisor this script cannot drive must refuse, never fall through to
+# `kill`. require_drivable_supervisor die()s, so it is invoked inside a command substitution — that
+# forks a subshell, so its exit() only ends the subshell and this test script keeps running under
+# `set -e`.
+test_require_drivable_supervisor_refuses_ambiguous() {
+  local output rc=0
+  output="$(require_drivable_supervisor "ambiguous" 2>&1)" || rc=$?
+  [ "$rc" -ne 0 ] || fail "require_drivable_supervisor accepted an ambiguous (undrivable) supervisor"
+  printf '%s' "$output" | grep -qF "$LAUNCHD_LABEL" \
+    || fail "refusal message does not name the launchd label it found"
+  printf '%s' "$output" | grep -qF "$SYSTEMD_UNIT" \
+    || fail "refusal message does not name the systemd unit it found"
+}
+
+test_require_drivable_supervisor_accepts_known_kinds() {
+  require_drivable_supervisor "launchd" || fail "refused a drivable launchd supervisor"
+  require_drivable_supervisor "systemd" || fail "refused a drivable systemd supervisor"
+  require_drivable_supervisor "none"    || fail "refused the unsupervised case"
+}
+
+# fleetd #492 — the one-daemon check. Two live pids is the exact symptom a racing supervisor
+# produces, and none of the other post-restart checks (healthz, jar id, the fresh log line) can see
+# it because either daemon alone satisfies them.
+test_count_daemon_pids() {
+  assert_equals 0 "$(count_daemon_pids "")" "count of an empty pid list"
+  assert_equals 1 "$(count_daemon_pids "4242")" "count of a single pid"
+  assert_equals 2 "$(count_daemon_pids "$(printf '4242\n4343\n')")" "count of two pids"
+}
+
+test_assert_single_daemon_accepts_one_pid() {
+  assert_single_daemon "4242" || fail "assert_single_daemon rejected a single running pid"
+}
+
+test_assert_single_daemon_rejects_two_pids() {
+  local output rc=0
+  output="$(assert_single_daemon "$(printf '4242\n4343\n')" 2>&1)" || rc=$?
+  [ "$rc" -ne 0 ] || fail "assert_single_daemon accepted two simultaneously running pids"
+  printf '%s' "$output" | grep -qF '4242' || fail "refusal message does not list the pids it found"
+  printf '%s' "$output" | grep -qF '4343' || fail "refusal message does not list the pids it found"
+}
+
 test_no_errors() {
  cat > "$TMP/no-errors.log" <<'LOG'
 2026-09-05 12:00:00 INFO fleetd listening
@@ -224,6 +296,14 @@ test_unattributable_quiet_mutation_is_caught() {
  printf 'Unattributable mutation: FAIL: cross-unattributable recovered: expected 0, got 2\n'
 }

+test_detect_supervisor_launchd_only
+test_detect_supervisor_systemd_only
+test_detect_supervisor_none
+test_require_drivable_supervisor_refuses_ambiguous
+test_require_drivable_supervisor_accepts_known_kinds
+test_count_daemon_pids
+test_assert_single_daemon_accepts_one_pid
+test_assert_single_daemon_rejects_two_pids
 test_no_errors
 test_recovery_patterns_match_source
 test_attributed_recovered_connection_error