CB-578 stage A: classify a usage-limit refusal instead of a completed reply

A backend that refuses on a subscription usage limit leaves the pane healthy but
the turn ends with no bridge_reply; the completion fallback used to scrape and
hand that refusal back as if it were a real answer. CompletionResolver now
matches the scrape against a per-profile exhaustedPattern (config, never a
vendor string) and resolves the send as Rendezvous.Kind/Outcome.BACKEND_EXHAUSTED
with a reason carrying the matched line, kept distinct from GONE/WORKER_FAILED.
A profile with no pattern configured is unaffected. Coverage is logged at
startup via CompletionResolver.coverage(...), naming which profiles have a
pattern and which don't, following FleetHealthMonitor.coverage's pattern.

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

@@ -13,6 +13,7 @@ import dev.ltms.bridged.herdr.PaneLocator;
 import dev.ltms.bridged.herdr.UnixSocketHerdrClient;
 import dev.ltms.bridged.herdr.WorkspaceControl;
 import dev.ltms.bridged.inject.CompletionResolver;
+import dev.ltms.bridged.inject.ExhaustedPatternLookup;
 import dev.ltms.bridged.inject.Injector;
 import dev.ltms.bridged.inject.StatusPoller;
 import dev.ltms.bridged.inject.TurnListener;
@@ -60,6 +61,7 @@ import java.util.concurrent.atomic.AtomicReference;
 import java.util.function.Function;
 import java.util.function.Predicate;
 import java.util.function.Supplier;
+import java.util.regex.Pattern;
 import java.util.stream.Collectors;
 
 /**
@@ -253,7 +255,24 @@ public final class Bridged {
         // The blocking message endpoint (CB-104) is the producer; the poller is inert until then.
         // CB-106: a confirmed turn completion resolves a blocked send whose worker never replied.
         Rendezvous rendezvous = new Rendezvous();
-        CompletionResolver completion = new CompletionResolver(agents, rendezvous);
+        // CB-578 stage A: classify a completion-fallback scrape that matches a profile's configured
+        // usage-limit refusal as BACKEND_EXHAUSTED rather than handing it back as a real answer.
+        // Compiled once at startup, keyed by profile name; a profile with no exhaustedPattern is
+        // simply absent here, so its workers keep today's completion-fallback behaviour unchanged.
+        Map<String, Pattern> exhaustedPatternsByProfile = new LinkedHashMap<>();
+        cfg.profiles().forEach((name, profile) -> {
+            if (profile.hasExhaustedPattern()) {
+                exhaustedPatternsByProfile.put(name, Pattern.compile(profile.exhaustedPattern()));
+            }
+        });
+        ExhaustedPatternLookup exhaustedPatterns = target -> sessions.roster().stream()
+                .filter(session -> target.equals(session.terminalId()))
+                .findFirst()
+                .map(session -> exhaustedPatternsByProfile.get(session.profile()))
+                .orElse(null);
+        log.info("backend-exhausted classification (CB-578 stage A): {}",
+                CompletionResolver.coverage(cfg.profiles().keySet(), exhaustedPatternsByProfile.keySet()));
+        CompletionResolver completion = new CompletionResolver(agents, rendezvous, exhaustedPatterns);
         // CB-113: deliver only to an available worker (its MCP is connected), never its boot window.
         // CB-301: the manager's presence bridge records availability and drives SPAWNING → READY.
         MemberPresence presence = sessions.asPresence();

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

@@ -181,6 +181,12 @@ public record BridgedConfig(
      *                       opposite intents). For the same reason, an {@code env:} entry naming
      *                       {@code ANTHROPIC_BASE_URL} or {@code ANTHROPIC_AUTH_TOKEN} is refused at
      *                       config load (CB-542): on the subscription path no guard would vet it.
+     * @param exhaustedPattern  regex matched against a completion-fallback scrape (CB-578 stage A) to
+     *                       classify a turn that ended with no {@code bridge_reply} as the backend
+     *                       having refused on a subscription usage limit, rather than a real answer.
+     *                       {@code null}/blank ⇒ the classification never fires for this profile and
+     *                       today's completion-fallback behaviour is unchanged. Every backend words
+     *                       its refusal differently, so this is config, never a vendor string in code.
      */
     @JsonIgnoreProperties(ignoreUnknown = true)
     public record Profile(String profile, String baseUrl, String model,
@@ -193,7 +199,8 @@ public record BridgedConfig(
                          Map<String, String> env,
                          Float weight,
                          Integer maxLoad,
-                         Boolean subscription) {
+                         Boolean subscription,
+                         String exhaustedPattern) {
 
         /** Peer kind spawned by {@link dev.ltms.bridged.member.ClaudeCodeLauncher} (the default). */
         public static final String KIND_CLAUDE_CODE = "claude-code";
@@ -236,6 +243,9 @@ public record BridgedConfig(
             weight = (weight == null || weight <= 0.0f) ? 1.0f : weight;
             maxLoad = (maxLoad == null || maxLoad <= 0) ? null : maxLoad;
             subscription = (subscription != null && subscription) ? Boolean.TRUE : Boolean.FALSE;
+            // exhaustedPattern stays null when unset/blank (opt-in) — no defaulting, no vendor
+            // wording: an unconfigured profile keeps today's completion-fallback behaviour exactly.
+            exhaustedPattern = (exhaustedPattern == null || exhaustedPattern.isBlank()) ? null : exhaustedPattern;
         }
 
         /**
@@ -248,7 +258,7 @@ public record BridgedConfig(
                       String placement, String workspace, String tabLabel, String mcpUrl,
                       String cwd, List<String> parityOverlay) {
             this(profile, baseUrl, model, configDir, tokenEnv, argv, placement, workspace, tabLabel,
-                    mcpUrl, cwd, parityOverlay, null, null, null, null, null, null, null);
+                    mcpUrl, cwd, parityOverlay, null, null, null, null, null, null, null, null);
         }
 
         /**
@@ -260,7 +270,7 @@ public record BridgedConfig(
                       String placement, String workspace, String tabLabel, String mcpUrl,
                       String cwd, List<String> parityOverlay, String gitTokenEnv, String gitHostEnv) {
             this(profile, baseUrl, model, configDir, tokenEnv, argv, placement, workspace, tabLabel,
-                    mcpUrl, cwd, parityOverlay, gitTokenEnv, gitHostEnv, null, null, null, null, null);
+                    mcpUrl, cwd, parityOverlay, gitTokenEnv, gitHostEnv, null, null, null, null, null, null);
         }
 
         /**
@@ -273,13 +283,14 @@ public record BridgedConfig(
                       String cwd, List<String> parityOverlay, String gitTokenEnv, String gitHostEnv,
                       String kind) {
             this(profile, baseUrl, model, configDir, tokenEnv, argv, placement, workspace, tabLabel,
-                    mcpUrl, cwd, parityOverlay, gitTokenEnv, gitHostEnv, kind, null, null, null, null);
+                    mcpUrl, cwd, parityOverlay, gitTokenEnv, gitHostEnv, kind, null, null, null, null, null);
         }
 
         /** A copy with {@code profile} set — used to default a profile to its {@code workers} key. */
         public Profile withProfile(String p) {
             return new Profile(p, baseUrl, model, configDir, tokenEnv, argv, placement, workspace, tabLabel,
-                    mcpUrl, cwd, parityOverlay, gitTokenEnv, gitHostEnv, kind, env, weight, maxLoad, subscription);
+                    mcpUrl, cwd, parityOverlay, gitTokenEnv, gitHostEnv, kind, env, weight, maxLoad, subscription,
+                    exhaustedPattern);
         }
 
         /** True when this profile is served by the Claude Code adapter (the default kind). */
@@ -312,7 +323,12 @@ public record BridgedConfig(
                       String cwd, List<String> parityOverlay, String gitTokenEnv, String gitHostEnv,
                       String kind, Map<String, String> env, Float weight, Integer maxLoad) {
             this(profile, baseUrl, model, configDir, tokenEnv, argv, placement, workspace, tabLabel,
-                    mcpUrl, cwd, parityOverlay, gitTokenEnv, gitHostEnv, kind, env, weight, maxLoad, null);
+                    mcpUrl, cwd, parityOverlay, gitTokenEnv, gitHostEnv, kind, env, weight, maxLoad, null, null);
+        }
+
+        /** True when this profile's CB-578 stage A backend-exhausted classification is configured. */
+        public boolean hasExhaustedPattern() {
+            return exhaustedPattern != null;
         }
 
         /** True when this profile's workers are granted a forge token to open their own PR (CB-302). */

bridged/src/main/java/dev/ltms/bridged/inject/CompletionResolver.java

@@ -6,8 +6,13 @@ import dev.ltms.bridged.msg.TurnToken;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+import java.util.List;
+import java.util.Objects;
+import java.util.Set;
+import java.util.TreeSet;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.ConcurrentHashMap;
+import java.util.regex.Pattern;
 
 /**
  * The CB-106 completion fallback: bridges the {@link Injector}'s turn-completion signal to the
@@ -61,6 +66,7 @@ public final class CompletionResolver implements TurnListener {
 
     private final AgentControl agents;
     private final Rendezvous rendezvous;
+    private final ExhaustedPatternLookup exhaustedPatterns;
 
     /**
      * Per-target record of the turn currently in flight: the exact {@link Rendezvous} waiter its
@@ -78,9 +84,16 @@ public final class CompletionResolver implements TurnListener {
 
     private final ConcurrentHashMap<String, InFlight> inFlight = new ConcurrentHashMap<>();
 
-    public CompletionResolver(AgentControl agents, Rendezvous rendezvous) {
+    /**
+     * @param exhaustedPatterns CB-578 stage A: per-target lookup for a profile's configured
+     *                          usage-limit refusal pattern. Required — there is deliberately no
+     *                          defaulting overload; a caller that does not want the classification
+     *                          must pass an explicit inert value ({@link ExhaustedPatternLookup#none()}).
+     */
+    public CompletionResolver(AgentControl agents, Rendezvous rendezvous, ExhaustedPatternLookup exhaustedPatterns) {
         this.agents = agents;
         this.rendezvous = rendezvous;
+        this.exhaustedPatterns = Objects.requireNonNull(exhaustedPatterns, "exhaustedPatterns");
     }
 
     @Override
@@ -157,11 +170,12 @@ public final class CompletionResolver implements TurnListener {
             return;
         }
         String tail;
+        String assistantBlock = null;
         int originalLength = 0;
         boolean clipped = false;
         boolean scrapeFailed = false;
         try {
-            String assistantBlock = lastAssistantBlock(agents.read(target, SCRAPE_SOURCE));
+            assistantBlock = lastAssistantBlock(agents.read(target, SCRAPE_SOURCE));
             originalLength = assistantBlock.strip().length();
             clipped = originalLength > MAX_SCRAPE_CHARS;
             tail = clip(assistantBlock);
@@ -184,6 +198,22 @@ public final class CompletionResolver implements TurnListener {
                     target);
             return; // keep the in-flight record: a later genuine completion still needs it
         }
+        // CB-578 stage A: a turn that ended with no bridge_reply AND whose scrape matches the
+        // backend's configured usage-limit pattern is a refusal, not an answer. Classify it as
+        // BACKEND_EXHAUSTED rather than handing the caller a scrape that reads like a real reply.
+        if (!scrapeFailed) {
+            Pattern exhausted = exhaustedPatterns.patternFor(target);
+            String matchedLine = exhausted == null ? null : firstMatchingLine(assistantBlock, exhausted);
+            if (matchedLine != null) {
+                String reason = "backend exhausted (usage limit): " + matchedLine;
+                if (rendezvous.resolveExhausted(waiter, reason)) {
+                    inFlight.remove(target, turn);
+                    log.warn("completion for {} classified BACKEND_EXHAUSTED (no bridge_reply; scrape "
+                            + "matched the profile's exhausted pattern): {}", target, reason);
+                }
+                return;
+            }
+        }
         String completion = clipped ? tail + "\n" + CLIPPED_PANE_TAIL_MARKER : tail;
         if (rendezvous.resolveCompletion(waiter, completion)) {
             inFlight.remove(target, turn);
@@ -232,6 +262,45 @@ public final class CompletionResolver implements TurnListener {
         }
     }
 
+    /**
+     * The first line of {@code text} matching {@code pattern}, stripped — the CB-578 stage A
+     * evidence carried in a {@code BACKEND_EXHAUSTED} reason so the operator sees the real refusal
+     * text, never a generic label. {@code null} if no line matches.
+     */
+    static String firstMatchingLine(String text, Pattern pattern) {
+        if (text == null || text.isEmpty()) return null;
+        for (String line : text.split("\n", -1)) {
+            if (pattern.matcher(line).find()) {
+                return line.strip();
+            }
+        }
+        return null;
+    }
+
+    /**
+     * Coverage summary for the CB-578 stage A exhausted-pattern classification, logged at startup
+     * the way {@link dev.ltms.bridged.health.FleetHealthMonitor#coverage} is — so an operator can
+     * see whether the classification is on, and for which profiles, without reading every
+     * profile's config by hand.
+     *
+     * @param allProfiles        every configured profile name
+     * @param configuredProfiles the subset of {@code allProfiles} that carry an exhausted pattern
+     */
+    public static String coverage(Set<String> allProfiles, Set<String> configuredProfiles) {
+        if (configuredProfiles.isEmpty()) {
+            return "off (no profile has an exhaustedPattern configured; profiles: " + sorted(allProfiles) + ")";
+        }
+        Set<String> unconfigured = new TreeSet<>(allProfiles);
+        unconfigured.removeAll(configuredProfiles);
+        return unconfigured.isEmpty()
+                ? "full (all profiles configured: " + sorted(allProfiles) + ")"
+                : "partial (configured: " + sorted(configuredProfiles) + "; not configured: " + sorted(unconfigured) + ")";
+    }
+
+    private static List<String> sorted(Set<String> names) {
+        return names.stream().sorted().toList();
+    }
+
     private static String clip(String s) {
         if (s == null) return "";
         String trimmed = s.strip();

bridged/src/main/java/dev/ltms/bridged/inject/ExhaustedPatternLookup.java

@@ -0,0 +1,27 @@
+package dev.ltms.bridged.inject;
+
+import java.util.regex.Pattern;
+
+/**
+ * Per-target lookup for a profile's configured usage-limit refusal pattern (CB-578 stage A): how
+ * {@link CompletionResolver} tells a backend that refused on a subscription usage limit — the
+ * worker's pane stays healthy, but the account is exhausted — apart from a genuine completion.
+ *
+ * <p>The pattern is always profile config, never a vendor string in Java source: every backend
+ * words its refusal differently, so a hardcoded sentence would only ever match one of them.
+ */
+@FunctionalInterface
+public interface ExhaustedPatternLookup {
+
+    /** The compiled pattern configured for {@code target}'s profile, or {@code null} if none. */
+    Pattern patternFor(String target);
+
+    /**
+     * Inert lookup — no profile has a pattern configured, so the classification never fires and
+     * the completion fallback behaves exactly as before CB-578 stage A. The explicit stand-in a
+     * caller (or a test not exercising this feature) passes instead of a defaulting overload.
+     */
+    static ExhaustedPatternLookup none() {
+        return target -> null;
+    }
+}

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

@@ -458,6 +458,11 @@ public final class BridgeMcp {
                     "[worker finished without a structured bridge_reply — transcript tail follows]\n" + r.text());
             // The worker ran the turn then wedged (CB-109) — surface the error context.
             case WORKER_FAILED -> text("[worker failed — turn ended in an unrecoverable state]\n" + r.text());
+            // The backend refused on a subscription usage limit (CB-578 stage A) — the worker's
+            // pane stayed healthy, but its account is exhausted. Distinct from WORKER_FAILED so the
+            // primary gets the real cause, not a generic wedge.
+            case BACKEND_EXHAUSTED -> text("[backend exhausted — the worker's account refused on a "
+                    + "usage limit]\n" + r.text());
             // The worker paused mid-turn to ask (CB-205) — tell the primary how to answer in-turn.
             case QUESTION -> text("[question] the worker paused to ask before it can finish:\n" + r.text()
                     + "\n\nAnswer it by calling bridge_send again with turnId=\"" + r.turnId()

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

@@ -69,6 +69,14 @@ public final class MessageService {
          * failure context (e.g. the error screen). Terminal, but not a successful completion.
          */
         WORKER_FAILED,
+        /**
+         * The turn finished without a {@code bridge_reply} and the scrape matched the backend's
+         * configured usage-limit refusal pattern (CB-578 stage A); {@code text} is the reason,
+         * carrying the matched line. The worker's pane is healthy — only its account is refusing —
+         * so this is never reported as a completed reply, and is kept distinct from
+         * {@link #WORKER_FAILED} (a wedged worker) and a session simply going {@code GONE}.
+         */
+        BACKEND_EXHAUSTED,
         /**
          * The worker paused mid-turn to ask the primary a question (CB-205); {@code text} is the
          * question and {@code turnId} correlates the answer. Not terminal — the primary answers with
@@ -280,6 +288,7 @@ public final class MessageService {
             case COMPLETED_UNREPLIED -> "completion_fallback";
             case TIMED_OUT_WORKING, TIMED_OUT_QUEUED, BUSY -> "timeout";
             case WORKER_FAILED -> "failed";
+            case BACKEND_EXHAUSTED -> "backend_exhausted";
             case STALE_TURN, QUESTION -> null; // not a completed delegation
         };
     }
@@ -591,9 +600,11 @@ public final class MessageService {
             String source = r.outcome() == Outcome.REPLIED ? "reply" : "transcript";
             return new TaskView(ticket, Phase.DONE, r.text(), source, null, null);
         }
-        // A wedged worker (CB-109) carries the error context as its reason; the timeout/busy
-        // outcomes carry none, so fall back to the outcome name.
-        String detail = r.outcome() == Outcome.WORKER_FAILED && r.text() != null
+        // A wedged worker (CB-109) or a backend-exhausted classification (CB-578 stage A) carries
+        // the real cause as its reason; the timeout/busy outcomes carry none, so fall back to the
+        // outcome name.
+        boolean carriesReason = r.outcome() == Outcome.WORKER_FAILED || r.outcome() == Outcome.BACKEND_EXHAUSTED;
+        String detail = carriesReason && r.text() != null
                 ? r.text()
                 : "no reply — " + r.outcome().name().toLowerCase();
         return new TaskView(ticket, Phase.FAILED, null, null, detail, null);
@@ -669,6 +680,7 @@ public final class MessageService {
             case REPLY -> Outcome.REPLIED;
             case COMPLETION -> Outcome.COMPLETED_UNREPLIED;
             case FAILED -> Outcome.WORKER_FAILED;
+            case BACKEND_EXHAUSTED -> Outcome.BACKEND_EXHAUSTED;
             case QUESTION -> Outcome.QUESTION;
         };
     }

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

@@ -33,6 +33,13 @@ public final class Rendezvous {
         COMPLETION,
         /** The worker ran the turn then wedged (CB-109); {@code text} is the failure context. */
         FAILED,
+        /**
+         * The turn finished without a {@code bridge_reply}, and the scrape matched the backend's
+         * configured usage-limit refusal pattern (CB-578 stage A); {@code text} is the reason,
+         * carrying the matched line. The pane is healthy — only the account is refusing — so this
+         * is kept separate from a session simply going {@code GONE}.
+         */
+        BACKEND_EXHAUSTED,
         /**
          * The worker paused mid-turn to ask the primary a question (CB-205 reverse rendezvous);
          * {@code text} is the question and {@code turnId} correlates the primary's answer back to
@@ -224,6 +231,19 @@ public final class Rendezvous {
         return waiter != null && waiter.complete(new Resolution(Kind.FAILED, reason));
     }
 
+    /**
+     * Resolve a specific captured {@code waiter} as {@link Kind#BACKEND_EXHAUSTED} (CB-578 stage A):
+     * the turn finished with no {@code bridge_reply} and the scrape matched the backend's configured
+     * usage-limit pattern; {@code reason} carries the matched line. Like
+     * {@link #resolveCompletion(CompletableFuture, String)} it targets the exact captured send
+     * (CB-116). A no-op if that waiter was already resolved — first resolution wins.
+     *
+     * @return {@code true} if this call resolved the waiter, {@code false} if it was null or already resolved
+     */
+    public boolean resolveExhausted(CompletableFuture<Resolution> waiter, String reason) {
+        return waiter != null && waiter.complete(new Resolution(Kind.BACKEND_EXHAUSTED, reason));
+    }
+
     private boolean complete(String session, Resolution resolution) {
         CompletableFuture<Resolution> waiter = waiters.get(session);
         return waiter != null && waiter.complete(resolution);

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

@@ -403,9 +403,12 @@ public final class BridgedApp {
                         case TIMED_OUT_QUEUED -> "queued";
                         case BUSY -> "busy";
                         case WORKER_FAILED -> "failed";
+                        case BACKEND_EXHAUSTED -> "backend_exhausted";
                         default -> "done"; // unreachable (terminal outcomes handled above)
                     },
-                    "detail", reply.outcome() == MessageService.Outcome.WORKER_FAILED && reply.text() != null
+                    "detail", (reply.outcome() == MessageService.Outcome.WORKER_FAILED
+                                    || reply.outcome() == MessageService.Outcome.BACKEND_EXHAUSTED)
+                                    && reply.text() != null
                             ? reply.text()
                             : "no reply within " + timeout + "ms; poll status or retry"));
         }