CB-602: guard against a config key that never reaches the example

BridgedConfig.KNOWN_TOP_LEVEL_KEYS is now package-private so a test can assert
every key the parser accepts appears in bridged.example.yaml — live or
commented-out, since the file is gitignored and the example is the only
committed description of the config schema. The existing tests only checked
the example->code direction; this adds code->example.

CLAUDE.md

@@ -81,9 +81,9 @@ below are the procedure — run them in order, every task, not only the big ones
 5. **Collect** — `bridge_poll{ticket}` → `bridge_ack{ticket, msgId}`. Answer a worker's `bridge_ask`
    with `bridge_send{turnId, content}` — **not** `sessionId`. A worker gone quiet is diagnosed with
    `bridge_status`, never by reading its terminal.
-6. **Verify yourself.** Re-run the build and the checks. A worker mounts only the bridge MCP and
-   cannot run your other tooling, and a piped command (`… | tail`) hides failures behind a zero
-   exit — never promote a worker's "clean" to a fact.
+6. **Verify yourself.** Re-run the build and the checks. A worker cannot run your IDE tooling, any
+   forge tools it appears to have hold a blocked credential and fail, and a piped command
+   (`… | tail`) hides failures behind a zero exit — never promote a worker's "clean" to a fact.
 7. **Review — fan out.** Spawn reviewers against the diff, one per dimension or per file, with
    `wait:false`. Never the implementer of the scope it reviews, and brief them from the diff — not
    from the implementer's rationale, which carries its own blind spot. Dispatch each PR's reviewers
@@ -155,9 +155,13 @@ you.
    without replying, the bridge scrapes your pane, and it can return only the last 4000 characters.
    A clipped scrape is marked as partial, but the missing text is gone — your report reaches the
    lead with its end cut off.
-5. **Report honestly.** State only what you actually ran and its real output, including failures.
-   You mount **only** the bridge MCP — the primary's other servers (IDE, forge, docs) are not yours,
-   so never claim the result of a check you had no way to run.
+5. **Report honestly.** State only what you actually ran and its real output, including failures,
+   and never claim the result of a check you had no way to run. **Measure your own tools; do not
+   assume them.** What you mount depends on your backend: an opencode member gets the bridge and
+   nothing else, while a Claude Code member also inherits the operator's user-scope MCP servers,
+   which the bridge never chose for you. Two rules follow. The primary's IDE tooling is still not
+   yours, whatever you see. And **a mounted tool is not a working tool** — the forge server you may
+   find there holds a deliberately blocked credential and fails every call, by design.
 6. **Never merge.** Stage files explicitly — never `git add -A` — and leave alone anything the
    project marks as not-yours-to-commit.
 

bridged/bridged.example.yaml

@@ -88,15 +88,28 @@ bind:
 #   backoffMs: 60000
 #   quietNudgeCap: 3
 
-# Fleet health detection is dormant unless enabled. It reads one whole-fleet agent list per tick.
-# It can run without a webhook; bridge_list then reports healthCoverage: detection-only.
+# Fleet health detection is dormant unless enabled (CB-573). It reads one whole-fleet agent list
+# per tick.
+#   intervalSeconds → how often a tick runs (default 30). ENFORCED floor of 15: the code computes
+#                      Math.max(15, intervalSeconds), so a lower value is silently raised, not
+#                      rejected.
+#   workingSuspectAfterSeconds, paneProbeIntervalSeconds → accepted and parsed, but NOT YET READ by
+#                      anything — the dormant monitor only consumes intervalSeconds today (CB-573
+#                      shipped ahead of the evidence publishers these two knobs are for). Setting
+#                      them changes nothing right now, and no minimum is enforced on either, because
+#                      nothing reads them to enforce one. They exist so a later build can start
+#                      honouring them without another config-shape change.
+#   notifications.mode → "webhook" flips what bridge_list REPORTS (healthCoverage: "full" instead
+#                      of "detection-only") — it does NOT make bridged send any webhook call; no
+#                      delivery mechanism is implemented yet. Any other value, or omitting the
+#                      block, reports "detection-only".
 # health:
 #   enabled: true
-#   intervalSeconds: 30              # minimum 15
-#   workingSuspectAfterSeconds: 600  # minimum 300
-#   paneProbeIntervalSeconds: 60     # minimum 60
+#   intervalSeconds: 30
+#   workingSuspectAfterSeconds: 600
+#   paneProbeIntervalSeconds: 60
 #   notifications:
-#     mode: disabled                 # disabled (default) or webhook
+#     mode: disabled
 
 # herdr Unix socket. Omit to use the client default
 # (${HERDR_SOCKET_PATH:-~/.config/herdr/herdr.sock}).
@@ -286,6 +299,11 @@ placement: weighted
 #               / credentialId. Those are hot because the placement policy (and, for credentialId,
 #               the CB-578 stage B quarantine check) reads them through a supplier — being config is
 #               not by itself enough to make a key hot.
+#               EXCEPT `fleet.leaders`: Bridged.main reads it once at startup to build the lead tab
+#               scanner and launcher, and neither is rebuilt on reload. A changed/added/removed
+#               `fleet.leaders` entry is silently accepted — the reload reports "config reloaded"
+#               with nothing in the deferred list — but has NO effect until you restart. Treat it
+#               as deferred in practice, even though today's reload output does not say so.
 #   DEFERRED  → accepted into the new config, but the wiring built at startup keeps the old value
 #               until you restart: `lifecycle:`, `leadHeartbeat:`, `guard:`, `worktreeRoot:`,
 #               `spawnReadyTimeoutMs` / `spawnReadyPollMs`, `quarantineCooldownSeconds` (CB-578
@@ -368,6 +386,12 @@ fleet:
   # An auto-launched lead is NOT a member: it gets no worker reply charter, is never registered with
   # the session lifecycle (the idle reaper would kill your orchestrator), and stays on the
   # subscription — ANTHROPIC_BASE_URL/AUTH_TOKEN are stripped from its env whatever the profile says.
+  #
+  # GET THE `tab:` VALUE RIGHT. A pane that does not match any configured `tab:` (a typo, a renamed
+  # tab, a pane no entry names at all) is not recognised as a lead — it resolves as an ordinary
+  # WORKER instead, silently, and every orchestration call it makes (spawn/stop/send/drain) is
+  # refused. There is no error at startup for this: an unmatched pane is simply not a lead. If your
+  # primary suddenly can't spawn or send, check this section first.
   # leaders:
   #   opus-5.0:
   #     profile: opus                # omit to never create this lead, only recognise it
@@ -423,10 +447,15 @@ guard:
 #   idleTtlSeconds     → reap READY/DONE sessions idle longer than this (never BUSY/SPAWNING)
 #   contextCap         → force-release a session after this many delegated turns
 #   drainTimeoutSeconds → seconds to wait for BUSY sessions on shutdown before forced teardown
+#   clearAfterTurn     → whether a reusable worker discards its conversation context after every
+#                        completed delegated turn (default false). Works for claude-code workers
+#                        only — any other peer kind (e.g. opencode) logs "context reset is
+#                        unsupported for peer kind …" once and the reset is a no-op.
 # lifecycle:
 #   idleTtlSeconds: 300
 #   contextCap: 10
 #   drainTimeoutSeconds: 5
+#   clearAfterTurn: false
 
 # Durable reply delivery (CB-307 Stage 2). OMIT this block entirely to keep the default
 # in-memory, soft-state reply inbox (late worker replies are held only until a daemon bounce).
@@ -434,10 +463,14 @@ guard:
 # on a durable per-target queue (agent.<target>.inbox) and survive a restart — the broker
 # redelivers anything the primary had not yet drained. Production default is LavinMQ; a stock
 # RabbitMQ speaks the same AMQP 0-9-1, so it is a URI-only swap.
-#   uri → AMQP connection URI. No trailing slash ⇒ the default vhost "/"; an empty path ("/")
-#         is vhost "" and will NOT connect. Encode a named vhost as .../%2Fmyvhost.
+#   uri      → AMQP connection URI. No trailing slash ⇒ the default vhost "/"; an empty path ("/")
+#              is vhost "" and will NOT connect. Encode a named vhost as .../%2Fmyvhost.
+#   prefetch → CB-527: consumer basicQos, capping how many unacked messages the inbox holds
+#              in-heap per owned target (the rest sits on the broker's durable queue instead of
+#              growing the JVM heap). Default 32 when omitted.
 # broker:
 #   uri: amqp://guest:guest@127.0.0.1:5672
+#   prefetch: 32
 
 # Active push-to-primary (CB-307 Stage 3). When a worker reply lands with no open bridge_send,
 # the ReplyPushLoop injects a *drain nudge* (never the payload) into the primary's own herdr

bridged/src/main/java/dev/ltms/bridged/Bridged.java

@@ -83,6 +83,10 @@ public final class Bridged {
     static void main(String[] args) {
         Path configPath = Path.of(args.length > 0 ? args[0] : "bridged.yaml");
         BridgedConfig cfg = BridgedConfig.load(configPath);
+        // CB-594: report which secret env vars the config actually needs, by name, before anything
+        // else can fail on a silently-empty one. A daemon started without a login shell (launchd)
+        // boots fine either way — this is the only thing that says so out loud.
+        reportRequiredSecrets(cfg);
         // CB-559: `cfg` stays the startup snapshot — every validation and every piece of one-time
         // wiring below reads it, and must, because those decisions cannot be unmade. `config` is the
         // live reference the hot paths read per use. Which keys can actually move is ConfigRef's
@@ -348,8 +352,9 @@ public final class Bridged {
         // connection, so keep the reference to close it in the ordered shutdown hook.
         final ReplyInbox replyInbox;
         if (cfg.broker() != null && cfg.broker().isConfigured()) {
-            replyInbox = AmqpReplyInbox.open(cfg.broker().uri());
-            log.info("reply inbox: AMQP broker (durable) at {}", cfg.broker().uri());
+            replyInbox = AmqpReplyInbox.open(cfg.broker().uri(), cfg.broker().prefetchOrDefault());
+            log.info("reply inbox: AMQP broker (durable) at {} (prefetch={})",
+                    cfg.broker().uri(), cfg.broker().prefetchOrDefault());
         } else {
             replyInbox = new InMemoryReplyInbox();
             log.info("reply inbox: in-memory (soft-state)");
@@ -543,6 +548,63 @@ public final class Bridged {
         return target -> presence.isPresent(target) || leads.get().containsKey(target);
     }
 
+    /**
+     * CB-594: which env vars the loaded config actually needs, and why — every non-{@code
+     * subscription} profile's {@code tokenEnv} (a subscription profile never reads one, see
+     * {@link BridgedConfig.Profile#isSubscription()}), plus every profile's {@code gitTokenEnv}
+     * where set (opt-in). Derived from the config, not hard-coded, so a new profile is covered for
+     * free. A var required by more than one profile is one entry naming every profile that needs
+     * it. Deliberately excludes {@code auth.tokenEnv}: that one is already enforced loudly, by a
+     * startup throw, a few lines above this method's call site.
+     *
+     * <p>Package-private and pure (no I/O, no logging) so the derivation is unit-testable without
+     * capturing log output; {@link #reportRequiredSecrets(BridgedConfig)} is the logging caller.
+     */
+    static Map<String, List<String>> requiredSecretEnvVars(BridgedConfig cfg) {
+        Map<String, List<String>> requiredBy = new LinkedHashMap<>();
+        cfg.profiles().forEach((name, profile) -> {
+            if (!profile.isSubscription()) {
+                requiredBy.computeIfAbsent(profile.tokenEnv(), _ -> new ArrayList<>())
+                        .add("profile '" + name + "' tokenEnv");
+            }
+            if (profile.hasGitToken()) {
+                requiredBy.computeIfAbsent(profile.gitTokenEnv(), _ -> new ArrayList<>())
+                        .add("profile '" + name + "' gitTokenEnv");
+            }
+        });
+        return requiredBy;
+    }
+
+    /**
+     * CB-594: log, by name only, which required env vars (see {@link #requiredSecretEnvVars}) are
+     * set in the daemon's own process environment — the environment every profile's {@code
+     * tokenEnv}/{@code gitTokenEnv} is read from at spawn time (see
+     * {@code HerdrPeerLauncher.resolveEnv}). Never logs a value, a prefix, or a length.
+     *
+     * <p>A missing entry only warns — it must never refuse to start. A daemon that boots and says
+     * what is wrong is strictly more useful than one that will not boot at all.
+     */
+    private static void reportRequiredSecrets(BridgedConfig cfg) {
+        Map<String, List<String>> requiredBy = requiredSecretEnvVars(cfg);
+        if (requiredBy.isEmpty()) {
+            log.info("startup secrets: no profile references a token env var — nothing to check");
+            return;
+        }
+        Map<String, String> env = System.getenv();
+        requiredBy.forEach((varName, sources) -> {
+            String value = env.get(varName);
+            if (value != null && !value.isBlank()) {
+                log.info("startup secret {}: set ({})", varName, String.join(", ", sources));
+            } else {
+                log.warn("startup secret {}: MISSING ({}) — the daemon will start anyway, and this "
+                                + "failure stays invisible until a worker actually needs it. Fix "
+                                + "${SHARED_ENV}/tools/secrets.sh and restart bridged from a LOGIN "
+                                + "shell (see scripts/redeploy-bridged.sh).",
+                        varName, String.join(", ", sources));
+            }
+        });
+    }
+
     /**
      * Poll herdr's {@code ping} until it answers or {@link #HERDR_WAIT_SECONDS} elapses (CB-504).
      *

bridged/src/main/java/dev/ltms/bridged/config/BridgedConfig.java

@@ -5,6 +5,7 @@ import com.fasterxml.jackson.core.JsonParser;
 import com.fasterxml.jackson.core.JsonToken;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.dataformat.yaml.YAMLFactory;
+import dev.ltms.bridged.msg.AmqpReplyInbox;
 import dev.ltms.bridged.peer.MemberRole;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -532,16 +533,24 @@ public record BridgedConfig(
      * stays soft-state. Production default is LavinMQ; a stock RabbitMQ speaks the same AMQP 0-9-1
      * and is a URI-only swap.
      *
-     * @param uri AMQP connection URI, e.g. {@code amqp://guest:guest@127.0.0.1:5672/}. Blank/{@code null}
-     *            ⇒ the broker block is treated as absent (in-memory adapter).
+     * @param uri      AMQP connection URI, e.g. {@code amqp://guest:guest@127.0.0.1:5672/}. Blank/
+     *                 {@code null} ⇒ the broker block is treated as absent (in-memory adapter).
+     * @param prefetch CB-527: the consumer's {@code basicQos} prefetch count, bounding how many
+     *                 unacked messages the AMQP inbox holds in-heap per owned target. {@code null}/
+     *                 non-positive ⇒ {@link AmqpReplyInbox#DEFAULT_PREFETCH}.
      */
     @JsonIgnoreProperties(ignoreUnknown = true)
-    public record Broker(String uri) {
+    public record Broker(String uri, Integer prefetch) {
 
         /** True when a usable broker URI is configured (an empty block does not enable AMQP). */
         public boolean isConfigured() {
             return uri != null && !uri.isBlank();
         }
+
+        /** The prefetch to use, defaulting to {@link AmqpReplyInbox#DEFAULT_PREFETCH} when unset. */
+        public int prefetchOrDefault() {
+            return (prefetch != null && prefetch > 0) ? prefetch : AmqpReplyInbox.DEFAULT_PREFETCH;
+        }
     }
 
     /**
@@ -958,8 +967,12 @@ public record BridgedConfig(
     /**
      * Top-level keys this version understands. Used only to warn about the rest — see
      * {@link #warnUnknownTopLevelKeys}. Keep in step with the record components.
+     *
+     * <p>Package-private (not {@code private}) so a test can assert every key here is documented in
+     * {@code bridged.example.yaml} — the only committed description of the config schema, since
+     * {@code bridged.yaml} itself is gitignored.
      */
-    private static final Set<String> KNOWN_TOP_LEVEL_KEYS = Set.of(
+    static final Set<String> KNOWN_TOP_LEVEL_KEYS = Set.of(
             "bind", "herdrSocket", "profiles", "guard", "worktreeRoot",
             "lifecycle", "spawnReadyTimeoutMs", "spawnReadyPollMs", "broker", "primary", "fleet",
             "leadHeartbeat", "health", "placement", "auth", "configReload", "quarantineCooldownSeconds");

bridged/src/main/java/dev/ltms/bridged/mcp/BridgeMcp.java

@@ -15,6 +15,7 @@ import dev.ltms.bridged.msg.MessageService;
 import dev.ltms.bridged.msg.Rendezvous;
 import dev.ltms.bridged.peer.PeerUnreachableException;
 import dev.ltms.bridged.placement.BackendQuarantine;
+import dev.ltms.bridged.placement.PlacementException;
 import dev.ltms.bridged.session.SessionManager;
 import dev.ltms.bridged.session.MemberSession;
 import dev.ltms.bridged.session.WorktreeRequest;
@@ -692,6 +693,10 @@ public final class BridgeMcp {
             return text(json(memberView(member)));
         } catch (GuardException e) {
             return error("subscription boundary: " + e.getMessage());
+        } catch (PlacementException e) {
+            // CB-599: no candidate had capacity (maxLoad, quarantine, or all-exhausted) — distinct
+            // from "profile does not exist" below.
+            return error("no capacity: " + e.getMessage());
         } catch (IllegalArgumentException e) {
             return error(e.getMessage()); // unknown / no-default profile, or a refused resumeSessionId
         } catch (PeerUnreachableException e) {

bridged/src/main/java/dev/ltms/bridged/member/CompositePeerLauncher.java

@@ -372,8 +372,11 @@ public final class CompositePeerLauncher implements PeerLauncher {
     }
 
     private void enforceMaxLoad(String profile) {
-        // Absent config, or a config whose maxLoad normalized to null (non-positive ⇒ unlimited at
-        // load), means no cap — never cap what wasn't configured.
+        // Absent config, or a config whose maxLoad normalized to null (ABSENT ⇒ unlimited at load),
+        // means no cap — never cap what wasn't configured. Note "non-positive ⇒ unlimited" was true
+        // until CB-585: an explicit `maxLoad: 0` now survives as 0 and is a real cap of zero, so the
+        // check below refuses every spawn on that profile, and a negative value is refused at config
+        // load rather than normalized away.
         BridgedConfig.Profile cfg = profiles0().get(profile);
         Integer cap = (cfg == null) ? null : cfg.maxLoad();
         if (cap == null) {

bridged/src/main/java/dev/ltms/bridged/member/HerdrPeerLauncher.java

@@ -766,10 +766,61 @@ public abstract class HerdrPeerLauncher implements PeerLauncher {
         }
     }
 
-    /** A fresh mutable env map — the conventional starting point for {@link #buildLaunch}. */
+    /**
+     * CB-592: overlay value that shadows the admin {@code GITEA_ACCESS_TOKEN} a herdr pane
+     * otherwise inherits from herdr's own login-shell process environment (gitea issue #77).
+     * herdr spawns a pane from its <em>own</em> process environment and layers our map on top —
+     * {@link dev.ltms.bridged.herdr.WorkspaceControl#createTab} and {@code #splitPane} send only
+     * the keys we put in that map, so any key we never mention passes straight through from
+     * herdr's own shell, admin token included.
+     *
+     * <p>Deliberately a non-blank sentinel, not {@code ""}. Whether an empty-string overlay value
+     * overrides an inherited variable or is skipped as blank could not be settled by reading this
+     * codebase — herdr's server-side merge is an external process, not something in this repo.
+     * A non-blank replacement sidesteps that ambiguity entirely: {@link #baseEnv}'s own {@code
+     * PATH} seeding already depends on the overlay reliably replacing an inherited value (see its
+     * javadoc), and that is only demonstrated for a non-blank value, so this reuses the same,
+     * proven-reliable shape rather than the unverified one.
+     *
+     * <p><b>MEASURED ON A LIVE PANE, 2026-08-15: this sentinel alone does NOT hold.</b> The overlay
+     * itself works — {@code GITEA_TOKEN} is injected here, is exported by no shell file, and does
+     * reach the pane. The sentinel loses one step later. A herdr pane runs a <em>login</em> shell,
+     * {@code ~/.zprofile} sources {@code ${SHARED_ENV}/tools/secrets.sh}, and that file does a plain
+     * unconditional {@code export GITEA_ACCESS_TOKEN=...}. A login shell overwrites a value already
+     * in the environment, so the real admin token is put back over this sentinel before the member
+     * process ever starts. That defeat applies to <em>every</em> name {@code secrets.sh} exports,
+     * and no launcher-side overlay can win against it.
+     *
+     * <p>So this constant is not the control on its own — {@link #MEMBER_MARKER} is the other half.
+     * Keeping the sentinel is still worth it: it is correct for any peer kind whose pane does not
+     * start a login shell, and it makes the intent explicit at the one place every adapter passes.
+     */
+    private static final String BLOCKED_GITEA_ACCESS_TOKEN =
+            "blocked-by-bridged-cb592-see-gitea-issue-77";
+
+    /**
+     * CB-592: marks a pane as a bridged member so a shell startup file can decline to export
+     * operator-only credentials into it (gitea issue #77).
+     *
+     * <p>This name is deliberately one that {@code secrets.sh} never exports, which is exactly why
+     * it survives the login shell that wipes {@link #BLOCKED_GITEA_ACCESS_TOKEN}. The mechanism is
+     * measured, not assumed: {@code GITEA_TOKEN} is injected the same way, is absent from a login
+     * shell of its own, and was observed set inside a live member pane.
+     *
+     * <p>It is a no-op until the operator guards the export, which is a one-line change in a file
+     * this repo does not own and must not edit unasked:
+     *
+     * <pre>{@code
+     * [ -n "${BRIDGED_MEMBER:-}" ] || export GITEA_ACCESS_TOKEN=...
+     * }</pre>
+     *
+     * <p>Setting the marker now costs nothing and means that edit is the whole remaining fix.
+     */
+    static final String MEMBER_MARKER = "BRIDGED_MEMBER";
+
     /**
      * Seed a worker's environment (CB-511): the daemon's own {@code PATH}, then the profile's
-     * {@code env:} entries.
+     * {@code env:} entries, then the CB-592 admin-token shadow.
      *
      * <p>Why this exists: bridged passes herdr an explicit env map, and herdr merges it into
      * <em>its own</em> process environment. So before this, a worker inherited whatever PATH the
@@ -783,6 +834,12 @@ public abstract class HerdrPeerLauncher implements PeerLauncher {
      * overriding {@code ANTHROPIC_BASE_URL} and slipping past {@link
      * dev.ltms.bridged.guard.SubscriptionGuard}, which is checked against the profile's
      * {@code baseUrl} and nothing else.
+     *
+     * <p>The CB-592 shadow and marker are put in <em>last</em>, after the profile's own
+     * {@code env:}, so no profile — present or future — can restore the admin token, or hide that
+     * the pane is a member, by naming either in config. This is the one place both are applied:
+     * every {@code buildLaunch} in every adapter calls this first, so a new profile, and a peer
+     * kind not yet written, gets them for free.
      */
     protected Map<String, String> baseEnv(BridgedConfig.Profile cfg) {
         Map<String, String> workerEnv = new LinkedHashMap<>();
@@ -793,6 +850,8 @@ public abstract class HerdrPeerLauncher implements PeerLauncher {
         if (cfg != null && cfg.env() != null) {
             workerEnv.putAll(cfg.env());
         }
+        workerEnv.put("GITEA_ACCESS_TOKEN", BLOCKED_GITEA_ACCESS_TOKEN);
+        workerEnv.put(MEMBER_MARKER, "1");
         return workerEnv;
     }
 

bridged/src/main/java/dev/ltms/bridged/msg/AmqpReplyInbox.java

@@ -7,6 +7,7 @@ import com.rabbitmq.client.ConnectionFactory;
 import com.rabbitmq.client.DeliverCallback;
 import com.rabbitmq.client.Recoverable;
 import com.rabbitmq.client.RecoveryListener;
+import com.rabbitmq.client.Return;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -14,7 +15,13 @@ import java.io.IOException;
 import java.nio.charset.StandardCharsets;
 import java.util.LinkedHashMap;
 import java.util.List;
+import java.util.NavigableMap;
+import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ConcurrentSkipListMap;
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
 
 /**
  * AMQP-backed {@link ReplyInbox} (CB-307 Stage 2): genuine cross-restart durability behind the same
@@ -29,6 +36,27 @@ import java.util.concurrent.ConcurrentHashMap;
  * leaves them on the broker — it redelivers on reconnect. That is the durability the in-memory
  * adapter cannot give, with the port contract preserved.
  *
+ * <p><strong>Prefetch bounds the held backlog (CB-527).</strong> The consumer channel calls
+ * {@code basicQos} with a configurable prefetch count ({@link #DEFAULT_PREFETCH} unless the caller
+ * passes another value to {@link #open(String, int)}) before starting any consumer. Without a bound,
+ * the broker pushes its entire queue into {@link #held} the instant a target is {@link #own owned},
+ * so an undrained primary grows the JVM heap without limit and any queue-level control
+ * ({@code x-max-length}, per-message TTL) never fires because the queue never actually holds a
+ * backlog. Prefetch keeps the backlog where it is visible — on the broker — until the owner drains it.
+ *
+ * <p><strong>Publishes require a confirmed, routable delivery (CB-528).</strong> {@link #publish}
+ * runs on a channel separate from the consume/ack channel ({@link #channel}), so a slow or blocked
+ * publish confirm can never hold {@link #channelLock} and stall an ack — the ack path never waits on
+ * a publish confirm. That publish channel is in publisher-confirm mode and every publish sets the
+ * {@code mandatory} flag, so an unroutable publish (queue not declared, e.g. the owner never called
+ * {@link #own}) is returned by the broker instead of silently dropped. The broker sends the
+ * <em>return</em> for an unroutable message before the <em>confirm</em> that covers it — the ack/nack
+ * callback checks the returned-set at confirm time rather than assuming an ack means routed — so
+ * "confirmed" here means "durably queued", not merely "accepted by the broker". A returned or nacked
+ * (or un-confirmed within the timeout) publish surfaces as an {@link IllegalStateException} on the
+ * caller's thread; the caller — {@link MessageService#reply} — must not report success for a
+ * black-holed reply.
+ *
  * <p><strong>Ownership is explicit.</strong> {@link #own} declares the queue and starts the consumer;
  * {@link #release} cancels it. {@link #publish} sends to the queue but does <em>not</em> imply ownership
  * and does not attach a consumer. This split is required by CB-308 federation, where one gateway may
@@ -54,6 +82,12 @@ public final class AmqpReplyInbox implements ReplyInbox, AutoCloseable {
     private static final String QUEUE_PREFIX = "agent.";
     private static final String QUEUE_SUFFIX = ".inbox";
 
+    /** CB-527: the prefetch used when a caller does not pass an explicit value to {@link #open(String, int)}. */
+    public static final int DEFAULT_PREFETCH = 32;
+
+    /** How long {@link #publish} waits for its publisher confirm before failing the call (CB-528). */
+    private static final long CONFIRM_TIMEOUT_MS = 10_000L;
+
     private final Connection connection;
     private final Channel channel;
     /** All channel operations (publish/declare/ack/cancel) serialize on this — a Channel is not thread-safe. */
@@ -63,39 +97,87 @@ public final class AmqpReplyInbox implements ReplyInbox, AutoCloseable {
     /** Targets whose queue is declared and consumer is running, mapped to their broker consumer tag. */
     private final ConcurrentHashMap<String, String> consumerTags = new ConcurrentHashMap<>();
 
+    /**
+     * CB-528: a dedicated channel for {@link #publish}, kept separate from {@link #channel} (consume
+     * + ack) so a publish confirm round trip never blocks under {@link #channelLock} and stalls an ack.
+     */
+    private final Channel publishChannel;
+    private final Object publishChannelLock = new Object();
+    /** In-flight publishes awaiting their confirm, keyed by the publish channel's sequence number. */
+    private final ConcurrentSkipListMap<Long, Pending> pendingBySeq = new ConcurrentSkipListMap<>();
+    /**
+     * The same in-flight publishes, keyed by {@code msgId} — a broker {@code Return} carries no delivery
+     * tag. Assumes {@code msgId} is unique per in-flight publish: a second {@link #publish} for a
+     * {@code msgId} still awaiting its confirm would overwrite this entry and misdirect
+     * {@link #onReturn}'s lookup. Not reachable today — {@code MessageService.reply} generates a fresh
+     * {@code UUID} per call — so no guard is added for it.
+     */
+    private final ConcurrentHashMap<String, Pending> pendingByMsgId = new ConcurrentHashMap<>();
+
     /** A message pulled off the broker but not yet acked: its delivery-tag plus the port payload. */
     private record Held(long deliveryTag, InboxMessage message) {}
 
-    /** Connect to {@code uri} (e.g. {@code amqp://guest:guest@127.0.0.1:5672/}) and open the inbox. */
+    /** A publish awaiting its confirm; {@link #returned} records whether the broker already returned it. */
+    private static final class Pending {
+        final String msgId;
+        final CompletableFuture<Void> confirmed = new CompletableFuture<>();
+        volatile boolean returned;
+
+        Pending(String msgId) {
+            this.msgId = msgId;
+        }
+    }
+
+    /** Connect to {@code uri} (e.g. {@code amqp://guest:guest@127.0.0.1:5672/}) with {@link #DEFAULT_PREFETCH}. */
     public static AmqpReplyInbox open(String uri) {
+        return open(uri, DEFAULT_PREFETCH);
+    }
+
+    /** As {@link #open(String)}, with an explicit consumer prefetch (CB-527: caps the held backlog per target). */
+    public static AmqpReplyInbox open(String uri, int prefetch) {
         try {
             ConnectionFactory factory = new ConnectionFactory();
             factory.setUri(uri);
             // Self-heal transient blips; topology recovery re-declares queues and re-attaches consumers.
             factory.setAutomaticRecoveryEnabled(true);
             factory.setTopologyRecoveryEnabled(true);
-            return new AmqpReplyInbox(factory.newConnection("bridged-reply-inbox"));
+            return new AmqpReplyInbox(factory.newConnection("bridged-reply-inbox"), prefetch);
         } catch (Exception e) {
             throw new IllegalStateException("cannot connect to AMQP broker at " + uri, e);
         }
     }
 
-    /** Wrap an already-open connection (injection seam for the contract test). */
+    /** Wrap an already-open connection with {@link #DEFAULT_PREFETCH} (injection seam for the contract test). */
     AmqpReplyInbox(Connection connection) {
+        this(connection, DEFAULT_PREFETCH);
+    }
+
+    /** As above, with an explicit prefetch (injection seam for the contract test). */
+    AmqpReplyInbox(Connection connection, int prefetch) {
         this.connection = connection;
         try {
             this.channel = connection.createChannel();
+            // CB-527: bound the held backlog per owned target — must be set before any own()/basicConsume.
+            this.channel.basicQos(prefetch);
+            this.publishChannel = connection.createChannel();
+            this.publishChannel.confirmSelect();
+            this.publishChannel.addReturnListener(this::onReturn);
+            this.publishChannel.addConfirmListener(this::onAck, this::onNack);
         } catch (IOException e) {
             throw new IllegalStateException("cannot open AMQP channel", e);
         }
         // On automatic recovery the broker redelivers unacked messages with FRESH delivery-tags; the
         // tags we were holding are now stale. Drop the held snapshot so the re-attached consumer
-        // repopulates it with valid tags (dedup by msgId still prevents any double-queue).
+        // repopulates it with valid tags (dedup by msgId still prevents any double-queue). Any publish
+        // confirm still in flight when the connection dropped is equally stale — its sequence number
+        // meant nothing on the old channel and means nothing on the recovered one, so fail it now
+        // rather than let it silently ride out CONFIRM_TIMEOUT_MS.
         if (connection instanceof Recoverable recoverable) {
             recoverable.addRecoveryListener(new RecoveryListener() {
                 @Override
                 public void handleRecovery(Recoverable recoverable) {
                     held.clear();
+                    failPendingPublishesOnRecovery();
                     log.info("AMQP connection recovered; cleared held replies for fresh redelivery");
                 }
 
@@ -141,6 +223,12 @@ public final class AmqpReplyInbox implements ReplyInbox, AutoCloseable {
         }
     }
 
+    /**
+     * Publish {@code content} and block until the broker's publisher confirm for it lands (CB-528).
+     * Throws {@link IllegalStateException} if the message is returned as unroutable, nacked, or not
+     * confirmed within {@link #CONFIRM_TIMEOUT_MS} — the caller must treat that as a failed publish,
+     * not a lost-and-forgotten one.
+     */
     @Override
     public void publish(String target, String msgId, String content) {
         AMQP.BasicProperties props = new AMQP.BasicProperties.Builder()
@@ -148,12 +236,35 @@ public final class AmqpReplyInbox implements ReplyInbox, AutoCloseable {
                 .deliveryMode(2)                   // persistent — survives a broker restart
                 .contentType("text/plain")
                 .build();
-        try {
-            synchronized (channelLock) {
-                channel.basicPublish("", queueName(target), props, content.getBytes(StandardCharsets.UTF_8));
+        Pending pending = new Pending(msgId);
+        long seq;
+        synchronized (publishChannelLock) {
+            seq = publishChannel.getNextPublishSeqNo();
+            pendingBySeq.put(seq, pending);
+            pendingByMsgId.put(msgId, pending);
+            try {
+                publishChannel.basicPublish("", queueName(target), true, props,
+                        content.getBytes(StandardCharsets.UTF_8));
+            } catch (IOException e) {
+                pendingBySeq.remove(seq, pending);
+                pendingByMsgId.remove(msgId, pending);
+                throw new IllegalStateException("cannot publish reply to " + queueName(target), e);
             }
-        } catch (IOException e) {
-            throw new IllegalStateException("cannot publish reply to " + queueName(target), e);
+        }
+        try {
+            pending.confirmed.get(CONFIRM_TIMEOUT_MS, TimeUnit.MILLISECONDS);
+        } catch (ExecutionException e) {
+            Throwable cause = e.getCause();
+            throw cause instanceof RuntimeException re ? re : new IllegalStateException(cause);
+        } catch (TimeoutException e) {
+            throw new IllegalStateException("publish confirm for reply " + msgId + " to " + queueName(target)
+                    + " timed out after " + CONFIRM_TIMEOUT_MS + "ms — broker may be unreachable or overloaded", e);
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            throw new IllegalStateException("interrupted awaiting publish confirm for " + msgId, e);
+        } finally {
+            pendingBySeq.remove(seq, pending);
+            pendingByMsgId.remove(msgId, pending);
         }
     }
 
@@ -222,17 +333,115 @@ public final class AmqpReplyInbox implements ReplyInbox, AutoCloseable {
         };
     }
 
+    /** Broker return for an unroutable {@code mandatory} publish — arrives BEFORE its confirm (CB-528). */
+    private void onReturn(Return r) {
+        String msgId = r.getProperties() == null ? null : r.getProperties().getMessageId();
+        Pending pending = msgId == null ? null : pendingByMsgId.get(msgId);
+        if (pending != null) {
+            pending.returned = true;
+        } else {
+            log.warn("AMQP return for reply {} (routingKey={}, {} {}) with no matching in-flight publish"
+                    + " — already resolved by a prior confirm", msgId, r.getRoutingKey(), r.getReplyCode(),
+                    r.getReplyText());
+        }
+    }
+
+    private void onAck(long seq, boolean multiple) {
+        resolveConfirm(seq, multiple, true);
+    }
+
+    private void onNack(long seq, boolean multiple) {
+        resolveConfirm(seq, multiple, false);
+    }
+
+    /**
+     * Resolve every pending publish covered by this confirm (a single seq, or — {@code multiple} —
+     * every seq up to and including it). Checks {@link Pending#returned} at confirm time: since the
+     * broker's return for an unroutable message always precedes its confirm, an ack that arrives after
+     * a return means "confirmed but never routed", not "durably queued".
+     */
+    private void resolveConfirm(long seq, boolean multiple, boolean ack) {
+        NavigableMap<Long, Pending> covered = multiple
+                ? pendingBySeq.headMap(seq, true)
+                : pendingBySeq.subMap(seq, true, seq, true);
+        for (var it = covered.entrySet().iterator(); it.hasNext(); ) {
+            Pending pending = it.next().getValue();
+            it.remove();
+            pendingByMsgId.remove(pending.msgId, pending);
+            if (ack && !pending.returned) {
+                pending.confirmed.complete(null);
+            } else if (ack) {
+                pending.confirmed.completeExceptionally(new IllegalStateException(
+                        "reply " + pending.msgId + " was returned as unroutable (queue not declared/owned)"));
+            } else {
+                pending.confirmed.completeExceptionally(new IllegalStateException(
+                        "broker nacked publish of reply " + pending.msgId));
+            }
+        }
+    }
+
+    /**
+     * Fail every publish still awaiting its confirm — their sequence numbers are stale after recovery.
+     * Guarded by {@link #publishChannelLock}, the same lock {@link #publish} holds while it takes its
+     * sequence number and registers its {@link Pending}: without it, a {@link #publish} that starts
+     * after the connection has already recovered (so it publishes — and will be confirmed — on the
+     * <em>new</em> channel) can register between this sweep's iteration and its clear, and this sweep
+     * then fails a publish that actually succeeded. {@link #publish} only holds the lock for the
+     * seq/map-put/{@code basicPublish} — it awaits the confirm outside it — so this sweep can only ever
+     * wait for an in-flight {@code basicPublish} call to return, never for a broker round trip. No
+     * deadlock.
+     *
+     * <p>Package-private (rather than {@code private}) only so the unit test can drive it directly
+     * against a concurrent {@link #publish} without a live broker reconnect.
+     */
+    void failPendingPublishesOnRecovery() {
+        synchronized (publishChannelLock) {
+            for (var it = pendingBySeq.entrySet().iterator(); it.hasNext(); ) {
+                Pending pending = it.next().getValue();
+                it.remove();
+                pendingByMsgId.remove(pending.msgId, pending);
+                pending.confirmed.completeExceptionally(new IllegalStateException(
+                        "AMQP connection recovered mid-publish; confirm status of reply " + pending.msgId
+                                + " is unknown"));
+            }
+        }
+    }
+
+    /**
+     * Fail every publish still awaiting its confirm with a clear, immediate error instead of leaving it
+     * to time out after {@link #CONFIRM_TIMEOUT_MS} once the channels are closed underneath it. Guarded
+     * by {@link #publishChannelLock} for the same reason as {@link #failPendingPublishesOnRecovery}.
+     */
+    private void failPendingPublishesOnClose() {
+        synchronized (publishChannelLock) {
+            for (var it = pendingBySeq.entrySet().iterator(); it.hasNext(); ) {
+                Pending pending = it.next().getValue();
+                it.remove();
+                pendingByMsgId.remove(pending.msgId, pending);
+                pending.confirmed.completeExceptionally(new IllegalStateException(
+                        "AMQP reply inbox closed while publish of reply " + pending.msgId
+                                + " was still awaiting its confirm"));
+            }
+        }
+    }
+
     private static String queueName(String target) {
         return QUEUE_PREFIX + target + QUEUE_SUFFIX;
     }
 
     @Override
     public void close() {
+        failPendingPublishesOnClose();
         try {
             channel.close();
         } catch (Exception e) {
             log.debug("AMQP channel close: {}", e.toString());
         }
+        try {
+            publishChannel.close();
+        } catch (Exception e) {
+            log.debug("AMQP publish channel close: {}", e.toString());
+        }
         try {
             connection.close();
         } catch (Exception e) {

bridged/src/main/java/dev/ltms/bridged/msg/ReplyPushLoop.java

@@ -8,6 +8,8 @@ import dev.ltms.bridged.metrics.Metrics;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+import java.util.ArrayList;
+import java.util.HashSet;
 import java.util.List;
 import java.util.Set;
 import java.util.concurrent.ConcurrentHashMap;
@@ -16,35 +18,43 @@ import java.util.concurrent.TimeUnit;
 import java.util.stream.Collectors;
 
 /**
- * Mechanism (b) of CB-307: a dedicated, status-gated push loop that nudges the primary's own
- * herdr pane when a worker reply lands with no live {@code bridge_send} to resolve it.
+ * A status-gated push loop that nudges a lead's own herdr pane when it has uncollected work
+ * waiting: a worker reply queued with no live {@code bridge_send} to resolve it (CB-307), or an
+ * async delegation ticket ({@code bridge_send(wait:false)}) that reached a terminal phase
+ * (CB-588).
  *
- * <p>The loop is triggered by {@link #onReplyQueued(String)} (called from
- * {@link MessageService#reply} after the durable inbox publish). It checks four conditions
- * at each tick via {@link #decide(String, int)}, then either injects a drain nudge,
- * waits for the primary to become injectable, or stops reminding.
+ * <p><strong>CB-590: one schedule per lead.</strong> Both kinds of work are triggered through
+ * their own entry point — {@link #onReplyQueued(String)} and
+ * {@link #onTicketTerminal(String, String, boolean)} — but both resolve the lead that should be
+ * nudged and coalesce onto a single per-lead reminder schedule, tracked in {@link #activeLeads}.
+ * Earlier this was two independent schedules (one keyed by worker target for replies, one keyed
+ * by lead for tickets) that could both decide to inject into the same pane in the same window —
+ * a race, not routine behaviour, but the expensive kind: it interrupts the lead's live turn
+ * twice. Collapsing to one schedule per lead makes that structurally impossible: at most one
+ * scheduled tick chain is ever live for a given lead (guarded by {@link #activeLeads}'
+ * compare-and-set), so at most one {@code agents.send} to that lead's pane is ever in flight.
  *
- * <p>Bounded: at most {@link #maxReminders} nudges per target, with a configurable backoff
- * between them. The reply is never lost — the durable inbox is the backstop.
- *
- * <p><strong>CB-588 ticket nudges.</strong> {@link #onTicketTerminal(String, String, boolean)} is a
- * second, independent entry point for an async delegation ticket ({@code bridge_send(wait:false)})
- * reaching a terminal phase. That path takes the rendezvous fast path in {@link MessageService#reply}
- * and never reaches {@link #onReplyQueued}, so without this the lead's own charter — prefer
- * {@code wait:false} for anything non-trivial — was exactly the mode this loop failed to cover. It
- * reuses the same status gating, bounded/backoff reminders, and metrics, keyed by the nudge-receiving
- * lead terminal rather than the worker target so several tickets finishing together coalesce into one
- * nudge. The two entry points do not interact: {@link #onReplyQueued} / {@link #decide} / their nudge
- * text and bound are unchanged.
+ * <p>Each tick examines <em>everything</em> pending for that lead — reply targets whose inbox
+ * still holds an unacked message ({@link #pendingReplies}) and tickets not yet collected
+ * ({@link #pendingTickets}) — and sends at most one combined nudge per tick
+ * ({@link #injectNudge(String, int, int)}). Work that arrives while the lead is busy is never
+ * lost: it is re-read fresh on every tick until the lead is injectable or its own reminder cap
+ * ({@link #maxReminders}) is reached — reply and ticket work each spend from their own budget, so
+ * one source exhausting its cap does not stop nudges about the other (post-CB-590 regression fix;
+ * see {@link #decide}) — whichever the durable inbox / pending-ticket set doesn't already answer
+ * via {@code STOP}.
  */
 public final class ReplyPushLoop {
 
     private static final Logger log = LoggerFactory.getLogger(ReplyPushLoop.class);
     static final String NUDGE_FORMAT = "Worker %s returned a reply — run bridge_poll(target=%s) to collect it";
-    /** CB-588: singular form, one uncollected ticket. */
+    /** Coalesced form, several uncollected replies for the same lead. */
+    static final String REPLIES_NUDGE_FORMAT =
+            "%d workers returned replies — run bridge_poll(target=...) for each to collect them: %s";
+    /** Singular form, one uncollected ticket. */
     static final String TICKET_NUDGE_FORMAT =
             "Ticket %s finished%s — run bridge_poll(ticket=%s) to collect it";
-    /** CB-588: coalesced form, several uncollected tickets for the same lead. */
+    /** Coalesced form, several uncollected tickets for the same lead. */
     static final String TICKETS_NUDGE_FORMAT =
             "%d tickets finished%s — run bridge_poll(ticket=...) for each to collect them: %s";
 
@@ -56,11 +66,11 @@ public final class ReplyPushLoop {
     private final long backoffMs;
     private final Metrics metrics; // CB-512: nullable — no registry in unit tests
 
-    /** Track targets that have an active schedule. */
-    private final ConcurrentHashMap<String, Boolean> activeTargets = new ConcurrentHashMap<>();
-    /** CB-588: tickets that have gone terminal but not yet been polled, keyed by ticket. */
+    /** Worker targets with a reply queued, and the lead to nudge about it, keyed by target. */
+    private final ConcurrentHashMap<String, String> pendingReplies = new ConcurrentHashMap<>();
+    /** Tickets that have gone terminal but not yet been polled, keyed by ticket. */
     private final ConcurrentHashMap<String, PendingTicket> pendingTickets = new ConcurrentHashMap<>();
-    /** CB-588: leads with an active ticket-reminder schedule. */
+    /** CB-590: leads with an active combined reminder schedule (replies and/or tickets). */
     private final ConcurrentHashMap<String, Boolean> activeLeads = new ConcurrentHashMap<>();
 
     public ReplyPushLoop(PrimaryRegistry primaryRegistry, AgentControl agents, ReplyInbox inbox,
@@ -89,178 +99,79 @@ public final class ReplyPushLoop {
         }
     }
 
-    // --- decision logic (package-private for unit-testing) -------------------------------------
+    // --- pending-work lookups (package-private for unit-testing) -------------------------------
 
-    /** The action the loop should take for a target at the given reminder count. */
+    /** The action the loop should take for a lead at the given reminder count. */
     enum Action { INJECT, WAIT_BUSY, STOP }
 
     /**
-     * Pure decision function: examine the current state and return what the loop should do.
-     *
-     * @param target        the worker session (target terminal id)
-     * @param reminderCount how many nudges have been sent so far for this target
-     * @return the action the caller should take
+     * Reply targets still pending for {@code lead} — registered via {@link #onReplyQueued} and
+     * whose inbox still holds an unacked message. A target whose inbox has since drained (acked,
+     * or collected via a live {@code bridge_send} rendezvous instead) is dropped from
+     * {@link #pendingReplies} here rather than lingering forever; there is no explicit "reply
+     * collected" callback the way {@link #ticketCollected} exists for tickets, so the inbox itself
+     * is the only signal.
      */
-    Action decide(String target, int reminderCount) {
-        // CB-532: the destination is per-delegation — the lead that sent this worker its work, not
-        // "the primary". With two leads orchestrating one fleet the singular question has no right
-        // answer, and answering it anyway interrupted whichever lead happened to call bridge_send
-        // first with results it never asked for.
-        var nudgeTarget = primaryRegistry.nudgeTargetFor(target);
-        if (nudgeTarget.isEmpty()) {
-            log.debug("push: no lead is known to be waiting on {}, stopping reminder", target);
-            return Action.STOP;
-        }
-        if (inbox.peek(target).isEmpty()) {
-            log.debug("push: inbox empty for {}, stopping reminder", target);
-            return Action.STOP;
-        }
-        if (reminderCount >= maxReminders) {
-            log.debug("push: reminder cap ({}) reached for {}, stopping", maxReminders, target);
-            countNudge("exhausted");
-            return Action.STOP;
-        }
-        String leadTerminal = nudgeTarget.get();
-        AgentStatus status;
-        try {
-            status = agents.status(leadTerminal);
-        } catch (RuntimeException e) {
-            log.debug("push: status check failed for lead {}, will retry", leadTerminal, e);
-            return Action.WAIT_BUSY;
-        }
-        if (status.injectable()) {
-            return Action.INJECT;
-        }
-        log.debug("push: lead {} is {} (not injectable), waiting", leadTerminal, status);
-        return Action.WAIT_BUSY;
-    }
-
-    // --- public entrypoint ---------------------------------------------------------------------
-
-    /**
-     * Called when a reply is queued for {@code target}. Idempotent per target: a second call while
-     * a schedule is active is a no-op. The schedule nudges the primary, then schedules a follow-up
-     * check (reminder on backoff, or re-check on WAIT_BUSY), until the inbox is empty or the cap
-     * is reached.
-     */
-    public void onReplyQueued(String target) {
-        if (activeTargets.putIfAbsent(target, Boolean.TRUE) != null) {
-            log.debug("push: already active for {}, ignoring duplicate trigger", target);
-            return; // already scheduled
-        }
-        log.debug("push: starting reminder loop for {}", target);
-        scheduleNext(target, 0);
-    }
-
-    /** Execute one loop tick — called on the scheduler thread. */
-    private void tick(String target, int reminderCount) {
-        var action = decide(target, reminderCount);
-        switch (action) {
-            case INJECT -> {
-                injectNudge(target, reminderCount);
-                scheduleNext(target, reminderCount + 1);
-            }
-            // Re-check after the configured backoff; the primary may become injectable soon.
-            case WAIT_BUSY -> scheduleNext(target, reminderCount);
-            case STOP -> {
-                activeTargets.remove(target);
-                log.debug("push: reminder loop ended for {}", target);
+    private Set<String> pendingReplyTargetsFor(String lead) {
+        Set<String> result = new HashSet<>();
+        for (var entry : pendingReplies.entrySet()) {
+            String target = entry.getKey();
+            String owningLead = entry.getValue();
+            if (!lead.equals(owningLead)) continue;
+            if (inbox.peek(target).isEmpty()) {
+                pendingReplies.remove(target, owningLead);
+                continue;
             }
+            result.add(target);
         }
+        return result;
     }
 
-    /** Send the nudge and log the event. */
-    private void injectNudge(String target, int reminderCount) {
-        // Re-read rather than threading it down from decide(): the delegating lead can change
-        // between the decision and the injection, and the nudge should follow the current one.
-        var lead = primaryRegistry.nudgeTargetFor(target);
-        if (lead.isEmpty()) {
-            log.debug("push: lead for {} disappeared before the nudge could be sent", target);
-            return;
-        }
-        String leadTerminal = lead.get();
-        String nudge = NUDGE_FORMAT.formatted(target, target);
-        try {
-            agents.send(leadTerminal, nudge);
-            log.debug("push: nudge {}/{} sent to lead {} for target {}",
-                    reminderCount + 1, maxReminders, leadTerminal, target);
-            countNudge("delivered");
-        } catch (RuntimeException e) {
-            log.warn("push: failed to nudge lead {} for target {} (reminder {}/{}): {}",
-                    leadTerminal, target, reminderCount + 1, maxReminders, e.toString());
-        }
-    }
-
-    /** Schedule the next tick on the scheduler thread pool. */
-    private void scheduleNext(String target, int nextReminderCount) {
-        scheduler.schedule(() -> tick(target, nextReminderCount), backoffMs, TimeUnit.MILLISECONDS);
-    }
-
-    // --- CB-588: async ticket terminal nudges ---------------------------------------------------
-
     /** A ticket awaiting collection: which lead to nudge, and whether it ended in failure. */
     private record PendingTicket(String ticket, String lead, boolean failed) {
     }
 
-    /**
-     * Called when an async delegation ticket ({@code bridge_send(wait:false)}, CB-107) reaches a
-     * terminal phase — DONE or a failure. Unlike {@link #onReplyQueued}, which nudges about the
-     * durable-inbox no-waiter path, this covers the path {@code MessageService.reply} takes when a
-     * fire-and-poll send's own rendezvous waiter resolves the reply directly: that path returns
-     * before {@link #onReplyQueued} is ever called, so without this entry point a ticket finishing
-     * that way never nudged anyone (CB-588 / gitea #72).
-     *
-     * <p>Idempotent per lead: several tickets going terminal for the same lead while its schedule is
-     * already active coalesce onto that schedule's next tick rather than firing a nudge each.
-     *
-     * @param ticket the ticket to nudge about
-     * @param target the worker session the ticket was sent to — resolves which lead delegated it
-     * @param failed whether the ticket ended in a failure phase rather than {@code DONE}
-     */
-    public void onTicketTerminal(String ticket, String target, boolean failed) {
-        var lead = primaryRegistry.nudgeTargetFor(target);
-        if (lead.isEmpty()) {
-            log.debug("push: no lead is known to be waiting on ticket {} (target {}), skipping nudge",
-                    ticket, target);
-            return;
-        }
-        pendingTickets.put(ticket, new PendingTicket(ticket, lead.get(), failed));
-        if (activeLeads.putIfAbsent(lead.get(), Boolean.TRUE) != null) {
-            log.debug("push: ticket reminder loop already active for lead {}, {} coalesced in",
-                    lead.get(), ticket);
-            return;
-        }
-        log.debug("push: starting ticket reminder loop for lead {}", lead.get());
-        scheduleTicketTick(lead.get(), 0);
-    }
-
-    /**
-     * Called when a ticket's terminal state has been collected via {@code bridge_poll}. Removes it
-     * from the pending set so a scheduled tick — and any nudge it sends — never names a ticket the
-     * lead already has (CB-588 acceptance #5). A ticket that was never pending (unknown ticket, or
-     * one nudged with no push loop configured) is a no-op.
-     */
-    public void ticketCollected(String ticket) {
-        pendingTickets.remove(ticket);
-    }
-
     /** Tickets still pending for {@code lead}, snapshotted fresh for one tick. */
-    private List<PendingTicket> pendingFor(String lead) {
+    private List<PendingTicket> pendingTicketsFor(String lead) {
         return pendingTickets.values().stream().filter(t -> lead.equals(t.lead())).toList();
     }
 
+    /** Ticket ids still pending for {@code lead} — a plain snapshot for race comparison. */
+    private Set<String> pendingTicketIdsFor(String lead) {
+        return pendingTicketsFor(lead).stream().map(PendingTicket::ticket)
+                .collect(Collectors.toUnmodifiableSet());
+    }
+
     /**
-     * Pure decision function for ticket nudges, mirroring {@link #decide(String, int)} but keyed by
-     * the nudge-receiving lead terminal rather than the worker session — several tickets from
-     * different workers delegated by the same lead coalesce onto it.
+     * Pure decision function: examine everything pending for {@code lead} — reply targets and
+     * tickets alike — and return what the loop should do.
+     *
+     * <p><strong>CB-590-fix: one schedule, two budgets.</strong> The single per-lead schedule
+     * (CB-590) still ticks once for both sources, but each source is capped independently —
+     * {@code replyReminderCount} against a reply target still pending, {@code ticketReminderCount}
+     * against a ticket still pending. A busy reply stream that exhausts its own cap must not stop
+     * the loop from nudging about a ticket that still has budget left, and vice versa: either
+     * source being eligible (has pending work AND is under its own cap) is enough for
+     * {@link Action#INJECT}. Only when neither source has eligible work does the loop
+     * {@link Action#STOP}.
+     *
+     * @param lead                the lead terminal to nudge
+     * @param replyReminderCount  how many nudges have covered pending reply work for this lead
+     * @param ticketReminderCount how many nudges have covered pending ticket work for this lead
+     * @return the action the caller should take
      */
-    Action decideTickets(String lead, int reminderCount) {
-        if (pendingFor(lead).isEmpty()) {
-            log.debug("push: nothing pending for lead {}, stopping ticket reminder", lead);
+    Action decide(String lead, int replyReminderCount, int ticketReminderCount) {
+        boolean hasReplyWork = !pendingReplyTargetsFor(lead).isEmpty();
+        boolean hasTicketWork = !pendingTicketIdsFor(lead).isEmpty();
+        if (!hasReplyWork && !hasTicketWork) {
+            log.debug("push: nothing pending for lead {}, stopping reminder", lead);
             return Action.STOP;
         }
-        if (reminderCount >= maxReminders) {
-            log.debug("push: ticket reminder cap ({}) reached for lead {}, stopping", maxReminders, lead);
+        boolean replyEligible = hasReplyWork && replyReminderCount < maxReminders;
+        boolean ticketEligible = hasTicketWork && ticketReminderCount < maxReminders;
+        if (!replyEligible && !ticketEligible) {
+            log.debug("push: reminder cap ({}) reached for lead {} on every source with pending work, stopping",
+                    maxReminders, lead);
             countNudge("exhausted");
             return Action.STOP;
         }
@@ -278,95 +189,194 @@ public final class ReplyPushLoop {
         return Action.WAIT_BUSY;
     }
 
-    /** Execute one ticket-loop tick — called on the scheduler thread. */
-    private void ticketTick(String lead, int reminderCount) {
-        Set<String> pendingBefore = pendingIdsFor(lead);
-        var action = decideTickets(lead, reminderCount);
-        switch (action) {
-            case INJECT -> {
-                injectTicketNudge(lead, reminderCount);
-                scheduleTicketTick(lead, reminderCount + 1);
-            }
-            case WAIT_BUSY -> scheduleTicketTick(lead, reminderCount);
-            case STOP -> stopOrRestartTicketLoop(lead, pendingBefore);
-        }
-    }
+    // --- public entrypoints ----------------------------------------------------------------------
 
-    /** Ticket IDs pending for {@code lead} right now, as a plain snapshot for race comparison. */
-    private Set<String> pendingIdsFor(String lead) {
-        return pendingFor(lead).stream().map(PendingTicket::ticket).collect(Collectors.toUnmodifiableSet());
+    /**
+     * Called when a reply is queued for {@code target}. Resolves the lead delegating to
+     * {@code target} (CB-532) and coalesces onto that lead's single reminder schedule — starting
+     * one if none is active, joining an already-active one otherwise. A no-op if no lead is known
+     * to be waiting on {@code target}: there is nobody to nudge yet, and the durable inbox is the
+     * backstop until a lead is recorded.
+     */
+    public void onReplyQueued(String target) {
+        var lead = primaryRegistry.nudgeTargetFor(target);
+        if (lead.isEmpty()) {
+            log.debug("push: no lead is known to be waiting on {}, skipping reminder", target);
+            return;
+        }
+        pendingReplies.put(target, lead.get());
+        startOrCoalesce(lead.get());
     }
 
     /**
-     * Release {@code lead}'s active-schedule slot, then restart it only if a ticket landed that
-     * {@code pendingBefore} — the snapshot taken just before this tick's decision — did not already
-     * account for. {@code onTicketTerminal} reads {@code activeLeads} to decide whether to coalesce
-     * onto an existing schedule or start one, so a ticket that lands between {@code decideTickets}
-     * returning {@link Action#STOP} and this removal running sees the (soon-to-be-stale) slot as
-     * occupied, coalesces onto a schedule that is about to die, and gets no nudge scheduled at all —
-     * a lost nudge, the exact failure CB-588 exists to remove (found in review, gitea PR #73).
+     * Called when an async delegation ticket ({@code bridge_send(wait:false)}, CB-107) reaches a
+     * terminal phase — DONE or a failure. Unlike {@link #onReplyQueued}, which nudges about the
+     * durable-inbox no-waiter path, this covers the path {@code MessageService.reply} takes when a
+     * fire-and-poll send's own rendezvous waiter resolves the reply directly: that path returns
+     * before {@link #onReplyQueued} is ever called, so without this entry point a ticket finishing
+     * that way never nudged anyone (CB-588 / gitea #72).
      *
-     * <p>Restarting on ANY non-empty {@code pendingFor(lead)} would be wrong: when STOP is reached
-     * because the reminder cap was hit rather than the backlog draining, the same never-collected
-     * ticket is expected to still be sitting there — that is the cap doing its job — and restarting
-     * would nudge about it forever, defeating the bound (the original CB-307 bounded-reminder
-     * guarantee, carried into CB-588 by acceptance criterion #7 — this exact regression showed up as
-     * two existing tests failing once a naive "any pending ticket restarts" version of this fix went
-     * in: {@code successfulTicketNudgeIncrementsDelivered} and {@code ticketNudgesSendUpToCapThenStop}).
-     * Diffing the current pending set against {@code pendingBefore} tells the two cases apart: a
-     * ticket present before this tick's decision is stale backlog, not a race; only a ticket absent
-     * from {@code pendingBefore} can only have arrived during the decision-to-release window, which is
-     * exactly the race this method closes.
+     * <p>Resolves the delegating lead the same way {@link #onReplyQueued} does and coalesces onto
+     * the same per-lead schedule (CB-590) — several tickets, or a ticket and a reply, finishing
+     * for the same lead while its schedule is already active all ride the existing schedule's next
+     * tick rather than firing a nudge each.
+     *
+     * @param ticket the ticket to nudge about
+     * @param target the worker session the ticket was sent to — resolves which lead delegated it
+     * @param failed whether the ticket ended in a failure phase rather than {@code DONE}
+     */
+    public void onTicketTerminal(String ticket, String target, boolean failed) {
+        var lead = primaryRegistry.nudgeTargetFor(target);
+        if (lead.isEmpty()) {
+            log.debug("push: no lead is known to be waiting on ticket {} (target {}), skipping nudge",
+                    ticket, target);
+            return;
+        }
+        pendingTickets.put(ticket, new PendingTicket(ticket, lead.get(), failed));
+        startOrCoalesce(lead.get());
+    }
+
+    /**
+     * Called when a ticket's terminal state has been collected via {@code bridge_poll}. Removes it
+     * from the pending set so a scheduled tick — and any nudge it sends — never names a ticket the
+     * lead already has. A ticket that was never pending (unknown ticket, or one nudged with no push
+     * loop configured) is a no-op.
+     */
+    public void ticketCollected(String ticket) {
+        pendingTickets.remove(ticket);
+    }
+
+    // --- the schedule ----------------------------------------------------------------------------
+
+    /** Start a reminder schedule for {@code lead}, or join the one already running. */
+    private void startOrCoalesce(String lead) {
+        if (activeLeads.putIfAbsent(lead, Boolean.TRUE) != null) {
+            log.debug("push: reminder loop already active for lead {}, work coalesced in", lead);
+            return;
+        }
+        log.debug("push: starting reminder loop for lead {}", lead);
+        scheduleNext(lead, 0, 0);
+    }
+
+    /** Execute one loop tick — called on the scheduler thread. */
+    private void tick(String lead, int replyReminderCount, int ticketReminderCount) {
+        Set<String> repliesBefore = pendingReplyTargetsFor(lead);
+        Set<String> ticketsBefore = pendingTicketIdsFor(lead);
+        var action = decide(lead, replyReminderCount, ticketReminderCount);
+        switch (action) {
+            case INJECT -> {
+                injectNudge(lead, replyReminderCount, ticketReminderCount);
+                // Only the source(s) actually eligible this tick spend a unit of their own budget —
+                // an exhausted source riding along in the combined message (still pending, still
+                // named) does not get charged again; its count stays put until it drains.
+                boolean replyEligible = !repliesBefore.isEmpty() && replyReminderCount < maxReminders;
+                boolean ticketEligible = !ticketsBefore.isEmpty() && ticketReminderCount < maxReminders;
+                scheduleNext(lead,
+                        replyEligible ? replyReminderCount + 1 : replyReminderCount,
+                        ticketEligible ? ticketReminderCount + 1 : ticketReminderCount);
+            }
+            // Re-check after the configured backoff; the lead may become injectable soon.
+            case WAIT_BUSY -> scheduleNext(lead, replyReminderCount, ticketReminderCount);
+            case STOP -> stopOrRestart(lead, repliesBefore, ticketsBefore);
+        }
+    }
+
+    /**
+     * Release {@code lead}'s active-schedule slot, then restart it only if work landed that
+     * {@code repliesBefore} / {@code ticketsBefore} — the snapshots taken just before this tick's
+     * decision — did not already account for. {@link #onReplyQueued} / {@link #onTicketTerminal}
+     * read {@link #activeLeads} to decide whether to coalesce onto an existing schedule or start
+     * one, so work that lands between {@link #decide} returning {@link Action#STOP} and this
+     * removal running sees the (soon-to-be-stale) slot as occupied, coalesces onto a schedule that
+     * is about to die, and gets no nudge scheduled at all — a lost nudge, exactly what CB-588 (and
+     * now CB-590) exist to remove (originally found in review, gitea PR #73, for the ticket-only
+     * loop; carried forward here for the unified one).
+     *
+     * <p>Restarting on ANY non-empty pending set would be wrong: when STOP is reached because the
+     * reminder cap was hit rather than the backlog draining, the same never-collected work is
+     * expected to still be sitting there — that is the cap doing its job — and restarting would
+     * nudge about it forever, defeating the bound. Diffing the current pending sets against the
+     * "before" snapshots tells the two cases apart: an item present before this tick's decision is
+     * stale backlog, not a race; only an item absent from the "before" snapshot can only have
+     * arrived during the decision-to-release window, which is exactly the race this method closes.
      *
      * <p>Package-private so a test can drive the interleaving directly rather than trying to force a
-     * genuine thread race: pass the exact {@code pendingBefore} snapshot a race requires (or does
-     * not) and call this to prove the recheck responds correctly either way.
+     * genuine thread race.
      *
-     * <p>Terminates rather than spinning: this method restarts the schedule at most once per call, and
-     * a fresh {@link #onTicketTerminal} racing the recheck below still terminates in one of two ways —
-     * either it observes the slot already vacated (by the {@code activeLeads.remove} above, which
-     * happens-before this recheck in program order) and claims it itself, or it lands first and this
-     * recheck then observes its ticket in {@code pendingTickets} and reclaims the slot instead. Exactly
-     * one side always wins; neither can miss the other, so this never loops on its own account.
+     * <p>Terminates rather than spinning: this method restarts the schedule at most once per call,
+     * and a fresh {@link #onReplyQueued} / {@link #onTicketTerminal} racing the recheck below still
+     * terminates in one of two ways — either it observes the slot already vacated (by the
+     * {@code activeLeads.remove} above, which happens-before this recheck in program order) and
+     * claims it itself, or it lands first and this recheck then observes its work in
+     * {@link #pendingReplies} / {@link #pendingTickets} and reclaims the slot instead. Exactly one
+     * side always wins; neither can miss the other, so this never loops on its own account.
      */
-    void stopOrRestartTicketLoop(String lead, Set<String> pendingBefore) {
+    void stopOrRestart(String lead, Set<String> repliesBefore, Set<String> ticketsBefore) {
         activeLeads.remove(lead);
-        boolean ticketRacedIn = pendingFor(lead).stream().anyMatch(t -> !pendingBefore.contains(t.ticket()));
-        if (ticketRacedIn && activeLeads.putIfAbsent(lead, Boolean.TRUE) == null) {
-            log.debug("push: a ticket for lead {} raced the reminder loop's stop — restarting", lead);
-            scheduleTicketTick(lead, 0);
+        boolean racedIn = pendingReplyTargetsFor(lead).stream().anyMatch(t -> !repliesBefore.contains(t))
+                || pendingTicketIdsFor(lead).stream().anyMatch(t -> !ticketsBefore.contains(t));
+        if (racedIn && activeLeads.putIfAbsent(lead, Boolean.TRUE) == null) {
+            log.debug("push: new work for lead {} raced the reminder loop's stop — restarting", lead);
+            scheduleNext(lead, 0, 0);
             return;
         }
-        log.debug("push: ticket reminder loop ended for lead {}", lead);
+        log.debug("push: reminder loop ended for lead {}", lead);
     }
 
-    /** Send the coalesced ticket nudge and log the event. */
-    private void injectTicketNudge(String lead, int reminderCount) {
-        // Re-read rather than threading it down from decideTickets(): a ticket can be collected (or
-        // another can arrive) between the decision and the injection.
-        List<PendingTicket> pending = pendingFor(lead);
-        if (pending.isEmpty()) {
-            log.debug("push: pending tickets for lead {} drained before the nudge could be sent", lead);
+    /** Send one combined nudge covering everything currently pending for {@code lead}. */
+    private void injectNudge(String lead, int replyReminderCount, int ticketReminderCount) {
+        // Re-read rather than threading it down from decide(): a reply can drain, or a ticket be
+        // collected (or another arrive), between the decision and the injection.
+        Set<String> replyTargets = pendingReplyTargetsFor(lead);
+        List<PendingTicket> tickets = pendingTicketsFor(lead);
+        if (replyTargets.isEmpty() && tickets.isEmpty()) {
+            log.debug("push: pending work for lead {} drained before the nudge could be sent", lead);
             return;
         }
-        String nudge = formatTicketsNudge(pending);
+        String nudge = formatNudge(replyTargets, tickets);
         try {
             agents.send(lead, nudge);
-            log.debug("push: ticket nudge {}/{} sent to lead {} for {} ticket(s)",
-                    reminderCount + 1, maxReminders, lead, pending.size());
+            log.debug("push: nudge sent to lead {} (reply {}/{}, ticket {}/{}; {} reply target(s), {} ticket(s))",
+                    lead, replyReminderCount + 1, maxReminders, ticketReminderCount + 1, maxReminders,
+                    replyTargets.size(), tickets.size());
             countNudge("delivered");
         } catch (RuntimeException e) {
-            log.warn("push: failed to nudge lead {} for {} ticket(s) (reminder {}/{}): {}",
-                    lead, pending.size(), reminderCount + 1, maxReminders, e.toString());
+            log.warn("push: failed to nudge lead {} (reply {}/{}, ticket {}/{}): {}",
+                    lead, replyReminderCount + 1, maxReminders, ticketReminderCount + 1, maxReminders, e.toString());
         }
     }
 
-    /** Schedule the next ticket-loop tick on the scheduler thread pool. */
-    private void scheduleTicketTick(String lead, int nextReminderCount) {
-        scheduler.schedule(() -> ticketTick(lead, nextReminderCount), backoffMs, TimeUnit.MILLISECONDS);
+    /** Schedule the next tick on the scheduler thread pool. */
+    private void scheduleNext(String lead, int nextReplyReminderCount, int nextTicketReminderCount) {
+        scheduler.schedule(() -> tick(lead, nextReplyReminderCount, nextTicketReminderCount),
+                backoffMs, TimeUnit.MILLISECONDS);
     }
 
-    /** Render one or several pending tickets as a single nudge line. */
+    // --- nudge formatting ------------------------------------------------------------------------
+
+    /** Render everything pending for one lead as a single nudge line. */
+    private static String formatNudge(Set<String> replyTargets, List<PendingTicket> tickets) {
+        List<String> parts = new ArrayList<>();
+        if (!replyTargets.isEmpty()) {
+            parts.add(formatRepliesNudge(replyTargets));
+        }
+        if (!tickets.isEmpty()) {
+            parts.add(formatTicketsNudge(tickets));
+        }
+        return String.join(" | ", parts);
+    }
+
+    /** Render one or several pending reply targets. */
+    private static String formatRepliesNudge(Set<String> targets) {
+        if (targets.size() == 1) {
+            String target = targets.iterator().next();
+            return NUDGE_FORMAT.formatted(target, target);
+        }
+        String ids = String.join(", ", targets);
+        return REPLIES_NUDGE_FORMAT.formatted(targets.size(), ids);
+    }
+
+    /** Render one or several pending tickets. */
     private static String formatTicketsNudge(List<PendingTicket> pending) {
         if (pending.size() == 1) {
             PendingTicket t = pending.get(0);
@@ -383,23 +393,22 @@ public final class ReplyPushLoop {
     // --- lifecycle -----------------------------------------------------------------------------
 
     /**
-     * Whether any reminder loop is currently active for some target (CB-551). The idle-lead heartbeat
-     * uses this to stand aside: while the push loop is actively nudging the lead, a concurrent
-     * heartbeat injection would start a second competing turn in the same pane — racing loops multiply
-     * turns and context burn. "Active" means a schedule exists in {@link #activeTargets} or
-     * {@link #activeLeads} (CB-588 ticket nudges are a second source of pane injections the heartbeat
-     * must equally stand aside for); the sets are bounded by what has been triggered, not by any
-     * persistent state.
+     * Whether any reminder loop is currently active for some lead (CB-551). The idle-lead heartbeat
+     * uses this to stand aside: while the push loop is actively nudging a lead, a concurrent
+     * heartbeat injection would start a second competing turn in the same pane — racing loops
+     * multiply turns and context burn. "Active" means a schedule exists in {@link #activeLeads},
+     * which now covers both reply-queued (CB-307) and ticket-terminal (CB-588) work (CB-590) —
+     * bounded by what has been triggered, not by any persistent state.
      */
     public boolean isActive() {
-        return !activeTargets.isEmpty() || !activeLeads.isEmpty();
+        return !activeLeads.isEmpty();
     }
 
     /** Shut down the scheduler. Outstanding reminders are cancelled. */
     public void stop() {
         scheduler.shutdownNow();
-        activeTargets.clear();
         activeLeads.clear();
+        pendingReplies.clear();
         pendingTickets.clear();
     }
 

bridged/src/main/java/dev/ltms/bridged/rest/BridgedApp.java

@@ -13,6 +13,7 @@ import dev.ltms.bridged.herdr.HerdrClient;
 import dev.ltms.bridged.herdr.HerdrException;
 import dev.ltms.bridged.inject.MemberPresence;
 import dev.ltms.bridged.peer.PeerUnreachableException;
+import dev.ltms.bridged.placement.PlacementException;
 import dev.ltms.bridged.msg.MessageService;
 import dev.ltms.bridged.session.SessionManager;
 import dev.ltms.bridged.peer.MemberRole;
@@ -292,6 +293,11 @@ public final class BridgedApp {
             ctx.status(201).json(view(member));
         } catch (GuardException e) {
             ctx.status(403).json(Map.of("error", "subscription_boundary", "detail", e.getMessage()));
+        } catch (PlacementException e) {
+            // CB-599: no candidate had capacity (maxLoad, quarantine, or all-exhausted) — a benign,
+            // likely-transient refusal, distinct from "profile does not exist" below. 503: the
+            // request was valid and will likely succeed later.
+            ctx.status(503).json(Map.of("error", "no_capacity", "detail", e.getMessage()));
         } catch (IllegalArgumentException e) {
             ctx.status(400).json(Map.of("error", "unknown_profile", "detail", e.getMessage()));
         } catch (PeerUnreachableException e) {

bridged/src/test/java/dev/ltms/bridged/RequiredSecretEnvVarsTest.java

@@ -0,0 +1,114 @@
+package dev.ltms.bridged;
+
+import dev.ltms.bridged.config.BridgedConfig;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * CB-594: {@link Bridged#requiredSecretEnvVars(BridgedConfig)} is what decides what the startup
+ * secret report checks — it must derive that set from the config, not a hand-written list, or a
+ * new profile's token silently stops being reported.
+ */
+class RequiredSecretEnvVarsTest {
+
+    private static BridgedConfig load(Path dir, String yaml) throws Exception {
+        Path f = dir.resolve("bridged.yaml");
+        Files.writeString(f, yaml);
+        return BridgedConfig.load(f);
+    }
+
+    @Test
+    void collectsATokenEnvPerNonSubscriptionProfile(@TempDir Path dir) throws Exception {
+        BridgedConfig cfg = load(dir, """
+                profiles:
+                  local:
+                    baseUrl: http://gx00.gw:8000
+                    tokenEnv: AI_GATEWAY_TOKEN
+                """);
+
+        Map<String, List<String>> required = Bridged.requiredSecretEnvVars(cfg);
+
+        assertTrue(required.containsKey("AI_GATEWAY_TOKEN"));
+        assertEquals(List.of("profile 'local' tokenEnv"), required.get("AI_GATEWAY_TOKEN"));
+    }
+
+    @Test
+    void aSubscriptionProfileNeedsNoTokenEnv(@TempDir Path dir) throws Exception {
+        BridgedConfig cfg = load(dir, """
+                profiles:
+                  opus:
+                    subscription: true
+                    model: claude-opus-5
+                """);
+
+        assertTrue(Bridged.requiredSecretEnvVars(cfg).isEmpty(),
+                "subscription: true never reads ANTHROPIC_AUTH_TOKEN — see Profile#isSubscription");
+    }
+
+    @Test
+    void gitTokenEnvIsOptInAndCollectedWhenSet(@TempDir Path dir) throws Exception {
+        BridgedConfig cfg = load(dir, """
+                profiles:
+                  local:
+                    baseUrl: http://gx00.gw:8000
+                    tokenEnv: AI_GATEWAY_TOKEN
+                    gitTokenEnv: WORKER_GITEA_TOKEN
+                """);
+
+        Map<String, List<String>> required = Bridged.requiredSecretEnvVars(cfg);
+
+        assertTrue(required.containsKey("WORKER_GITEA_TOKEN"));
+        assertEquals(List.of("profile 'local' gitTokenEnv"), required.get("WORKER_GITEA_TOKEN"));
+    }
+
+    @Test
+    void noGitTokenEnvMeansNothingIsRequiredForIt(@TempDir Path dir) throws Exception {
+        BridgedConfig cfg = load(dir, """
+                profiles:
+                  local:
+                    baseUrl: http://gx00.gw:8000
+                    tokenEnv: AI_GATEWAY_TOKEN
+                """);
+
+        assertFalse(Bridged.requiredSecretEnvVars(cfg).containsKey("WORKER_GITEA_TOKEN"));
+    }
+
+    @Test
+    void aVarSharedByTwoProfilesIsReportedOnceNamingBoth(@TempDir Path dir) throws Exception {
+        BridgedConfig cfg = load(dir, """
+                profiles:
+                  local:
+                    baseUrl: http://gx00.gw:8000
+                    tokenEnv: AI_GATEWAY_TOKEN
+                    gitTokenEnv: WORKER_GITEA_TOKEN
+                  gx:
+                    kind: opencode
+                    baseUrl: https://llm.ltms.dev/v1
+                    tokenEnv: AI_GATEWAY_TOKEN
+                    gitTokenEnv: WORKER_GITEA_TOKEN
+                """);
+
+        Map<String, List<String>> required = Bridged.requiredSecretEnvVars(cfg);
+
+        assertEquals(List.of("profile 'local' tokenEnv", "profile 'gx' tokenEnv"),
+                required.get("AI_GATEWAY_TOKEN"));
+        assertEquals(List.of("profile 'local' gitTokenEnv", "profile 'gx' gitTokenEnv"),
+                required.get("WORKER_GITEA_TOKEN"));
+    }
+
+    @Test
+    void noProfilesMeansNothingIsRequired(@TempDir Path dir) throws Exception {
+        BridgedConfig cfg = load(dir, "bind:\n  host: 127.0.0.1\n  port: 8765\n");
+
+        assertTrue(Bridged.requiredSecretEnvVars(cfg).isEmpty());
+    }
+}

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

@@ -10,6 +10,7 @@ import java.nio.file.Path;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
+import java.util.regex.Pattern;
 
 import static org.junit.jupiter.api.Assertions.*;
 
@@ -1189,6 +1190,79 @@ class BridgedConfigTest {
         assertEquals(5, cfg.leadHeartbeat().quietNudgeCap());
     }
 
+    /**
+     * A top-level key {@code BridgedConfig} reads but that appears nowhere in
+     * {@code bridged.example.yaml} — live or commented — is invisible drift: {@code bridged.yaml}
+     * is gitignored, so the example is the ONLY committed description of the config schema, and
+     * neither {@link #shippedExampleConfigParses} (example → code: does the example still parse)
+     * nor {@link #everyOptionalKnobDocumentedInTheExampleBinds} (a hand-maintained list of keys
+     * that must bind) can catch a brand-new key nobody added to either.
+     *
+     * <p>This test compares the OTHER direction: every key in {@link BridgedConfig#KNOWN_TOP_LEVEL_KEYS}
+     * (the parser's own accepted set, which backs the unknown-key WARN) must appear as a top-level
+     * key in the example text, live or commented-out — see {@link #topLevelKeyDocumented}.
+     */
+    @Test
+    void everyKnownTopLevelKeyIsDocumentedInTheExample() throws Exception {
+        Path example = Path.of("bridged.example.yaml");
+        assertTrue(Files.exists(example), "bridged.example.yaml must ship next to the pom");
+        String text = Files.readString(example);
+
+        List<String> undocumented = BridgedConfig.KNOWN_TOP_LEVEL_KEYS.stream()
+                .filter(key -> !topLevelKeyDocumented(text, key))
+                .sorted()
+                .toList();
+
+        assertTrue(undocumented.isEmpty(), () -> "key(s) " + undocumented
+                + " are read by BridgedConfig but appear nowhere in bridged.example.yaml — "
+                + "document each one there, commented out if optional. bridged.yaml is "
+                + "gitignored, so this file is the only committed description of the config "
+                + "schema an operator or a worker can see.");
+    }
+
+    /**
+     * Most of {@code bridged.example.yaml} is deliberately commented out — optional sections are
+     * documented as commented blocks so the shipped file stays a working minimal config. A key
+     * documented ONLY as a comment must still count as documented; parsing the file as YAML and
+     * reading its live key set (as an earlier attempt at this guard did) gets this wrong, because
+     * every commented section then looks entirely absent.
+     */
+    @Test
+    void commentedOnlyTopLevelKeyCountsAsDocumented() {
+        String yaml = """
+                bind:
+                  port: 8765
+                # broker:
+                #   uri: amqp://guest:guest@127.0.0.1:5672
+                """;
+        assertTrue(topLevelKeyDocumented(yaml, "broker"),
+                "a key documented only inside a commented-out block must still count as documented");
+    }
+
+    /** A key that appears in neither a live nor a commented top-level line must NOT count. */
+    @Test
+    void absentTopLevelKeyIsNotDocumented() {
+        String yaml = """
+                bind:
+                  port: 8765
+                """;
+        assertFalse(topLevelKeyDocumented(yaml, "broker"),
+                "a key mentioned nowhere in the example must not be reported as documented");
+    }
+
+    /**
+     * True when {@code key} appears as a top-level YAML key in {@code yaml} — either live
+     * ({@code key:} at column 0) or commented out ({@code # key:}, also at column 0, with only
+     * whitespace between the {@code #} and the key). Anchoring on column 0 is what keeps this a
+     * top-level check: an indented occurrence (a nested field, or prose inside a comment that
+     * happens to end in a colon) never matches, because {@code ^} requires the key's own first
+     * character — or the sole leading {@code #} — to sit at the very start of the line.
+     */
+    private static boolean topLevelKeyDocumented(String yaml, String key) {
+        Pattern p = Pattern.compile("(?m)^(?:#\\s*)?" + Pattern.quote(key) + ":");
+        return p.matcher(yaml).find();
+    }
+
     @Test
     void placementDefaultsToFixedForExistingConfigs(@TempDir Path dir) throws Exception {
         Path f = dir.resolve("no-placement.yaml");

bridged/src/test/java/dev/ltms/bridged/mcp/BridgeMcpTest.java

@@ -16,12 +16,15 @@ import dev.ltms.bridged.inject.MemberPresence;
 import dev.ltms.bridged.session.MemberSession;
 import dev.ltms.bridged.session.WorktreeRequest;
 import dev.ltms.bridged.member.ClaudeCodeLauncher;
+import dev.ltms.bridged.member.CompositePeerLauncher;
 import dev.ltms.bridged.placement.BackendQuarantine;
+import dev.ltms.bridged.placement.PlacementPolicies;
 import io.modelcontextprotocol.spec.McpSchema;
 import dev.ltms.bridged.msg.InMemoryReplyInbox;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 
+import java.util.List;
 import java.util.Map;
 import java.util.Set;
 import java.util.concurrent.CompletableFuture;
@@ -423,6 +426,35 @@ class BridgeMcpTest {
         assertTrue(textOf(res).contains("unknown worker profile"), textOf(res));
     }
 
+    /**
+     * CB-599: a profile at its {@code maxLoad} cap must surface a readable reason on the MCP
+     * surface too, not merely flip {@code isError} with an opaque or absent message.
+     */
+    @Test
+    void spawnAtMaxLoadSurfacesTheCapacityReason() {
+        FakeHerdr h = new FakeHerdr();
+        BridgedConfig.Profile wcfg = new BridgedConfig.Profile(
+                "ltms-local", "http://gx00.gw:8000", "coder", null, "BRIDGED_WORKER_TOKEN", null,
+                "tab", "bridged-workers", "worker: {profile} #{n}", null,
+                null, null, null, null, null, null, null, 0, null, null, null);
+        Map<String, BridgedConfig.Profile> profiles = Map.of(wcfg.profile(), wcfg);
+        ClaudeCodeLauncher delegate = new ClaudeCodeLauncher(
+                new AgentControl(h), new WorkspaceControl(h), new SubscriptionGuard(Set.of("gx00.gw")),
+                profiles, wcfg.profile(), k -> "BRIDGED_WORKER_TOKEN".equals(k) ? "tok" : null);
+        CompositePeerLauncher composite = new CompositePeerLauncher(
+                List.of(delegate), wcfg.profile(), profiles, PlacementPolicies.fixed(), _ -> 0);
+        SessionManager sm = new SessionManager(composite);
+
+        McpSchema.CallToolResult res = BridgeMcp.spawn(sm, "ltms-local");
+
+        assertTrue(res.isError());
+        String text = textOf(res);
+        assertTrue(text.contains("no capacity"), "surfaces a capacity reason, not a bare error: " + text);
+        assertTrue(text.contains("ltms-local"), "names the profile: " + text);
+        assertTrue(text.contains("maxLoad"), "explains the refusal: " + text);
+        assertFalse(h.called("agent.start"), "at cap, the spawn is refused before any herdr call");
+    }
+
     @Test
     void spawnPassesTheRequestedCwdToTheWorker() {
         FakeHerdr h = new FakeHerdr();

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

@@ -676,6 +676,85 @@ class ClaudeCodeLauncherTest {
                 "the guard-checked baseUrl must win over any env: entry, or the boundary is bypassable");
     }
 
+    // --- CB-592: the admin GITEA_ACCESS_TOKEN never reaches a member -----------------------------
+
+    /**
+     * herdr's env map is an overlay onto its own (login-shell) process environment, so a worker
+     * inherits whatever the daemon's shell carries — including the admin GITEA_ACCESS_TOKEN — for
+     * every key baseEnv does not explicitly shadow. This pins that the launcher DOES send an
+     * explicit (non-blank) GITEA_ACCESS_TOKEN to herdr on every spawn, whatever the profile is, so
+     * a future baseEnv refactor cannot silently drop it and reopen the leak. Asserted against what
+     * tab.create's params actually carry, not an internal map built in the test (gitea #77).
+     *
+     * <p>Scope, measured on a live pane 2026-08-15: this pins what the launcher SENDS, and that is
+     * all it can pin. It does not prove the value survives, and it does not: the pane runs a login
+     * shell, ~/.zprofile sources secrets.sh, and its unconditional `export GITEA_ACCESS_TOKEN=...`
+     * puts the real token back over this sentinel. Closing that needs the operator to guard the
+     * export on BRIDGED_MEMBER — see everySpawnMarksThePaneAsAMember below.
+     */
+    @Test
+    void everySpawnShadowsTheAdminGiteaAccessToken() {
+        FakeHerdr herdr = new FakeHerdr();
+        service(herdr, List.of("claude"), null).spawn();
+
+        String shadowed = startEnv(herdr).get("GITEA_ACCESS_TOKEN");
+        assertNotNull(shadowed, "GITEA_ACCESS_TOKEN must be explicitly overlaid, not left unmentioned");
+        assertFalse(shadowed.isBlank(), "a blank overlay value's override behaviour is unverified — must be non-blank");
+    }
+
+    /**
+     * No profile — present or future — may restore the admin token by naming it in {@code env:}.
+     * The shadow is applied after the profile's own env in {@link HerdrPeerLauncher#baseEnv}
+     * precisely so this can never happen; this test pins that ordering.
+     */
+    @Test
+    void aProfileEnvEntryCannotRestoreTheAdminGiteaAccessToken() {
+        FakeHerdr herdr = new FakeHerdr();
+        BridgedConfig.Profile cfg = new BridgedConfig.Profile(
+                "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("GITEA_ACCESS_TOKEN", "admin-secret-from-profile-config"), 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();
+
+        assertNotEquals("admin-secret-from-profile-config", startEnv(herdr).get("GITEA_ACCESS_TOKEN"),
+                "a profile's own env: must not be able to smuggle the admin token back in");
+    }
+
+    /**
+     * The half of CB-592 that can actually survive the pane's login shell. BRIDGED_MEMBER is a name
+     * secrets.sh never exports, so nothing overwrites it — measured: GITEA_TOKEN is injected the
+     * same way, is absent from a login shell of its own, and was observed set inside a live member
+     * pane. It lets the operator guard the admin export with
+     * `[ -n "${BRIDGED_MEMBER:-}" ] || export GITEA_ACCESS_TOKEN=...`, which is the whole fix.
+     * Pinned here so a refactor cannot drop the marker and quietly un-guard every member (#77).
+     */
+    @Test
+    void everySpawnMarksThePaneAsAMember() {
+        FakeHerdr herdr = new FakeHerdr();
+        service(herdr, List.of("claude"), null).spawn();
+
+        assertEquals("1", startEnv(herdr).get("BRIDGED_MEMBER"),
+                "every member pane must be marked, or a shell file cannot tell it apart from the operator's");
+    }
+
+    /** A profile must not be able to hide that its pane is a member, for the same reason as above. */
+    @Test
+    void aProfileEnvEntryCannotClearTheMemberMarker() {
+        FakeHerdr herdr = new FakeHerdr();
+        BridgedConfig.Profile cfg = new BridgedConfig.Profile(
+                "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("BRIDGED_MEMBER", ""), 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();
+
+        assertEquals("1", startEnv(herdr).get("BRIDGED_MEMBER"),
+                "a profile's own env: must not be able to unmark its pane");
+    }
+
     // ── CB-533: the model is pinned on the command line, not only in the environment ────────────
 
     /** A launcher for a profile identical but for its {@code model:} — the only variable here. */

bridged/src/test/java/dev/ltms/bridged/member/OpenCodeLauncherTest.java

@@ -208,6 +208,21 @@ class OpenCodeLauncherTest {
                 "a git-token profile gets the peer-neutral GITEA_TOKEN grant, same as Claude");
     }
 
+    /**
+     * CB-592: the shadow lives in {@link HerdrPeerLauncher#baseEnv}, shared by every adapter — this
+     * pins that the opencode path gets it too, not just Claude's. See the matching test in
+     * {@code ClaudeCodeLauncherTest} for the full rationale (gitea #77).
+     */
+    @Test
+    void everySpawnShadowsTheAdminGiteaAccessToken(@TempDir Path root) {
+        FakeHerdr herdr = new FakeHerdr();
+        service(herdr, root, opencodeCfg(null, null, null)).spawn();
+
+        String shadowed = startEnv(herdr).get("GITEA_ACCESS_TOKEN");
+        assertNotNull(shadowed, "GITEA_ACCESS_TOKEN must be explicitly overlaid, not left unmentioned");
+        assertFalse(shadowed.isBlank(), "a blank overlay value's override behaviour is unverified — must be non-blank");
+    }
+
     @Test
     void capabilitiesDeclareOrphanReapAndMcpAskAndConditionalSelfPr(@TempDir Path root) {
         FakeHerdr herdr = new FakeHerdr();

bridged/src/test/java/dev/ltms/bridged/msg/AmqpReplyInboxContractTest.java

@@ -16,6 +16,7 @@ import java.util.List;
 import java.util.concurrent.TimeUnit;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
 /**
@@ -166,6 +167,88 @@ class AmqpReplyInboxContractTest {
         }
     }
 
+    @Test
+    void prefetchBoundsTheHeldBacklog() throws Exception {
+        String target = "worker-prefetch-" + System.nanoTime();
+        int prefetch = 4;
+        int published = 10;
+        try (AmqpReplyInbox inbox = new AmqpReplyInbox(newConnection(), prefetch);
+             Connection inspect = newConnection()) {
+            inbox.own(target);
+            for (int i = 0; i < published; i++) {
+                inbox.publish(target, "m" + i, "payload " + i);
+            }
+            awaitHeldAtLeast(inbox, target, prefetch);
+
+            long depth;
+            try (Channel ch = inspect.createChannel()) {
+                depth = ch.queueDeclarePassive(queueName(target)).getMessageCount();
+            }
+            assertTrue(depth >= published - prefetch,
+                    "broker should still hold at least " + (published - prefetch)
+                            + " undelivered messages behind a prefetch of " + prefetch + ", saw " + depth);
+
+            drainUntilEmpty(inbox, target, inspect);
+        }
+    }
+
+    @Test
+    void unroutablePublishReportsFailureNotSilentSuccess() throws Exception {
+        String target = "worker-unroutable-" + System.nanoTime();
+        try (AmqpReplyInbox inbox = AmqpReplyInbox.open(uri())) {
+            // Deliberately never own(target): the queue is never declared, so the default-exchange
+            // route to agent.<target>.inbox does not exist and the broker must return the publish.
+            IllegalStateException ex = assertThrows(IllegalStateException.class,
+                    () -> inbox.publish(target, "m1", "nobody home"));
+            assertTrue(ex.getMessage() != null && ex.getMessage().toLowerCase().contains("unroutable"),
+                    "expected an unroutable-publish failure, got: " + ex.getMessage());
+        }
+    }
+
+    @Test
+    void confirmedPublishDeliversNormally() throws Exception {
+        String target = "worker-confirm-" + System.nanoTime();
+        try (AmqpReplyInbox inbox = AmqpReplyInbox.open(uri())) {
+            inbox.own(target);
+            inbox.publish(target, "m1", "confirmed delivery"); // must return normally: routed and confirmed
+
+            List<ReplyInbox.InboxMessage> got = awaitPeek(inbox, target);
+            assertEquals(1, got.size());
+            assertEquals("confirmed delivery", got.getFirst().content());
+            inbox.ack(target, "m1");
+        }
+    }
+
+    /** Poll peek until at least {@code n} replies for {@code target} are held, or ~10s elapse. */
+    @SuppressWarnings("BusyWait")
+    private static void awaitHeldAtLeast(AmqpReplyInbox inbox, String target, int n) throws InterruptedException {
+        long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(10);
+        while (inbox.peek(target).size() < n && System.nanoTime() < deadline) {
+            Thread.sleep(50);
+        }
+    }
+
+    /**
+     * Repeatedly ack whatever is currently held (freeing prefetch slots for the next delivery) until
+     * both the local snapshot and the broker's own queue depth are empty, or ~10s elapse.
+     */
+    @SuppressWarnings("BusyWait")
+    private static void drainUntilEmpty(AmqpReplyInbox inbox, String target, Connection inspect) throws Exception {
+        long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(10);
+        while (System.nanoTime() < deadline) {
+            for (ReplyInbox.InboxMessage msg : inbox.peek(target)) {
+                inbox.ack(target, msg.msgId());
+            }
+            try (Channel ch = inspect.createChannel()) {
+                if (ch.queueDeclarePassive(queueName(target)).getMessageCount() == 0 && inbox.peek(target).isEmpty()) {
+                    return;
+                }
+            }
+            Thread.sleep(50);
+        }
+        throw new AssertionError("did not drain " + target + " to empty within the deadline");
+    }
+
     /** Poll peek (broker delivery is async) until a reply for {@code target} appears or ~10s elapse. */
     @SuppressWarnings("BusyWait") // deliberate poll for async broker delivery, bounded by the deadline
     private static List<ReplyInbox.InboxMessage> awaitPeek(AmqpReplyInbox inbox, String target)

bridged/src/test/java/dev/ltms/bridged/msg/AmqpReplyInboxRecoveryRaceTest.java

@@ -0,0 +1,264 @@
+package dev.ltms.bridged.msg;
+
+import com.rabbitmq.client.AMQP;
+import com.rabbitmq.client.Channel;
+import com.rabbitmq.client.ConfirmCallback;
+import com.rabbitmq.client.Connection;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.Timeout;
+
+import java.lang.reflect.InvocationHandler;
+import java.lang.reflect.Proxy;
+import java.util.List;
+import java.util.concurrent.CopyOnWriteArrayList;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.concurrent.atomic.AtomicLong;
+import java.util.concurrent.atomic.AtomicReference;
+
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * CB-528 follow-up: {@link AmqpReplyInbox#failPendingPublishesOnRecovery()} must not fail a publish
+ * that registers concurrently with (and was not yet visible when) the recovery sweep began — that
+ * would report a publish that actually succeeded as failed, and {@code MessageService.reply} retries
+ * with a fresh {@code msgId}, so the reply is delivered twice. A live broker reconnect cannot be
+ * forced reliably, so this drives {@link AmqpReplyInbox#failPendingPublishesOnRecovery} and a real
+ * {@link AmqpReplyInbox#publish} against each other directly, against fake AMQP channels built with
+ * {@link Proxy} (no mocking library is on the classpath).
+ *
+ * <p>Also covers Finding 2 (CB-528 follow-up): {@link AmqpReplyInbox#close()} must fail an in-flight
+ * publish promptly instead of leaving it to idle out the 10s confirm timeout.
+ */
+class AmqpReplyInboxRecoveryRaceTest {
+
+    /** Large enough that the (unfixed) unsynchronized sweep's iteration is a real, observable window
+     *  a concurrently-started publish can land in — not just a best case, single-entry sprint. */
+    private static final int STALE_PUBLISHES = 100_000;
+
+    @Test
+    @Timeout(30)
+    void recoverySweepDoesNotFailAPublishThatRegistersWhileItIsRunning() throws Exception {
+        AtomicLong seqCounter = new AtomicLong();
+        List<Long> seqOrder = new CopyOnWriteArrayList<>();
+        List<String> msgIdOrder = new CopyOnWriteArrayList<>();
+        AtomicReference<ConfirmCallback> ackCallback = new AtomicReference<>();
+        AtomicReference<ConfirmCallback> nackCallback = new AtomicReference<>();
+
+        Channel publishChannel = fakeChannel(seqCounter, seqOrder, msgIdOrder, ackCallback, nackCallback);
+        Channel consumeChannel = fakeChannel(seqCounter, seqOrder, msgIdOrder, ackCallback, nackCallback);
+        Connection connection = fakeConnection(consumeChannel, publishChannel);
+
+        AmqpReplyInbox inbox = new AmqpReplyInbox(connection, AmqpReplyInbox.DEFAULT_PREFETCH);
+
+        // STALE_PUBLISHES in-flight publishes that never get confirmed — they sit in pendingBySeq /
+        // pendingByMsgId exactly like publishes whose confirm never arrived before a connection drop.
+        // Virtual threads make this many concurrent blocking publish() calls cheap.
+        CountDownLatch staleStarted = new CountDownLatch(STALE_PUBLISHES);
+        for (int i = 0; i < STALE_PUBLISHES; i++) {
+            String msgId = "stale-" + i;
+            Thread.ofVirtual().start(() -> {
+                staleStarted.countDown();
+                try {
+                    inbox.publish("worker-stale", msgId, "x");
+                } catch (IllegalStateException expected) {
+                    // resolved (failed by the sweep) — that is exactly what this thread is here for
+                }
+            });
+        }
+        staleStarted.await();
+        // Let the registrations (the synchronized put into pendingBySeq/pendingByMsgId) actually land
+        // for all of them before the sweep starts, so the sweep begins with a large, real backlog.
+        Thread.sleep(300);
+
+        AtomicReference<Throwable> sweepError = new AtomicReference<>();
+        Thread sweepThread = new Thread(() -> {
+            try {
+                inbox.failPendingPublishesOnRecovery();
+            } catch (Throwable t) {
+                sweepError.set(t);
+            }
+        }, "recovery-sweep");
+        sweepThread.start();
+        // A short, deliberate head start: with STALE_PUBLISHES this large, the (unfixed) sweep's own
+        // iteration takes several milliseconds, so this guarantees the sweep has already begun —
+        // and, once guarded, is already holding publishChannelLock — before "fresh" attempts to
+        // register. Without this head start, "fresh" sometimes wins the race for the lock and
+        // registers before the sweep even starts, which is the accepted "already in flight when
+        // recovery fires" case (correctly failed either way) rather than the bug under test.
+        Thread.sleep(5);
+
+        // This is the exact interleaving CB-528's follow-up describes: "the still-running recovery
+        // sweep" racing a publish that registers while it is mid-flight.
+        AtomicReference<Throwable> publishError = new AtomicReference<>();
+        Thread freshThread = new Thread(() -> {
+            try {
+                inbox.publish("worker-fresh", "fresh", "hello");
+            } catch (Throwable t) {
+                publishError.set(t);
+            }
+        }, "fresh-publish");
+        freshThread.start();
+
+        sweepThread.join(20_000);
+        assertNull(sweepError.get(), "sweep threw: " + sweepError.get());
+
+        // Simulate the broker's real confirm for "fresh" now that the sweep is done, so a correct
+        // implementation's publish() returns normally instead of idling out CONFIRM_TIMEOUT_MS. Poll
+        // for the registration rather than checking once: freshThread may still be contending for
+        // publishChannelLock (behind the 20,000 stale threads' own lock acquisitions) even though the
+        // sweep itself has already finished.
+        long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(9);
+        int idx = -1;
+        while (idx < 0 && System.nanoTime() < deadline) {
+            idx = msgIdOrder.indexOf("fresh");
+            if (idx < 0) {
+                Thread.sleep(20);
+            }
+        }
+        if (idx >= 0 && ackCallback.get() != null) {
+            ackCallback.get().handle(seqOrder.get(idx), false);
+        }
+        freshThread.join(15_000);
+
+        assertNull(publishError.get(),
+                "a publish that registered while the recovery sweep was running must not be failed by "
+                        + "it, but got: " + publishError.get());
+    }
+
+    @Test
+    @Timeout(15)
+    void closeFailsInFlightPublishPromptlyInsteadOfWaitingOutTheConfirmTimeout() throws Exception {
+        AtomicLong seqCounter = new AtomicLong();
+        List<Long> seqOrder = new CopyOnWriteArrayList<>();
+        List<String> msgIdOrder = new CopyOnWriteArrayList<>();
+        AtomicReference<ConfirmCallback> ackCallback = new AtomicReference<>();
+        AtomicReference<ConfirmCallback> nackCallback = new AtomicReference<>();
+
+        Channel publishChannel = fakeChannel(seqCounter, seqOrder, msgIdOrder, ackCallback, nackCallback);
+        Channel consumeChannel = fakeChannel(seqCounter, seqOrder, msgIdOrder, ackCallback, nackCallback);
+        Connection connection = fakeConnection(consumeChannel, publishChannel);
+
+        AmqpReplyInbox inbox = new AmqpReplyInbox(connection, AmqpReplyInbox.DEFAULT_PREFETCH);
+
+        CountDownLatch publishReturned = new CountDownLatch(1);
+        AtomicReference<Throwable> publishError = new AtomicReference<>();
+        AtomicLong elapsedMillis = new AtomicLong();
+        Thread publishThread = new Thread(() -> {
+            long start = System.nanoTime();
+            try {
+                inbox.publish("worker-close", "never-confirmed", "x");
+            } catch (Throwable t) {
+                publishError.set(t);
+            } finally {
+                elapsedMillis.set((System.nanoTime() - start) / 1_000_000);
+                publishReturned.countDown();
+            }
+        }, "publish-during-close");
+        publishThread.start();
+
+        Thread.sleep(200); // let publish() register before close() runs
+        inbox.close();
+
+        assertTrue(publishReturned.await(5, TimeUnit.SECONDS), "publish() did not return after close()");
+        assertNotNull(publishError.get(), "a publish in flight when close() runs must fail, not hang");
+        assertTrue(publishError.get().getMessage() != null
+                        && publishError.get().getMessage().toLowerCase().contains("closed"),
+                "expected a clear closed-inbox message, got: " + publishError.get());
+        assertTrue(elapsedMillis.get() < 5_000,
+                "close() should fail the in-flight publish promptly, not wait out the confirm timeout — took "
+                        + elapsedMillis.get() + "ms");
+    }
+
+    /** A {@link Proxy}-backed {@link Channel}: only the calls {@link AmqpReplyInbox} actually makes
+     *  are meaningfully implemented; everything else returns a harmless default. */
+    private static Channel fakeChannel(AtomicLong seqCounter, List<Long> seqOrder, List<String> msgIdOrder,
+                                        AtomicReference<ConfirmCallback> ackCallback,
+                                        AtomicReference<ConfirmCallback> nackCallback) {
+        InvocationHandler handler = (proxy, method, args) -> {
+            String name = method.getName();
+            if (name.equals("getNextPublishSeqNo")) {
+                long value = seqCounter.incrementAndGet();
+                seqOrder.add(value);
+                return value;
+            }
+            if (name.equals("basicPublish")) {
+                AMQP.BasicProperties props = (AMQP.BasicProperties) args[3];
+                msgIdOrder.add(props.getMessageId());
+                return null;
+            }
+            if (name.equals("addConfirmListener")) {
+                ackCallback.set((ConfirmCallback) args[0]);
+                nackCallback.set((ConfirmCallback) args[1]);
+                return null;
+            }
+            if (name.equals("equals")) {
+                return proxy == args[0];
+            }
+            if (name.equals("hashCode")) {
+                return System.identityHashCode(proxy);
+            }
+            if (name.equals("toString")) {
+                return "FakeChannel";
+            }
+            return defaultValue(method.getReturnType());
+        };
+        return (Channel) Proxy.newProxyInstance(AmqpReplyInboxRecoveryRaceTest.class.getClassLoader(),
+                new Class<?>[] {Channel.class}, handler);
+    }
+
+    /** A {@link Proxy}-backed {@link Connection} handing out {@code first} then {@code second} from
+     *  successive {@code createChannel()} calls, matching {@link AmqpReplyInbox}'s constructor. */
+    private static Connection fakeConnection(Channel first, Channel second) {
+        AtomicInteger calls = new AtomicInteger();
+        InvocationHandler handler = (proxy, method, args) -> {
+            String name = method.getName();
+            if (name.equals("createChannel") && (args == null || args.length == 0)) {
+                return calls.getAndIncrement() == 0 ? first : second;
+            }
+            if (name.equals("equals")) {
+                return proxy == args[0];
+            }
+            if (name.equals("hashCode")) {
+                return System.identityHashCode(proxy);
+            }
+            if (name.equals("toString")) {
+                return "FakeConnection";
+            }
+            return defaultValue(method.getReturnType());
+        };
+        return (Connection) Proxy.newProxyInstance(AmqpReplyInboxRecoveryRaceTest.class.getClassLoader(),
+                new Class<?>[] {Connection.class}, handler);
+    }
+
+    private static Object defaultValue(Class<?> type) {
+        if (!type.isPrimitive() || type == void.class) {
+            return null;
+        }
+        if (type == boolean.class) {
+            return Boolean.FALSE;
+        }
+        if (type == long.class) {
+            return 0L;
+        }
+        if (type == short.class) {
+            return (short) 0;
+        }
+        if (type == byte.class) {
+            return (byte) 0;
+        }
+        if (type == char.class) {
+            return (char) 0;
+        }
+        if (type == double.class) {
+            return 0.0d;
+        }
+        if (type == float.class) {
+            return 0.0f;
+        }
+        return 0;
+    }
+}

bridged/src/test/java/dev/ltms/bridged/msg/ReplyPushLoopTest.java

@@ -20,6 +20,7 @@ import java.util.concurrent.CountDownLatch;
 import java.util.concurrent.Executors;
 import java.util.concurrent.ScheduledExecutorService;
 import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicInteger;
 
 import static org.junit.jupiter.api.Assertions.*;
 
@@ -27,6 +28,12 @@ import static org.junit.jupiter.api.Assertions.*;
  * Unit tests for {@link ReplyPushLoop}: decision logic, nudge injection, idempotency,
  * bounded reminders, and stop conditions.
  *
+ * <p>CB-590 collapsed the CB-307 reply-nudge schedule and the CB-588 ticket-nudge schedule into
+ * one schedule per lead ({@link ReplyPushLoop#decide}), so most tests below register pending work
+ * through the public entry points ({@code onReplyQueued} / {@code onTicketTerminal}) before
+ * exercising {@code decide} directly, mirroring how the two entry points now share one decision
+ * function keyed by the lead terminal rather than by worker target.
+ *
  * <p>Uses a {@link RecordingHerdrClient} that synchronizes access to its call list so the
  * scheduler thread and test thread never have memory ordering issues. The {@code decide()}
  * tests use a simple client with no concurrency concern.
@@ -58,38 +65,50 @@ class ReplyPushLoopTest {
     // --- decide() logic ------------------------------------------------------------------------
 
     @Test
-    void decideWithoutPrimaryIsStop() {
-        agents = agentWithStatus("idle");
-        var loop = new ReplyPushLoop(
-                new PrimaryRegistry(null), agents, inbox, scheduler, 5, 100);
-        assertEquals(ReplyPushLoop.Action.STOP, loop.decide(WORKER, 0));
+    void onReplyQueuedWithNoKnownLeadNeverStartsASchedule() throws Exception {
+        var rec = recordingClient();
+        agents = new AgentControl(rec);
+        inbox.publish(WORKER, "m1", "hello");
+        var loop = new ReplyPushLoop(new PrimaryRegistry(null), agents, inbox, scheduler, 5, 50);
+
+        loop.onReplyQueued(WORKER); // no lead known -> never registered, never scheduled
+
+        assertFalse(loop.isActive(), "no lead known means nothing to nudge yet");
+        Thread.sleep(150);
+        assertEquals(0, rec.sendCount(), "must not nudge when no lead is known to be waiting");
     }
 
     @Test
-    void decideWithEmptyInboxIsStop() {
+    void decideWithNothingPendingIsStop() {
         agents = agentWithStatus("idle");
-        assertEquals(ReplyPushLoop.Action.STOP, loop().decide(WORKER, 0));
+        assertEquals(ReplyPushLoop.Action.STOP, loop().decide(PRIMARY, 0, 0));
     }
 
     @Test
     void decideAtCapIsStop() {
         agents = agentWithStatus("idle");
         inbox.publish(WORKER, "m1", "hello");
-        assertEquals(ReplyPushLoop.Action.STOP, loop(2, 100).decide(WORKER, 2));
+        var loop = loop(2, 100);
+        loop.onReplyQueued(WORKER);
+        assertEquals(ReplyPushLoop.Action.STOP, loop.decide(PRIMARY, 2, 0));
     }
 
     @Test
     void decideUnderCapWithInjectablePrimaryIsInject() {
         agents = agentWithStatus("idle");
         inbox.publish(WORKER, "m1", "hello");
-        assertEquals(ReplyPushLoop.Action.INJECT, loop().decide(WORKER, 0));
+        var loop = loop();
+        loop.onReplyQueued(WORKER);
+        assertEquals(ReplyPushLoop.Action.INJECT, loop.decide(PRIMARY, 0, 0));
     }
 
     @Test
     void decideUnderCapWithBlockedPrimaryIsInject() {
         agents = agentWithStatus("blocked");
         inbox.publish(WORKER, "m1", "hello");
-        assertEquals(ReplyPushLoop.Action.INJECT, loop().decide(WORKER, 0),
+        var loop = loop();
+        loop.onReplyQueued(WORKER);
+        assertEquals(ReplyPushLoop.Action.INJECT, loop.decide(PRIMARY, 0, 0),
                 "BLOCKED is injectable");
     }
 
@@ -97,7 +116,9 @@ class ReplyPushLoopTest {
     void decideUnderCapWithDonePrimaryIsInject() {
         agents = agentWithStatus("done");
         inbox.publish(WORKER, "m1", "hello");
-        assertEquals(ReplyPushLoop.Action.INJECT, loop().decide(WORKER, 0),
+        var loop = loop();
+        loop.onReplyQueued(WORKER);
+        assertEquals(ReplyPushLoop.Action.INJECT, loop.decide(PRIMARY, 0, 0),
                 "DONE is injectable");
     }
 
@@ -105,23 +126,29 @@ class ReplyPushLoopTest {
     void decideUnderCapWithBusyPrimaryIsWaitBusy() {
         agents = agentWithStatus("working");
         inbox.publish(WORKER, "m1", "hello");
-        assertEquals(ReplyPushLoop.Action.WAIT_BUSY, loop().decide(WORKER, 0));
+        var loop = loop();
+        loop.onReplyQueued(WORKER);
+        assertEquals(ReplyPushLoop.Action.WAIT_BUSY, loop.decide(PRIMARY, 0, 0));
     }
 
     @Test
     void decideUnderCapWithUnknownPrimaryIsWaitBusy() {
         agents = agentWithStatus("unknown");
         inbox.publish(WORKER, "m1", "hello");
-        assertEquals(ReplyPushLoop.Action.WAIT_BUSY, loop().decide(WORKER, 0));
+        var loop = loop();
+        loop.onReplyQueued(WORKER);
+        assertEquals(ReplyPushLoop.Action.WAIT_BUSY, loop.decide(PRIMARY, 0, 0));
     }
 
     @Test
     void decideStopsAfterInboxIsEmptied() {
         agents = agentWithStatus("idle");
         inbox.publish(WORKER, "m1", "hello");
-        assertEquals(ReplyPushLoop.Action.INJECT, loop().decide(WORKER, 0));
+        var loop = loop();
+        loop.onReplyQueued(WORKER);
+        assertEquals(ReplyPushLoop.Action.INJECT, loop.decide(PRIMARY, 0, 0));
         inbox.ack(WORKER, "m1");
-        assertEquals(ReplyPushLoop.Action.STOP, loop().decide(WORKER, 0));
+        assertEquals(ReplyPushLoop.Action.STOP, loop.decide(PRIMARY, 0, 0));
     }
 
     // --- onReplyQueued integration -------------------------------------------------------------
@@ -201,12 +228,19 @@ class ReplyPushLoopTest {
         assertTrue(nudge.contains("bridge_poll(target=term_worker)"));
     }
 
-    // --- CB-588: async ticket terminal nudges — decideTickets() logic --------------------------
+    @Test
+    void repliesNudgeFormatIsCorrect() {
+        String multi = ReplyPushLoop.REPLIES_NUDGE_FORMAT.formatted(2, "term_worker1, term_worker2");
+        assertTrue(multi.contains("2 workers"));
+        assertTrue(multi.contains("bridge_poll(target=...)"));
+    }
+
+    // --- CB-588: async ticket terminal nudges — decide() logic on tickets -----------------------
 
     @Test
     void decideTicketsWithNothingPendingIsStop() {
         agents = agentWithStatus("idle");
-        assertEquals(ReplyPushLoop.Action.STOP, loop().decideTickets(PRIMARY, 0));
+        assertEquals(ReplyPushLoop.Action.STOP, loop().decide(PRIMARY, 0, 0));
     }
 
     @Test
@@ -214,7 +248,7 @@ class ReplyPushLoopTest {
         agents = agentWithStatus("idle");
         var loop = loop(2, 100_000);
         loop.onTicketTerminal("task-1", WORKER, false);
-        assertEquals(ReplyPushLoop.Action.STOP, loop.decideTickets(PRIMARY, 2));
+        assertEquals(ReplyPushLoop.Action.STOP, loop.decide(PRIMARY, 0, 2));
     }
 
     @Test
@@ -222,7 +256,7 @@ class ReplyPushLoopTest {
         agents = agentWithStatus("idle");
         var loop = loop(5, 100_000);
         loop.onTicketTerminal("task-1", WORKER, false);
-        assertEquals(ReplyPushLoop.Action.INJECT, loop.decideTickets(PRIMARY, 0));
+        assertEquals(ReplyPushLoop.Action.INJECT, loop.decide(PRIMARY, 0, 0));
     }
 
     @Test
@@ -230,7 +264,7 @@ class ReplyPushLoopTest {
         agents = agentWithStatus("working");
         var loop = loop(5, 100_000);
         loop.onTicketTerminal("task-1", WORKER, false);
-        assertEquals(ReplyPushLoop.Action.WAIT_BUSY, loop.decideTickets(PRIMARY, 0));
+        assertEquals(ReplyPushLoop.Action.WAIT_BUSY, loop.decide(PRIMARY, 0, 0));
     }
 
     @Test
@@ -238,7 +272,7 @@ class ReplyPushLoopTest {
         agents = agentWithStatus("idle");
         var loop = new ReplyPushLoop(new PrimaryRegistry(null), agents, inbox, scheduler, 5, 100_000);
         loop.onTicketTerminal("task-1", WORKER, false); // no lead known -> never registered as pending
-        assertEquals(ReplyPushLoop.Action.STOP, loop.decideTickets(PRIMARY, 0));
+        assertEquals(ReplyPushLoop.Action.STOP, loop.decide(PRIMARY, 0, 0));
     }
 
     // --- CB-588: onTicketTerminal integration ---------------------------------------------------
@@ -255,7 +289,7 @@ class ReplyPushLoopTest {
         String nudge = rec.sentParams().getFirst().getValue().toString();
         assertTrue(nudge.contains("task-1"), "nudge should name the ticket");
         assertTrue(nudge.contains("bridge_poll(ticket="), "nudge should name the exact ticket-poll call");
-        assertFalse(nudge.contains("bridge_poll(target="), "a ticket nudge must not tell the lead to run the target-poll call");
+        assertFalse(nudge.contains("bridge_poll(target="), "a ticket-only nudge must not tell the lead to run the target-poll call");
     }
 
     @Test
@@ -346,11 +380,11 @@ class ReplyPushLoopTest {
     void aTicketStillPendingWhenTheLoopStopsIsNotStranded() {
         // Regression for the race a reviewer found in gitea PR #73: onTicketTerminal's
         // activeLeads.putIfAbsent can see the lead's slot as still occupied a moment before
-        // decideTickets' STOP releases it, so the ticket coalesces onto a schedule that is about to
+        // decide's STOP releases it, so the ticket coalesces onto a schedule that is about to
         // die and nothing ever nudges about it. Forcing that exact thread interleaving is not
-        // reliable, so this drives stopOrRestartTicketLoop — the STOP path's own release-and-recheck —
+        // reliable, so this drives stopOrRestart — the STOP path's own release-and-recheck —
         // directly, arranging the state it must not lose a ticket in: a ticket pending for the lead
-        // that was NOT part of the pre-decision snapshot (pendingBefore=empty), standing in for one
+        // that was NOT part of the pre-decision snapshot (ticketsBefore=empty), standing in for one
         // that races in during the decision-to-release window.
         var rec = recordingClient();
         agents = new AgentControl(rec);
@@ -358,9 +392,9 @@ class ReplyPushLoopTest {
 
         loop.onTicketTerminal("task-1", WORKER, false); // pendingTickets={task-1}; activeLeads={PRIMARY}
 
-        // Stand in for the scheduler thread reaching decideTickets==STOP for this lead — with nothing
+        // Stand in for the scheduler thread reaching decide==STOP for this lead — with nothing
         // pending at decide time — while task-1 races in before the release below runs.
-        loop.stopOrRestartTicketLoop(PRIMARY, Set.of());
+        loop.stopOrRestart(PRIMARY, Set.of(), Set.of());
 
         assertTrue(loop.isActive(), "a ticket that raced the loop's stop must reclaim the schedule "
                 + "slot, not be stranded with no schedule left to ever nudge about it");
@@ -368,23 +402,67 @@ class ReplyPushLoopTest {
 
     @Test
     void aStaleUncollectedTicketAtCapDoesNotRestartTheLoop() {
-        // The other direction of the same fix: restarting on ANY non-empty pendingFor(lead) would be
+        // The other direction of the same fix: restarting on ANY non-empty pending set would be
         // wrong. When STOP is reached because the reminder cap was hit, the same never-collected
         // ticket is expected to still be there — that is the cap doing its job (acceptance criterion
-        // #7: nudges stay bounded). task-1 here was already accounted for at decide time (it is in
-        // pendingBefore), so it must not restart the loop just because it is still sitting there.
+        // #5: no spin / nudges stay bounded). task-1 here was already accounted for at decide time
+        // (it is in ticketsBefore), so it must not restart the loop just because it is still sitting
+        // there.
         var rec = recordingClient();
         agents = new AgentControl(rec);
         ReplyPushLoop loop = loop(1, 100_000);
 
         loop.onTicketTerminal("task-1", WORKER, false); // pendingTickets={task-1}; activeLeads={PRIMARY}
 
-        loop.stopOrRestartTicketLoop(PRIMARY, Set.of("task-1"));
+        loop.stopOrRestart(PRIMARY, Set.of(), Set.of("task-1"));
 
         assertFalse(loop.isActive(), "a stale ticket already accounted for at decide time must not "
                 + "restart the loop — that would defeat the reminder cap");
     }
 
+    // --- mirror of the two stopOrRestart tests above, for the reply arm ------------------------
+    //
+    // Both tests above only ever passed Set.of() for repliesBefore, so racedIn's reply branch
+    // (`pendingReplyTargetsFor(lead).stream().anyMatch(t -> !repliesBefore.contains(t))`) was
+    // never exercised by anything other than an always-empty snapshot. The reviewer flagged this:
+    // racedIn is symmetric in the code, and only half of it was pinned by a test.
+
+    @Test
+    void aReplyStillPendingWhenTheLoopStopsIsNotStranded() {
+        // Mirrors aTicketStillPendingWhenTheLoopStopsIsNotStranded: a reply target that raced in
+        // during the decision-to-release window (absent from the "before" snapshot) must reclaim
+        // the schedule slot rather than being stranded with no schedule left to nudge about it.
+        var rec = recordingClient();
+        agents = new AgentControl(rec);
+        inbox.publish(WORKER, "m1", "hello");
+        ReplyPushLoop loop = loop(1, 100_000); // long backoff — no natural tick fires during this test
+
+        loop.onReplyQueued(WORKER); // pendingReplies={term_worker}; activeLeads={PRIMARY}
+
+        loop.stopOrRestart(PRIMARY, Set.of(), Set.of());
+
+        assertTrue(loop.isActive(), "a reply that raced the loop's stop must reclaim the schedule "
+                + "slot, not be stranded with no schedule left to ever nudge about it");
+    }
+
+    @Test
+    void aStaleUncollectedReplyAtCapDoesNotRestartTheLoop() {
+        // Mirrors aStaleUncollectedTicketAtCapDoesNotRestartTheLoop: a reply target already
+        // accounted for at decide time (present in repliesBefore) must not restart the loop —
+        // that is the reminder cap doing its job, not a race.
+        var rec = recordingClient();
+        agents = new AgentControl(rec);
+        inbox.publish(WORKER, "m1", "hello");
+        ReplyPushLoop loop = loop(1, 100_000);
+
+        loop.onReplyQueued(WORKER); // pendingReplies={term_worker}; activeLeads={PRIMARY}
+
+        loop.stopOrRestart(PRIMARY, Set.of(WORKER), Set.of());
+
+        assertFalse(loop.isActive(), "a stale reply target already accounted for at decide time "
+                + "must not restart the loop — that would defeat the reminder cap");
+    }
+
     @Test
     void ticketNudgeFormatIsCorrect() {
         String single = ReplyPushLoop.TICKET_NUDGE_FORMAT.formatted("task-1", "", "task-1");
@@ -402,7 +480,103 @@ class ReplyPushLoopTest {
     void inboxNudgeStillUsesTheOriginalTargetPollCall() {
         String nudge = ReplyPushLoop.NUDGE_FORMAT.formatted(WORKER, WORKER);
         assertTrue(nudge.contains("bridge_poll(target=" + WORKER + ")"),
-                "CB-588 must not change the CB-307 inbox nudge's call shape");
+                "CB-588/CB-590 must not change the CB-307 inbox nudge's call shape");
+    }
+
+    // --- CB-590: one schedule per lead — no overlap, no lost nudges -----------------------------
+
+    @Test
+    void replyAndTicketForTheSameLeadCoalesceIntoOneSendNeverOverlapping() throws Exception {
+        var rec = recordingClient();
+        agents = new AgentControl(rec);
+        inbox.publish(WORKER, "m1", "hello");
+        var loop = loop(1, 300); // backoff wide enough that both entry points land before the first tick
+
+        loop.onReplyQueued(WORKER);
+        loop.onTicketTerminal("task-1", WORKER, false);
+
+        assertTrue(rec.sendLatch.await(3, TimeUnit.SECONDS), "one combined nudge should have been sent");
+        Thread.sleep(300);
+        assertEquals(1, rec.sendCount(),
+                "a reply and a ticket for the same lead must coalesce onto ONE schedule — "
+                        + "two nudge injections into the same lead pane must never overlap");
+        String nudge = rec.sentParams().getFirst().getValue().toString();
+        assertTrue(nudge.contains("bridge_poll(target=" + WORKER + ")"),
+                "the combined nudge must still mention the reply: " + nudge);
+        assertTrue(nudge.contains("task-1"), "the combined nudge must still mention the ticket: " + nudge);
+    }
+
+    @Test
+    void aReplyQueuedWhileTheLeadIsBusyIsNotLostWhenATicketArrivesToo() throws Exception {
+        // The lead is busy for its first two status checks, then becomes injectable. A reply is
+        // queued while busy; a ticket for the same lead arrives before the lead frees up. Neither
+        // may be dropped — deferred is fine, lost is not (acceptance criterion #2).
+        var rec = new BusyThenIdleHerdrClient(2);
+        agents = new AgentControl(rec);
+        inbox.publish(WORKER, "m1", "hello");
+        var loop = loop(1, 50); // cap=1: WAIT_BUSY doesn't count against it, so exactly one send once injectable
+
+        loop.onReplyQueued(WORKER);                     // schedule starts, first tick(s) WAIT_BUSY
+        loop.onTicketTerminal("task-1", WORKER, false);  // coalesces onto the same waiting schedule
+
+        assertTrue(rec.sendLatch.await(3, TimeUnit.SECONDS),
+                "once the lead becomes injectable, the deferred work must still be nudged");
+        Thread.sleep(200);
+        assertEquals(1, rec.sendCount(), "exactly one nudge once injectable — reply and ticket coalesced");
+        String nudge = rec.sentParams().getFirst().getValue().toString();
+        assertTrue(nudge.contains("bridge_poll(target=" + WORKER + ")"), "the reply must not be dropped: " + nudge);
+        assertTrue(nudge.contains("task-1"), "the ticket must not be dropped: " + nudge);
+    }
+
+    // --- CB-590 follow-up: per-source reminder budgets — the regression this round exists for ---
+
+    @Test
+    void oneExhaustedSourceDoesNotBlockANudgeForTheOtherSource() {
+        // The live trace this ticket was filed from: an undrained reply target got nudged up to
+        // its cap (5 reminders), then a ticket for the SAME lead went terminal shortly before the
+        // next scheduled tick — so it coalesced onto the still-active schedule (arriving BEFORE
+        // that tick's "before" snapshot, not during the decision-to-release race stopOrRestart
+        // guards). With CB-590's single shared reminder counter, that tick's decide() saw
+        // reminderCount already at the cap and returned STOP regardless of the ticket, and because
+        // the ticket was already present in that tick's "before" snapshot, stopOrRestart's
+        // racedIn check (proven correct on its own above) did not save it either — it is not a
+        // race, it looks like ordinary stale backlog. The ticket was then stranded: pending
+        // forever with no live schedule, never named in any nudge.
+        //
+        // Fixed by giving each source its own counter. Here the reply source is AT its cap (2/2)
+        // and the ticket source has NEVER been nudged (0/2) — decide() must still return INJECT,
+        // because the ticket is still eligible on its own budget.
+        agents = agentWithStatus("idle");
+        inbox.publish(WORKER, "m1", "hello");
+        var loop = loop(2, 100_000); // huge backoff — this test drives decide()/isActive() directly
+        loop.onReplyQueued(WORKER);
+        loop.onTicketTerminal("task-1", WORKER, false);
+
+        assertEquals(ReplyPushLoop.Action.INJECT, loop.decide(PRIMARY, 2, 0),
+                "the reply source is exhausted (2/2), but the ticket source has never been "
+                        + "nudged (0/2) — the lead must still be injected so the ticket is not "
+                        + "lost, exactly the CB-590 follow-up regression");
+
+        // isActive() (criterion #5): a real tick that takes the INJECT branch above never calls
+        // stopOrRestart, so the schedule started by onTicketTerminal above stays live — the
+        // ticket is not left stranded with isActive()==false while it is still pending.
+        assertTrue(loop.isActive(), "the schedule must stay active while the ticket source still "
+                + "has budget left, even though the reply source sharing it is exhausted");
+    }
+
+    @Test
+    void bothSourcesExhaustedIsStillStop() {
+        // The flip side: per-source budgets must not turn into unbounded nudging. When BOTH
+        // sources are at their cap, decide() must still STOP — a per-source budget is still a
+        // budget.
+        agents = agentWithStatus("idle");
+        inbox.publish(WORKER, "m1", "hello");
+        var loop = loop(2, 100_000);
+        loop.onReplyQueued(WORKER);
+        loop.onTicketTerminal("task-1", WORKER, false);
+
+        assertEquals(ReplyPushLoop.Action.STOP, loop.decide(PRIMARY, 2, 2),
+                "both the reply and the ticket source are at their own cap — must still stop");
     }
 
     // --- metrics (CB-512) ----------------------------------------------------------------------
@@ -430,8 +604,10 @@ class ReplyPushLoopTest {
         agents = agentWithStatus("idle");
         inbox.publish(WORKER, "m1", "hello");
         Metrics metrics = new Metrics();
+        var loop = loop(2, 100, metrics);
+        loop.onReplyQueued(WORKER);
 
-        assertEquals(ReplyPushLoop.Action.STOP, loop(2, 100, metrics).decide(WORKER, 2));
+        assertEquals(ReplyPushLoop.Action.STOP, loop.decide(PRIMARY, 2, 0));
 
         assertEquals(1, metrics.count(BridgedMetrics.PUSH_NUDGES, "outcome", "exhausted"),
                 "hitting the reminder cap must count as exhausted");
@@ -459,7 +635,7 @@ class ReplyPushLoopTest {
         var loop = loop(2, 100_000, metrics);
         loop.onTicketTerminal("task-1", WORKER, false);
 
-        assertEquals(ReplyPushLoop.Action.STOP, loop.decideTickets(PRIMARY, 2));
+        assertEquals(ReplyPushLoop.Action.STOP, loop.decide(PRIMARY, 0, 2));
 
         assertEquals(1, metrics.count(BridgedMetrics.PUSH_NUDGES, "outcome", "exhausted"),
                 "hitting the ticket reminder cap must count as exhausted");
@@ -547,4 +723,49 @@ class ReplyPushLoopTest {
     private static RecordingHerdrClient recordingClient() {
         return new RecordingHerdrClient();
     }
+
+    /**
+     * Thread-safe fake that reports {@code working} (not injectable) for its first
+     * {@code busyChecks} status calls, then {@code idle} forever after — used to prove work queued
+     * while the lead is busy is deferred, not dropped, once it becomes injectable.
+     */
+    private static final class BusyThenIdleHerdrClient implements HerdrClient {
+        private final List<Map.Entry<String, Object>> calls =
+                Collections.synchronizedList(new ArrayList<>());
+        private final AtomicInteger statusChecks = new AtomicInteger();
+        private final int busyChecks;
+        volatile CountDownLatch sendLatch = new CountDownLatch(1);
+
+        BusyThenIdleHerdrClient(int busyChecks) {
+            this.busyChecks = busyChecks;
+        }
+
+        @Override
+        public JsonNode call(String method, Object params) {
+            if ("agent.get".equals(method)) {
+                String status = statusChecks.getAndIncrement() < busyChecks ? "working" : "idle";
+                return MAPPER.createObjectNode()
+                        .set("agent", MAPPER.createObjectNode()
+                                .put("terminal_id", PRIMARY)
+                                .put("agent_status", status));
+            }
+            if ("agent.prompt".equals(method)) {
+                calls.add(Map.entry(method, params));
+                sendLatch.countDown();
+            }
+            return MAPPER.createObjectNode();
+        }
+
+        long sendCount() {
+            return calls.size();
+        }
+
+        List<Map.Entry<String, Object>> sentParams() {
+            return List.copyOf(calls);
+        }
+
+        @Override
+        public void close() {
+        }
+    }
 }

bridged/src/test/java/dev/ltms/bridged/rest/BridgedAppTest.java

@@ -18,6 +18,8 @@ import dev.ltms.bridged.session.GitWorktrees;
 import dev.ltms.bridged.session.SessionManager;
 import dev.ltms.bridged.session.Worktrees;
 import dev.ltms.bridged.member.ClaudeCodeLauncher;
+import dev.ltms.bridged.member.CompositePeerLauncher;
+import dev.ltms.bridged.placement.PlacementPolicies;
 import io.javalin.Javalin;
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.Test;
@@ -240,6 +242,43 @@ class BridgedAppTest {
         assertFalse(herdr.called("agent.start"), "an unknown profile must not spawn anything");
     }
 
+    /**
+     * CB-599: a profile at its {@code maxLoad} cap must not surface as a bare 500 — the caller
+     * needs a structured, readable reason, distinct from "unknown_profile".
+     */
+    @Test
+    void spawnAtMaxLoadIs503WithTheCapacityReasonNotABare500() throws Exception {
+        FakeHerdr herdr = new FakeHerdr();
+        BridgedConfig.Profile wcfg = new BridgedConfig.Profile(
+                "ltms-local", "http://gx00.gw:8000", "coder", null, "BRIDGED_WORKER_TOKEN", null,
+                "tab", "bridged-workers", "worker: {profile} #{n}", null,
+                null, null, null, null, null, null, null, 0, null, null, null);
+        Map<String, BridgedConfig.Profile> profiles = Map.of(wcfg.profile(), wcfg);
+        ClaudeCodeLauncher delegate = new ClaudeCodeLauncher(
+                new AgentControl(herdr), new WorkspaceControl(herdr), new SubscriptionGuard(Set.of("gx00.gw")),
+                profiles, wcfg.profile(), k -> "BRIDGED_WORKER_TOKEN".equals(k) ? "tok-abc" : null);
+        CompositePeerLauncher workers = new CompositePeerLauncher(
+                List.of(delegate), wcfg.profile(), profiles, PlacementPolicies.fixed(), _ -> 0);
+        SessionManager sessions = new SessionManager(workers, new GitWorktrees());
+        this.presence = sessions.asPresence();
+        Injector injector = new Injector(new AgentControl(herdr));
+        InMemoryReplyInbox inbox = new InMemoryReplyInbox();
+        sessions.onAcquire(inbox::own);
+        MessageService messages = new MessageService(new AgentControl(herdr), injector, new Rendezvous(), inbox);
+        app = new BridgedApp(herdr, workers, sessions, messages, this.presence, null).build().start("127.0.0.1", 0);
+        int port = app.port();
+
+        HttpResponse<String> res = req(port, "POST", "/members?profile=ltms-local");
+
+        assertEquals(503, res.statusCode(), res.body());
+        JsonNode body = mapper.readTree(res.body());
+        assertEquals("no_capacity", body.get("error").asText());
+        String detail = body.get("detail").asText();
+        assertTrue(detail.contains("ltms-local"), "detail names the profile: " + detail);
+        assertTrue(detail.contains("maxLoad"), "detail explains the refusal: " + detail);
+        assertFalse(herdr.called("agent.start"), "at cap, the spawn is refused before any herdr call");
+    }
+
     @Test
     void spawnWorkerReusesExistingWorkerSpace() throws Exception {
         // A space labelled "bridged-workers" already exists → no second workspace.create.

deploy/dev.ltms.bridged.plist

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <!--
-  CB-504 — launchd agent for bridged (macOS).
+  CB-504 / CB-594 — launchd agent for bridged (macOS).
 
   This is the real supervision target today: the dogfooded daemon runs on macOS, where there is
   no systemd. A systemd unit ships alongside (deploy/bridged.service) for the Linux gateways
@@ -9,14 +9,33 @@
 
   Install:
     cp deploy/dev.ltms.bridged.plist ~/Library/LaunchAgents/
-    # edit the paths + JAVA_HOME below to match this host, then:
     launchctl load -w ~/Library/LaunchAgents/dev.ltms.bridged.plist
     launchctl list | grep bridged
 
+  The paths below are already filled in for this host (resolved 2026-08-16 from
+  `/usr/libexec/java_home`... except that reported the system Applet-plugin JVM, not the jenv-
+  managed JDK 25 actually used to build/run bridged, so JAVA_HOME here is the real one:
+  `JENV_VERSION=25.0.3 java -XshowSettings:properties -version 2>&1 | grep java.home`; `which mvn`;
+  `echo $HOME`). If this file is copied to a different host, re-resolve all three paths and check
+  no placeholder path is left behind; scripts/redeploy-bridged.sh's check mode does not (and
+  cannot) check this file for you.
+
+  CB-594 — launchd cannot run a login shell (see the PATH comment on EnvironmentVariables below,
+  and scripts/bridged-launchd-wrapper.sh for the fix): ProgramArguments below execs THAT wrapper,
+  not java directly, so WORKER_GITEA_TOKEN and AI_GATEWAY_TOKEN still get sourced from
+  ${SHARED_ENV}/tools/secrets.sh even though launchd itself never sources anything.
+
   Note on ordering: launchd has no "start after herdr" primitive for user agents, and neither
   does systemd in a way that survives a socket appearing late. bridged retries the herdr socket
   on startup instead, so an agent that comes up before herdr converges rather than dying — that
   retry is the actual fix; KeepAlive below is the backstop.
+
+  CB-594 — KeepAlive vs. scripts/redeploy-bridged.sh: a bare SIGTERM makes this JVM exit 143 even
+  with its shutdown hook running to completion (measured, see the CB-594 report), which
+  SuccessfulExit:false below reads as a crash and races to restart the OLD jar. The redeploy
+  script now detects a loaded agent and uses `launchctl unload`/`load` instead of a raw kill, so
+  only one supervisor ever touches the process at a time — read that script's own output on a
+  redeploy for the confirmation.
 -->
 <plist version="1.0">
 <dict>
@@ -25,22 +44,23 @@
 
     <key>ProgramArguments</key>
     <array>
-        <string>/Users/CHANGEME/Tool/jdk-25.0.2.jdk/Contents/Home/bin/java</string>
+        <string>/Users/dai.ha/LTMS/claude-bridge/scripts/bridged-launchd-wrapper.sh</string>
+        <string>/Users/dai.ha/Softwares/jdks/jdk-25.0.3.jdk/Contents/Home/bin/java</string>
         <string>-jar</string>
-        <string>/Users/CHANGEME/src/claude-bridge/bridged/target/bridged.jar</string>
+        <string>/Users/dai.ha/LTMS/claude-bridge/bridged/target/bridged.jar</string>
         <string>bridged.yaml</string>
     </array>
 
     <!-- Config path in ProgramArguments is relative, so the working directory must be the module. -->
     <key>WorkingDirectory</key>
-    <string>/Users/CHANGEME/src/claude-bridge/bridged</string>
+    <string>/Users/dai.ha/LTMS/claude-bridge/bridged</string>
 
     <key>EnvironmentVariables</key>
     <dict>
         <key>JAVA_HOME</key>
-        <string>/Users/CHANGEME/Tool/jdk-25.0.2.jdk/Contents/Home</string>
+        <string>/Users/dai.ha/Softwares/jdks/jdk-25.0.3.jdk/Contents/Home</string>
         <key>HERDR_SOCKET_PATH</key>
-        <string>/Users/CHANGEME/.config/herdr/herdr.sock</string>
+        <string>/Users/dai.ha/.config/herdr/herdr.sock</string>
         <!--
           PATH matters more than it looks (CB-511): bridged propagates its own PATH to every worker
           it spawns, so this line decides whether the fleet can run a build at all. launchd does NOT
@@ -48,11 +68,14 @@
           bare /usr/bin:/bin and no JDK or Maven. Keep the toolchain entries first.
         -->
         <key>PATH</key>
-        <string>/Users/CHANGEME/Tool/jdk-25.0.2.jdk/Contents/Home/bin:/Users/CHANGEME/Tool/apache-maven-3.9.16/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+        <string>/Users/dai.ha/Softwares/jdks/jdk-25.0.3.jdk/Contents/Home/bin:/Users/dai.ha/Softwares/apache-maven/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
         <!--
-          Worker/API tokens are NOT set here: this file is committed. Export them from a private
-          launchd override or a wrapper script. bridged reads the API token from the env var named
-          by auth.tokenEnv (default BRIDGED_API_TOKEN) and only in auth.mode: token.
+          Worker/API tokens are NOT set here: this file is committed. CB-594 —
+          scripts/bridged-launchd-wrapper.sh (named in ProgramArguments above) is what supplies
+          them, by execing a login shell that sources ${SHARED_ENV}/tools/secrets.sh before the
+          daemon itself starts. bridged also reads the API token from the env var named by
+          auth.tokenEnv (default BRIDGED_API_TOKEN) and only in auth.mode: token — the wrapper
+          covers that one too, since it is the same login shell.
         -->
     </dict>
 
@@ -69,10 +92,17 @@
     <key>ThrottleInterval</key>
     <integer>10</integer>
 
+    <!--
+      CB-594 — same file scripts/redeploy-bridged.sh already tails ($BRIDGED/bridged.out), and both
+      streams point at it, not two separate log files: the script's fresh-line / ERROR-count checks
+      after a restart read this one path regardless of whether launchd or the script started the
+      process, and a stdout/stderr split would make half of what happens during a launchd-driven
+      restart invisible to it.
+    -->
     <key>StandardOutPath</key>
-    <string>/Users/CHANGEME/src/claude-bridge/bridged/logs/bridged.out.log</string>
+    <string>/Users/dai.ha/LTMS/claude-bridge/bridged/bridged.out</string>
     <key>StandardErrorPath</key>
-    <string>/Users/CHANGEME/src/claude-bridge/bridged/logs/bridged.err.log</string>
+    <string>/Users/dai.ha/LTMS/claude-bridge/bridged/bridged.out</string>
 
     <key>ProcessType</key>
     <string>Background</string>

docs/CB-591-Gateway-Migration.md

@@ -0,0 +1,467 @@
+# CB-591 — move the fleet onto the LLM and MCP gateway
+
+**Status: DONE — the fleet is on the gateway as of 2026-08-15.** `local` runs on `/anthropic` and
+`gx` on `/v1`, both at `weight: 100`; `local-direct` stays at `weight: 0` as the escape hatch. Getting
+here took a revert and two upstream fixes — see §7.1, which is the useful part of this document. One
+risk is **accepted rather than solved**: a stream cut by any mid-response timer arrives as HTTP 200
+with no terminator, and our third-party members cannot detect it (§7.2).
+· **Upstream:** [systems/vms wiki → LLM and MCP Gateway](https://git.ltms.dev/systems/vms/wiki/LLM-and-MCP-Gateway)
+· **Upstream issue:** [systems/vms#31](https://git.ltms.dev/systems/vms/issues/31)
+
+The gateway went live on 2026-08-15 and replaced Bifrost. This plan says what that means for a
+**member definition** in `bridged.yaml`, because that is the part of this repo the change actually
+touches.
+
+---
+
+## 1. What changed upstream
+
+One front door for every LLM and MCP client: `https://llm.ltms.dev`, one token per consumer.
+
+| Surface | URL |
+|---|---|
+| OpenAI chat | `https://llm.ltms.dev/v1/chat/completions` |
+| OpenAI models | `https://llm.ltms.dev/v1/models` |
+| **Anthropic messages** | `https://llm.ltms.dev/anthropic/v1/messages` |
+| MCP, all servers multiplexed | `https://llm.ltms.dev/mcp` |
+
+Anything outside that list returns **404 before any token is checked**, on purpose — the gateway must
+never become a blanket proxy.
+
+The model backend is unchanged: GX10 vLLM at `10.10.10.26:8000` (`gx00.gw`), model name exactly
+`deepseek-v4-flash`. The direct LAN path stays open on purpose as an escape hatch.
+
+---
+
+## 2. Where claude-bridge sits today
+
+We do **not** use the gateway. The `local` profile talks straight to the vLLM:
+
+```yaml
+local:
+  kind: claude-code
+  baseUrl: http://gx00.gw:8000     # direct vLLM — no auth, LAN only
+  model: deepseek-v4-flash
+  configDir: /Users/dai.ha/.ccs/instances/gx10
+```
+
+Three facts about our side that decide the shape of this work:
+
+1. **`baseUrl` becomes `ANTHROPIC_BASE_URL`** in the member's environment, and `tokenEnv` becomes
+   `ANTHROPIC_AUTH_TOKEN` (the value is read from a host env var and never stored in config).
+   `local` sets no `tokenEnv` today, because a direct vLLM needs no token.
+2. **`SubscriptionGuard` refuses any host not on an allowlist**, and that allowlist is
+   `guard.offSubscriptionHosts: [gx00.gw]`. It is built once in `Bridged.java:93` and handed to the
+   launcher, so **it is a restart-required key**, not a hot one. Changing `baseUrl` without changing
+   this makes every `local` spawn throw.
+3. **The wiki names us as a blocker.** Under *Not done yet*: retiring the shared `legacy` token is
+   blocked because "kb, brain, **claude-bridge** and the workstation still share it. Each needs its
+   own consumer first."
+
+Context7 is mounted twice today, both times straight at `https://ct7.ltms.dev/mcp` — once in
+`.mcp.json` (the primary) and once in `opencode.json` (the `sol` and `terra` members).
+
+```mermaid
+flowchart LR
+    subgraph now["Today"]
+        M1["local member<br/>claude-code"] -->|"ANTHROPIC_BASE_URL"| V1["vLLM gx00.gw:8000<br/>no auth, LAN only"]
+        M2["sol / terra<br/>opencode"] --> CT1["ct7.ltms.dev/mcp"]
+        P1["primary"] --> CT1
+    end
+    subgraph after["Proposed"]
+        M3["local member"] -->|"ANTHROPIC_BASE_URL<br/>+ ANTHROPIC_AUTH_TOKEN"| G["llm.ltms.dev/anthropic<br/>consumer: claude-bridge"]
+        G --> V2["vLLM gx00.gw:8000"]
+        M4["local-direct<br/>weight 0, escape hatch"] --> V2
+    end
+```
+
+*The member definition is the only thing that moves. The model behind it does not.*
+
+---
+
+## 3. The member definition change
+
+The gateway serves an Anthropic surface *and* an OpenAI surface, so **both member kinds can point at
+it**. That is the main opportunity here, and it is bigger than the `local` profile alone.
+
+### 3a. `local` — claude-code, on `/anthropic`
+
+| Key | Today | After | Note |
+|---|---|---|---|
+| `baseUrl` | `http://gx00.gw:8000` | `https://llm.ltms.dev/anthropic` | see the schema warning below |
+| `tokenEnv` | *(unset)* | `AI_GATEWAY_TOKEN` | new consumer token, `llmk-claude-bridge-<32 hex>` |
+| `model` | `deepseek-v4-flash` | unchanged | must stay **exact**; a regex match returns an empty `/v1/models` while completions keep working |
+| `guard.offSubscriptionHosts` | `[gx00.gw]` | `[gx00.gw, llm.ltms.dev]` | **restart required** |
+
+### 3b. A new opencode profile on `/v1` — no code needed
+
+`OpenCodeLauncher` already supports a pinned OpenAI-compatible endpoint (CB-508). Given `baseUrl` it
+writes a custom provider block into the worker's opencode config:
+
+- `baseUrl` → `options.baseURL`. `openAiBaseUrl` appends `/v1` to a bare host, and takes a URL that
+  already has a path **as-is** — so `https://llm.ltms.dev/v1` works unchanged.
+- `tokenEnv` → `options.apiKey` (falls back to a placeholder when unset, since a local vLLM ignores it).
+- `model:` **must** be `<provider>/<model>` when `baseUrl` is set — a bare name is rejected loudly
+  rather than silently falling back to opencode's default gateway.
+
+So the profile is pure config:
+
+```yaml
+gx:
+  kind: opencode
+  baseUrl: https://llm.ltms.dev/v1
+  tokenEnv: AI_GATEWAY_TOKEN
+  model: gx/deepseek-v4-flash        # provider id is ours to choose; the half after / is the model
+  argv: ["opencode"]
+  mcpUrl: http://127.0.0.1:8765/mcp
+  gitTokenEnv: WORKER_GITEA_TOKEN
+  weight: 100                        # same tier as `local` — free
+  maxLoad: 2
+  # deliberately NO credentialId — this is our own box, not the shared OpenAI account
+```
+
+**Why this matters more than it looks.** Today every opencode member is `sol` or `terra`, and those
+are two models on **one** OpenAI account sharing `credentialId: openai-shared` — so an exhaustion on
+either locks out both, and half the fleet's opencode capacity dies at once. A gateway-backed opencode
+profile is free, is not on that credential, and therefore is not in that quarantine pair. It removes
+a single point of failure rather than just adding capacity.
+
+**Note the asymmetry, it is deliberate:** `SubscriptionGuard` does not apply to opencode at all — the
+guard exists to stop a *Claude* worker borrowing the operator's subscription, and opencode reads its
+own provider credentials. So 3b needs **no allowlist change**; only 3a does.
+
+**Both still need a restart, for a different reason.** `tokenEnv` is resolved by
+`HerdrPeerLauncher.resolveEnv` → `env.apply(name)`, which reads the **daemon's own process
+environment**. The running `bridged` inherited its environment when it started, so a variable added to
+`secrets.sh` afterwards is simply not there — the launcher would inject an empty token and the
+gateway would answer 401. This is the same failure as trap 1 in `scripts/redeploy-bridged.sh`
+(`WORKER_GITEA_TOKEN`), and it has the same fix: **restart from a login shell**, and use
+`scripts/redeploy-bridged.sh --check` to confirm the name resolves before restarting anything.
+
+### 3c. What this does to `ccs`
+
+Once a profile carries `baseUrl`, `tokenEnv` and `model` itself, the ccs instance stops being what
+routes a member. Be precise about what is left, though: `configDir` still supplies **folder trust**
+and `settings.json`, and dropping it is what produced the trust dialog and the wrong-model error
+recorded in `bridged.yaml`. So ccs goes from *deciding where the tokens go* to *holding client-side
+state*. Less load-bearing, not removable.
+
+### Why `/anthropic` and never `/v1/chat/completions`
+
+The gateway declares its Anthropic backend as `schema.name: Anthropic`, which means **no
+translation** — streaming, tool use and thinking blocks pass through exactly as they do against vLLM
+directly.
+
+Declared as `OpenAI`, Envoy's translator looks for a `thinking_blocks` field that our vLLM does not
+send (it sends `reasoning_content`), and **every thinking delta disappears silently**. Claude Code
+speaks the Anthropic protocol, so `/anthropic` is both correct and the only safe choice.
+
+This is the exact failure shape this repo keeps hitting: it compiles, it answers, it looks healthy,
+and a capability is quietly off. Treat it as a `silent-default` risk, not a config preference.
+
+**Open question for 3b — ANSWERED, 2026-08-15.** The worry was that the OpenAI surface might drop
+reasoning the way the wiki documents for a mis-declared Anthropic backend. It does not. Checked at
+the API before any profile was switched:
+
+| surface | request | result |
+|---|---|---|
+| `/anthropic/v1/messages` | `deepseek-v4-flash`, 64 tokens | 200, response carries a real `"type":"thinking"` block |
+| `/v1/chat/completions` | same | 200, message carries a populated `reasoning_content` (and a `reasoning` field) |
+| `/v1/models` | — | 200, exactly `["deepseek-v4-flash"]` — the exact-name trap is clear |
+| `/v1/models`, **no token** | — | **401** — Caddy is gating, as designed |
+
+So reasoning survives on **both** surfaces, and the `/anthropic` choice for `local` is about protocol
+correctness rather than a repair for a known loss. The last row matters on its own: the wiki warns
+the gateway's own `SecurityPolicy` fails open, so it is worth knowing the proxy in front really does
+refuse an unauthenticated request here.
+
+---
+
+## 4. Decisions
+
+### D1 — switch, but keep the direct path as an explicit profile · **recommended**
+
+Switching buys four things we do not have:
+
+- **Free opencode capacity, off the shared credential.** The largest single win. See §3b — it retires
+  a real single point of failure, not just a cost line.
+- **Per-consumer usage figures.** The cockpit counts requests per consumer. That is the first real
+  measurement of what the fleet consumes, and it feeds [CB-589](https://git.ltms.dev/lms/claude-bridge/issues/74) Gap 2 directly.
+- **Our own revocable token.** One consumer to revoke if a worker ever leaks it, instead of a shared
+  `legacy` token used by four systems.
+- **It works off-LAN.** `gx00.gw` resolves on the LAN only.
+
+The cost is honest and worth stating: we add a TLS edge, an auth proxy and a gateway to the path of
+every member spawn. The wiki keeps the direct route open precisely because "if the gateway breaks,
+nothing that matters is blocked."
+
+So keep it. Add a second profile `local-direct` pointing at `http://gx00.gw:8000` with **`weight: 0`**
+— never auto-selected, still spawnable with an explicit `bridge_spawn{profile: "local-direct"}`.
+That is exactly what CB-554 made `weight: 0` mean, and it turns the escape hatch into something the
+lead can actually reach during an incident.
+
+### D2 — do members also mount the gateway's `/mcp`? · **OPEN, operator's call**
+
+Not a detail. `CLAUDE.md` states in two places that a member mounts **only** the bridge MCP, and a
+worker's honesty rule leans on it ("never claim the result of a check you had no way to run").
+
+- **Keep bridge-only.** The invariant stays true and simple. Workers stay cheap and narrow.
+- **Add the gateway MCP.** Implementers get context7 documentation lookups, which is genuinely useful
+  for library work. But `mcpUrl` in `BridgedConfig.Profile` is a **single `String`**, so a
+  claude-code member can mount exactly one MCP — this needs a code change, not a config edit.
+
+Note the invariant is **already inaccurate**: `opencode.json` gives `sol` and `terra` both context7
+and gitea. So the choice is really "make the rule true" or "make the rule match reality". Either is
+defensible; picking one is not mine to do.
+
+### D3 — token scope
+
+One consumer, `claude-bridge`, its token in `${SHARED_ENV}/tools/secrets.sh` as `AI_GATEWAY_TOKEN`,
+referenced by name only. Never the literal value in `bridged.yaml` — `tokenEnv` exists for this.
+
+---
+
+## 5. Units of work
+
+```mermaid
+flowchart TB
+    U1["U1 · consumer token<br/>issue via cockpit, add to secrets.sh"]
+    U2["U2 · profile + guard<br/>bridged.yaml, restart"]
+    U3["U3 · verify live<br/>spawn, prove thinking survives"]
+    U4["U4 · context7 via gateway<br/>.mcp.json + opencode.json"]
+    U5["U5 · docs<br/>CLAUDE.md, wiki 11-Features"]
+    U1 --> U2 --> U3
+    U4 --> U5
+    U3 --> U5
+```
+
+| # | Scope | Who | Why |
+|---|---|---|---|
+| U1 | Issue the `claude-bridge` consumer at `auth.ltms.dev`; store as `AI_GATEWAY_TOKEN` | **operator** | touches secrets and a host we do not own |
+| U2a | New `gx` opencode profile on `/v1` — pure config, no guard change | **lead** | `bridged.yaml` is gitignored, so a worker cannot see or edit it |
+| U2b | `local` → `/anthropic`; add `local-direct` weight 0; add `llm.ltms.dev` to the guard allowlist | **lead** | same |
+| U2c | One restart from a **login shell**, after U2a and U2b | **lead** | picks up `AI_GATEWAY_TOKEN` into the daemon env *and* the guard allowlist, in one stop |
+| U3 | Live spawn on both new profiles; confirm reasoning survives on each surface | **lead** | needs real spawns and the running daemon |
+| U4 | Point `.mcp.json` and `opencode.json` context7 at the gateway `/mcp`; rename pinned tools | delegatable | tracked files, self-contained |
+| U5 | Fix the "members mount only the bridge" claim; add a `wiki/11-Features.md` entry | delegatable | writing, clear criteria |
+
+U1 blocks U2a, U2b and U3. U4 and U5 do not depend on it.
+
+**Write U2a and U2b, then restart once (U2c), then verify `gx` before `local`.** Since both profiles
+need the same restart there is no reason to do two, but there is still a reason to *verify* in order:
+`gx` exercises the token and the gateway with no guard involved, so if it fails the cause is upstream.
+`local` adds the guard allowlist on top, so a failure there points at our config instead. Testing them
+in that order separates the two causes instead of confusing them.
+
+> **U1 status, 2026-08-15:** the operator issued the consumer and exported it as `AI_GATEWAY_TOKEN`
+> (one key for every agent and MCP client behind `llm.ltms.dev`). Confirmed: it resolves in a login
+> shell, is 48 characters and carries the documented `llmk-` prefix. The value was never printed.
+
+---
+
+## 6. Traps carried over from the wiki
+
+Each of these cost someone real debugging time upstream. They apply to us.
+
+1. **Rotating a token restarts the auth proxy, which drops in-flight streaming responses.** For us
+   that means rotating `AI_GATEWAY_TOKEN` kills every live member mid-turn, and an async ticket's
+   report goes with it. This is the same rule as a daemon redeploy: **drain the fleet first**
+   (`bridge_list` → `bridge_poll` anything wanted → `bridge_stop`), then rotate.
+2. **The gateway's own `SecurityPolicy` fails open.** Standalone `aigw run` accepts it and silently
+   ignores it — an unauthenticated request returned **200**. Auth is the Caddy proxy in front, and
+   nothing else. Never reason as if the gateway authenticates.
+3. **Exact model name.** A regex match routes fine but returns an **empty** `/v1/models` list while
+   completions keep working. A wrong name returns a bare 404 that reads exactly like a dead gateway.
+4. **MCP tool names changed prefix separator.** Bifrost used one dash (`ct7-resolve-library-id`); the
+   gateway uses **two underscores** (`ct7__resolve-library-id`). Relevant only if U4 is done.
+5. **`/v1/models` 404 vs empty list are different faults.** 404 means no route loaded at all; empty
+   means the model match is a regex. Do not conflate them when diagnosing.
+
+---
+
+## 7. Verification — what would prove this works
+
+Merging config is not proving it. The checks, in order:
+
+1. `bridge_spawn{profile: "gx"}` succeeds and the member completes a real turn ending in
+   `bridge_reply`. This is the first proof of the token, the URL and the model name, and it risks
+   nothing the fleet depends on.
+2. `bridge_spawn{profile: "local"}` succeeds. If the guard allowlist was missed, this **throws** — a
+   loud, self-correcting failure, which is the good kind. If the restart was missed, it also throws,
+   for the same reason.
+3. A `local` member completes a turn. That exercises streaming through two TLS edges, the auth proxy
+   and the gateway.
+4. **Reasoning survives, checked separately on each surface.** For `local` on `/anthropic` this is
+   the check that catches the `/v1` versus `/anthropic` mistake, and it is the only one that does —
+   nothing else distinguishes a working passthrough from a translator quietly dropping thinking
+   deltas. For `gx` on `/v1`, this answers the open question in §3 rather than assuming it.
+5. The cockpit at `auth.ltms.dev` shows requests counted against the `claude-bridge` consumer, not
+   `legacy`. That is the whole point of taking our own token.
+6. `bridge_spawn{profile: "local-direct"}` still works, so the escape hatch is real rather than
+   theoretical.
+7. `bridge_list` shows `gx` carrying no `credentialId`, so a `sol`/`terra` exhaustion cannot
+   quarantine it. This is the single-point-of-failure claim in §3b, checked rather than asserted.
+
+---
+
+## 7.1 What the live run actually found — 2026-08-15
+
+U1–U2c were done, the daemon restarted onto them, and both new profiles were spawned for real. The
+migration was then **reverted**. This section is the result, so none of it has to be re-derived.
+
+### The blocker
+
+`llm.ltms.dev` answers **HTTP 413 Request Entity Too Large** above **32 KiB (32768 bytes)**, on both
+surfaces:
+
+```
+/v1        32695 bytes -> 200        /anthropic  32095 bytes -> 200
+/v1        32795 bytes -> 413        /anthropic  32855 bytes -> 413
+```
+
+32 KiB is far below one real agent turn.
+
+**Root cause — confirmed by the systems/vms side, 2026-08-15.** My guess that it was a Caddy
+`request_body max_size` was **wrong**. It is Envoy, inside `aigw` on `llm.vm`. Envoy Gateway defaults
+a listener's `per_connection_buffer_limit_bytes` to **32768**, and the AI Gateway buffers the *whole*
+request body before it can route on the model name — so that default is not a network tuning knob
+here, it is a hard ceiling on prompt size. Read out of the live Envoy `config_dump`:
+
+```
+listener default/llm/http    per_connection_buffer_limit_bytes: 32768
+```
+
+Nobody chose 32 KiB; it was inherited from the default. Both TLS edges are innocent: the same
+boundary reproduces on the LAN path and the internet path, and both 413s carry an `x-llm-consumer`
+header their auth proxy sets only *after* authenticating — so the body cleared both edges and the
+auth. Directly on `llm.vm`, `aigw` 413s at 39 KB while the vLLM backend accepts the same 39 KB and
+answers 200.
+
+**Do not plan around 32 KiB.** The intended ceiling is far higher. Their fix — a `ClientTrafficPolicy`
+setting `bufferLimit: 8Mi` — is written but **not deployed** as of this note, pending their operator's
+approval. I have not re-tested and will not until they confirm, so as not to measure a half-changed
+system. Fixed in **systems/vms**, not here.
+
+### The part worth remembering
+
+Two members were spawned at the same moment with the same message:
+
+| | `local` (claude-code, `/anthropic`) | `gx` (opencode, `/v1`) |
+|---|---|---|
+| READY → BUSY | 19:07:26 | 19:07:45 |
+| BUSY → DONE | **19:08:51 (66s)** | **never — 10+ min, ticket FAILED** |
+
+**`local` passed.** It passed only because the probe was three trivial questions in a fresh session,
+so the request fit under 32 KiB. The profile looked healthy and was a landmine set to fire on the
+first turn that reads a file.
+
+So §7's checklist was not wrong, it was **too easy**. Any future run of it must use a task that reads
+a real file. A liveness probe proves the token and the URL; it does not prove the path.
+
+`gx` did not fail loudly either. Reproduced outside the bridge by running `opencode` by hand with the
+launcher's own generated config:
+
+```
+Error: Request Entity Too Large
+...compacts context, retries...
+Error: Request Entity Too Large
+```
+
+opencode **catches the 413, compacts, and retries — indefinitely**. A member that fails loudly costs
+one turn; this one costs the whole task and is indistinguishable from a slow worker.
+
+> **Diagnosing a stuck opencode member.** Do not read its pane. The launcher writes its config to a
+> temp dir and passes it as `OPENCODE_CONFIG` — find it with
+> `ls -dt /var/folders/*/*/T/bridged-opencode-* | head -1`, check the provider block and the key's
+> length and prefix (never its value), then reproduce with `opencode run --auto -m <provider>/<model>`
+> using the same `OPENCODE_CONFIG`. That is what turned "it hangs" into a one-line error.
+
+### What checked out, and needs no re-testing
+
+- Token accepted on both surfaces. **Unauthenticated → 401**, so the Caddy proxy really does gate —
+  the wiki's "SecurityPolicy fails open" warning is about the gateway itself, not the edge.
+- `/v1/models` returns exactly `["deepseek-v4-flash"]`, so trap 3 is clear.
+- **Reasoning survives both surfaces** — see §3b above.
+- The launcher's generated opencode provider block is correct, carrying a real 48-character `llmk-`
+  key rather than the `bridged-local-noauth` placeholder.
+- `SubscriptionGuard` accepted `llm.ltms.dev` after the allowlist edit and the restart: `local`
+  spawned without throwing, which is the check that catches a missed restart.
+
+### Resolution — both ceilings fixed, migration completed
+
+systems/vms fixed both, and each was re-checked from this side rather than taken on trust:
+
+| ceiling | was | now | our own check |
+|---|---|---|---|
+| listener buffer | 32 KiB | 32 Mi | 1.2 MB body → **200** (was 413) |
+| LLM route timeout | 60s | 86400s | the request that truncated: **101s, `message_stop` present, 4000/4000** |
+
+The timeout moved in two steps on 2026-08-15: 60s → 1800s, then 1800s → **86400s (24 hours)** after
+the truncation risk below was discussed. They tried `request: 0s` first, which removes the
+total-duration timer completely. It works, but on an `AIGatewayRoute` the **idle timeout is derived
+from the request timeout**, so `0s` also removed any bound on a stalled connection. 86400s keeps a
+reaper for dead connections while putting the truncation timer out of practical reach.
+
+Neither was deliberate. The 32 KiB was Envoy Gateway's default `per_connection_buffer_limit_bytes`;
+the 60s was Envoy AI Gateway's own documented default. The 60s bounded **generation** as well as
+prompt size — a tiny prompt with a long answer returned 504 at 60.05s.
+
+Two configuration facts worth keeping, from their bisection:
+
+- **`ClientTrafficPolicy` is honoured in standalone `aigw run`; `BackendTrafficPolicy` is NOT.** A
+  `BackendTrafficPolicy` setting `requestTimeout` is accepted, logs nothing, and leaves the routes
+  unchanged (upstream `envoyproxy/gateway#9513`). What works is `timeouts: {request: …}` on each
+  `AIGatewayRoute` rule. Nothing from the outside distinguishes the two — the same silent-default
+  shape as their `SecurityPolicy` caveat.
+- In that stack, "the config was accepted" proves nothing. Read the live `config_dump`.
+
+## 7.2 The risk we accepted, and why we could not remove it
+
+Raising the timeout made the failure **rare, not impossible**, and the residual failure is silent.
+
+On a mid-response timeout over chunked HTTP/1.1, Envoy ends the chunked encoding *cleanly* instead of
+resetting the connection, so the client receives what looks like a complete transfer
+(`envoyproxy/envoy#17186` — acknowledged as a bug in 2021, closed by a stale bot, never fixed). The
+December 2025 fix `envoyproxy/envoy#42269` changes locally-originated resets from `NO_ERROR` to
+`INTERNAL_ERROR`, but it is **HTTP/2 only** and SSE clients here speak HTTP/1.1.
+
+Measured on our side while the timeout was still 60s:
+
+```
+HTTP 200   61.07s   141992 bytes
+  message_stop 0    message_delta 0    error events 0
+  emitted 2473 of 4000, ending on a WELL-FORMED SSE frame
+```
+
+A syntactically valid stream that simply stops. Any timer firing mid-stream — route timeout, idle
+timeout, `max_stream_duration` — fails this same way.
+
+**The recommended defence does not transfer to us.** The right fix is to treat a stream with no
+`message_stop` / `[DONE]` / `finish_reason` as failed. We cannot: our members are Claude Code and
+opencode, third-party clients whose SSE parsing we do not own, and there is no seam to insert the
+check. Whether either detects a missing terminator is unverified — and opencode's handling of the 413
+(swallow, compact, retry forever, never surface an error) does not suggest it is strict.
+
+So the honest statement of our position:
+
+> Gateway traffic is acceptable at 86400s because a single request would have to run for 24 hours to
+> trip the bug — **not** because we could detect it if it did.
+
+At 86400s our **own** limit binds first, which is the ordering we want. `MessageService.ASYNC_TIMEOUT_MS`
+caps a turn at 30 minutes, so a runaway request ends as a clean `FAILED` ticket that we raised, rather
+than as a silently truncated `200` that we cannot see. While the gateway sat at 1800s the two numbers
+were equal and did not nest, so a gateway-side stall could have been misread as a bug in our own ticket
+handling. That ambiguity is now gone.
+
+**If a member ever returns a confident but truncated answer, suspect this before anything in our own
+code.** That is the whole reason this section exists.
+
+---
+
+## 8. Related
+
+- [CB-589 / #74](https://git.ltms.dev/lms/claude-bridge/issues/74) — cost-first placement and a
+  gateway that reports live capacity. The per-consumer figures this migration unlocks are the first
+  input that ticket actually needs.
+- `docs/CB-500-Multi-Tier-Coordination.md` §11 — the distributed-sandbox topology this gateway is
+  part of.

opencode.json

@@ -26,7 +26,7 @@
       ],
       "enabled": true,
       "environment": {
-        "GITEA_ACCESS_TOKEN": "{env:GITEA_ACCESS_TOKEN}",
+        "GITEA_ACCESS_TOKEN": "{env:WORKER_GITEA_TOKEN}",
         "GITEA_HOST": "{env:GITEA_HOST}"
       }
     }

scripts/bridged-launchd-wrapper.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+#
+# CB-594 — the only reason this file exists: launchd does not run a login shell.
+#
+# WORKER_GITEA_TOKEN and AI_GATEWAY_TOKEN live in ${SHARED_ENV}/tools/secrets.sh, sourced only by a
+# LOGIN shell (.zprofile/.zshrc etc). launchd execs a job's ProgramArguments directly — no shell, no
+# profile, nothing sourced (the plist's own PATH comment documents the same gap one variable over).
+# A daemon started that way boots fine and looks healthy; the failure is invisible until a worker
+# tries to open a PR (WORKER_GITEA_TOKEN empty) or a gateway profile gets a 401 (AI_GATEWAY_TOKEN
+# empty) — hours later, with nothing tying the two together (CB-591, CLAUDE.md "Redeploying the
+# daemon"). Bridged now also logs which required secret names resolved at startup (see
+# Bridged.reportRequiredSecrets), but that log line can only tell the truth if the tokens had a
+# chance to be sourced in the first place — which is this script's entire job.
+#
+# So: launchd execs THIS script instead of java directly. This script execs a login shell
+# ('zsh -l'), which sources secrets.sh, and that shell execs the real command in its place — one
+# process throughout (exec, not a subshell fork), so launchd's PID tracking, KeepAlive, and
+# StandardOut/ErrorPath all still see the one process they expect.
+#
+# The plist passes the full command as THIS script's own arguments, e.g.:
+#   ProgramArguments = [ .../bridged-launchd-wrapper.sh, /path/to/java, -jar, /path/to/bridged.jar,
+#                        bridged.yaml ]
+# so the wrapper stays generic and the actual command lives in exactly one place (the plist), not
+# duplicated here.
+set -euo pipefail
+
+if [ "$#" -eq 0 ]; then
+  echo "bridged-launchd-wrapper.sh: no command given — check the plist's ProgramArguments" >&2
+  exit 2
+fi
+
+exec /bin/zsh -lc 'exec "$@"' -- "$@"

scripts/redeploy-bridged.sh

@@ -5,11 +5,14 @@
 # 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 five remembered traps into one auditable command:
+# This script exists to turn six 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 WORKER_GITEA_TOKEN is empty and workers cannot
-#      open a PR. Nothing in the daemon logs this, so the script checks it and says so out loud.
+#   2. The daemon must start from a LOGIN shell, or the tokens it hands to members are empty:
+#      WORKER_GITEA_TOKEN (workers cannot open a PR) and AI_GATEWAY_TOKEN (401 at llm.ltms.dev).
+#      Both are read from the DAEMON's own environment at spawn time, so a value added to
+#      secrets.sh after startup is absent. Nothing logs this here, so the script checks and says
+#      so — and since CB-594, bridged's own startup log says so too, by env var name.
 #   3. An old daemon that never actually died looks identical from the outside, so the script waits
 #      for the process to exit and for the port to free before it starts a new one.
 #   4. "It started" is not "it works": the script polls /healthz until it answers, and reports the
@@ -17,6 +20,13 @@
 #      mismatch.
 #   5. Restarting under live members drops their tickets, so the script refuses unless you confirm
 #      the fleet is drained.
+#   6. CB-594 — the launchd agent (deploy/dev.ltms.bridged.plist), if installed and loaded, is a
+#      SECOND supervisor: its KeepAlive.SuccessfulExit=false restarts the daemon on any nonzero
+#      exit, and a bare SIGTERM makes this JVM exit 143 even with its shutdown hook running to
+#      completion (measured — see the CB-594 report). A plain `kill` here would race launchd's own
+#      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.
 #
 # Usage:
 #   scripts/redeploy-bridged.sh              # build, confirm, restart, verify
@@ -41,13 +51,17 @@ HEALTH='http://127.0.0.1:8765/healthz'
 STOP_WAIT=30      # seconds to wait for a clean exit before reporting failure
 HEALTH_WAIT=60    # seconds to wait for /healthz to answer after start
 
+# CB-594: the launchd agent this script must not fight with (see trap 6 above).
+LAUNCHD_LABEL='dev.ltms.bridged'
+LAUNCHD_PLIST="$HOME/Library/LaunchAgents/$LAUNCHD_LABEL.plist"
+
 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,30p' "${BASH_SOURCE[0]}"; exit 0 ;;
+    -h|--help)  sed -n '3,37p' "${BASH_SOURCE[0]}"; exit 0 ;;
     *) echo "unknown option: $arg (try --help)" >&2; exit 2 ;;
   esac
 done
@@ -59,6 +73,11 @@ die()  { printf '\n   FAIL  %s\n\n' "$*" >&2; exit 1; }
 
 jar_id() { [ -f "$JAR" ] && shasum -a 256 "$JAR" | cut -c1-12 || echo "absent"; }
 running_pid() { pgrep -f "$PATTERN" || true; }
+# `launchctl list <label>` exits 0 iff the label is loaded (registered with launchd) — true whether
+# or not it is currently running, which is exactly "supervision is active" for our purposes. Read-
+# only: neither helper below changes anything, so both are also safe under --check.
+launchd_installed() { [ -f "$LAUNCHD_PLIST" ]; }
+launchd_loaded() { launchctl list "$LAUNCHD_LABEL" >/dev/null 2>&1; }
 
 # ---------------------------------------------------------------- report state
 
@@ -72,6 +91,22 @@ 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.
+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)."
+fi
+SUPERVISED=0
+if launchd_loaded; then
+  SUPERVISED=1
+  ok "launchd agent loaded ($LAUNCHD_LABEL) — launchd supervises this daemon"
+else
+  warn "launchd agent not loaded — this script is the only thing that will restart the daemon."
+fi
+
 # 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
@@ -82,6 +117,18 @@ else
   warn "Fix \${SHARED_ENV}/tools/secrets.sh before relying on worker checkpoints."
 fi
 
+# Same trap, second variable (CB-591). A profile's `tokenEnv:` is resolved from the DAEMON's own
+# process environment by HerdrPeerLauncher.resolveEnv, so a token added to secrets.sh after the
+# daemon started is simply absent. The launcher then injects an empty token and llm.ltms.dev answers
+# 401 — long after the restart, and with nothing tying the two together.
+if zsh -lc '[ -n "${AI_GATEWAY_TOKEN:-}" ]' 2>/dev/null; then
+  ok "AI_GATEWAY_TOKEN resolves in a login shell"
+else
+  warn "AI_GATEWAY_TOKEN is EMPTY in a login shell."
+  warn "Any profile whose tokenEnv is AI_GATEWAY_TOKEN will get an empty token and 401 at the gateway."
+  warn "This only matters once a profile points at llm.ltms.dev — harmless before that."
+fi
+
 if [ "$CHECK_ONLY" = 1 ]; then
   say "--check: nothing changed"
   exit 0
@@ -123,11 +170,26 @@ if [ -n "$OLD_PID" ] && [ "$ASSUME_YES" = 0 ]; then
 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.
 
 if [ -n "$OLD_PID" ]; then
   say "stop"
   RESTART_MARK="$(wc -l < "$OUT" 2>/dev/null || echo 0)"   # verify a FRESH line appears later
-  kill "$OLD_PID"
+  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
   for _ in $(seq "$STOP_WAIT"); do
     [ -z "$(running_pid)" ] && break
     sleep 1
@@ -138,18 +200,33 @@ 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
+  # 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)"
 else
   RESTART_MARK="$(wc -l < "$OUT" 2>/dev/null || echo 0)"
 fi
 
 # ------------------------------------------------------------------ start
-# Login shell (zsh -l) is what puts the secrets on the daemon's environment. cwd must be bridged/
-# because the daemon resolves bridged.yaml, logs/ and target/ relative to it.
+# Unsupervised: login shell (zsh -l) is what puts the secrets on the daemon's environment, and cwd
+# must be bridged/ because the daemon resolves bridged.yaml, logs/ and target/ relative to it.
+# Supervised: launchd does both — deploy/dev.ltms.bridged.plist points ProgramArguments at
+# scripts/bridged-launchd-wrapper.sh (CB-594), which is what execs the login shell in launchd's
+# place, and WorkingDirectory in the plist already pins bridged/.
 
 say "start"
-# Absolute jar path so `ps` names which checkout is running; cwd still bridged/ because the daemon
-# resolves bridged.yaml, logs/ and target/ relative to it.
-( cd "$BRIDGED" && zsh -lc "nohup java -jar '$JAR' >> bridged.out 2>&1 &" )
+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."
+  launchctl load -w "$LAUNCHD_PLIST" || die "launchctl load failed"
+else
+  # Absolute jar path so `ps` names which checkout is running.
+  ( cd "$BRIDGED" && zsh -lc "nohup java -jar '$JAR' >> bridged.out 2>&1 &" )
+fi
 
 for _ in $(seq 10); do
   NEW_PID="$(running_pid)"