@desplega.ai/agent-swarm 1.100.1 → 1.100.3

package/src/providers/claude-adapter.ts

@@ -144,15 +144,46 @@ export function resolveClaudeBridgeEnabled(
   return parseClaudeBridgeEnabled(candidate);
 }
 
-function resolveClaudeBinaryArgv(
+/**
+ * Resolve the claude binary argv, gating claude-bridge on an OAuth token.
+ *
+ * claude-bridge exists to keep subscription/OAuth billing correct by driving
+ * the real interactive Claude TUI in tmux. It authenticates the child claude
+ * from `CLAUDE_CODE_OAUTH_TOKEN` only — it deliberately strips `ANTHROPIC_*`
+ * from the launched process — so it cannot run on an Anthropic API key. And
+ * API-key billing is identical headless vs interactive, so there's no reason to
+ * pay the bridge's complexity/footguns when only an API key is available.
+ *
+ * Therefore: only route through claude-bridge when an OAuth token is present.
+ * If the bridge is requested (`SWARM_USE_CLAUDE_BRIDGE`) but no OAuth token is
+ * set, fall back to stock `claude`, which Claude Code authenticates fine from
+ * the API key. `bridgeRequestedWithoutOAuth` lets the caller log why.
+ *
+ * Exported for unit testing.
+ */
+export function resolveClaudeBinaryArgv(
   resolvedEnv: Record<string, string | undefined>,
   fallbackEnv: Record<string, string | undefined> = process.env,
-): { raw: string; argv: string[]; useClaudeBridge: boolean } {
-  const useClaudeBridge = resolveClaudeBridgeEnabled(resolvedEnv, fallbackEnv);
+): {
+  raw: string;
+  argv: string[];
+  useClaudeBridge: boolean;
+  bridgeRequestedWithoutOAuth: boolean;
+} {
+  const bridgeRequested = resolveClaudeBridgeEnabled(resolvedEnv, fallbackEnv);
+  const hasOAuthToken = Boolean(
+    (resolvedEnv.CLAUDE_CODE_OAUTH_TOKEN ?? fallbackEnv.CLAUDE_CODE_OAUTH_TOKEN)?.trim(),
+  );
+  const useClaudeBridge = bridgeRequested && hasOAuthToken;
   const raw = useClaudeBridge
     ? CLAUDE_BRIDGE_BINARY
     : resolveClaudeBinary(resolvedEnv, fallbackEnv);
-  return { raw, argv: parseClaudeBinary(raw), useClaudeBridge };
+  return {
+    raw,
+    argv: parseClaudeBinary(raw),
+    useClaudeBridge,
+    bridgeRequestedWithoutOAuth: bridgeRequested && !hasOAuthToken,
+  };
 }
 
 function isLegacyClaudeBridgeCompatBinary(raw: string): boolean {
@@ -898,7 +929,13 @@ export class ClaudeAdapter implements ProviderAdapter {
       raw: claudeBinaryRaw,
       argv: claudeBinaryArgv,
       useClaudeBridge,
+      bridgeRequestedWithoutOAuth,
     } = resolveClaudeBinaryArgv(sourceEnv);
+    if (bridgeRequestedWithoutOAuth) {
+      console.warn(
+        `\x1b[33m[claude]\x1b[0m SWARM_USE_CLAUDE_BRIDGE is set but no CLAUDE_CODE_OAUTH_TOKEN is present — falling back to stock 'claude'. claude-bridge requires a subscription/OAuth token (it forwards only the OAuth token to claude and strips ANTHROPIC_*); API-key billing is identical headless vs interactive, so the bridge isn't needed.`,
+      );
+    }
     const isLegacyBridgeCompat = isLegacyClaudeBridgeCompatBinary(claudeBinaryRaw);
     const effectiveClaudeBinaryArgv = useClaudeBridge
       ? withClaudeBridgeAuthArgs(claudeBinaryArgv, sourceEnv)

package/src/slack/assistant.ts

@@ -5,12 +5,17 @@ import { slackContextKey } from "../tasks/context-key";
 import { createTaskWithSiblingAwareness } from "../tasks/sibling-awareness";
 import { resolveSlackUserId } from "./enrich";
 import { wasEventSeen } from "./event-dedup";
+import { hasOtherUserMention } from "./router";
 import { bufferThreadMessage } from "./thread-buffer";
 // Side-effect import: registers all Slack event templates in the in-memory registry
 import "./templates";
 
 const additiveSlack = process.env.ADDITIVE_SLACK === "true";
 
+// Cache the bot's own Slack user ID so we can suppress messages that @-mention
+// a different agent (e.g. Devin) rather than our bot.
+let cachedBotUserId: string | null = null;
+
 export function createAssistant(): Assistant {
   return new Assistant({
     threadStarted: async ({ say, setSuggestedPrompts, saveThreadContext }) => {
@@ -72,6 +77,29 @@ export function createAssistant(): Assistant {
         const messageText = (msg.text as string) || "";
         const userId = (msg.user as string) || "";
 
+        // Resolve the bot's own Slack user ID (cached after first call) so we can
+        // check whether this message is actually addressed to us.
+        if (!cachedBotUserId) {
+          try {
+            const authResult = await client.auth.test();
+            cachedBotUserId = (authResult.user_id as string) ?? null;
+          } catch (e) {
+            console.warn("[Slack] assistant: auth.test() failed — skipping bot-mention check", e);
+          }
+        }
+
+        // If the message @-mentions someone OTHER than our bot and does NOT mention
+        // our bot, it is addressed to a different agent/user — do not spawn a task.
+        if (cachedBotUserId) {
+          const botMentioned = messageText.includes(`<@${cachedBotUserId}>`);
+          if (!botMentioned && hasOtherUserMention(messageText, cachedBotUserId)) {
+            console.log(
+              `[Slack] assistant: skipping message in ${channelId}/${threadTs} — mentions another user, not us`,
+            );
+            return;
+          }
+        }
+
         // Resolve canonical user identity via the shared cascade. On no-email,
         // the cascade records the user in the kv unmapped tracker; this handler
         // proceeds without a `requestedByUserId`.

package/src/slack/channel-join.ts

@@ -1,5 +1,7 @@
 import type { WebClient } from "@slack/web-api";
 
+const logger = console;
+
 // @slack/web-api platform errors set message to "An API error occurred: <code>"
 // and store the raw Slack API code at error.data.error.
 function slackCode(error: unknown): string | undefined {
@@ -8,12 +10,38 @@ function slackCode(error: unknown): string | undefined {
   return typeof d?.error === "string" ? d.error : undefined;
 }
 
+/**
+ * Returns true if the channel has any external (non-host-org) members.
+ * Uses Slack's documented flags: is_ext_shared (accepted Connect) and
+ * is_pending_ext_shared (invite sent, not yet accepted). These two booleans
+ * are the authoritative org-boundary signal per Slack's API docs.
+ */
+async function isKnownExternalChannel(client: WebClient, channelId: string): Promise<boolean> {
+  try {
+    const resp = await client.conversations.info({ channel: channelId });
+    const ch = (resp.channel ?? {}) as {
+      is_ext_shared?: boolean;
+      is_pending_ext_shared?: boolean;
+    };
+    return ch.is_ext_shared === true || ch.is_pending_ext_shared === true;
+  } catch (error) {
+    logger.warn(
+      `[Slack] conversations.info failed for ${channelId}; attempting join fallback:`,
+      error,
+    );
+    return false;
+  }
+}
+
 /**
  * Wraps a Slack API call with automatic channel join for public channels.
  *
- * On not_in_channel: calls conversations.join and retries the original call once.
- * On private channel (method_not_supported_for_channel_type): throws a descriptive
- * error telling the caller the bot must be /invite-d — it cannot self-join private channels.
+ * On not_in_channel: checks conversations.info first — if is_ext_shared or
+ * is_pending_ext_shared is true the channel has external members; throws a
+ * human-invite error instead of self-joining. Internal channels (including
+ * Enterprise Grid org-shared channels) proceed normally.
+ * On private channel (method_not_supported_for_channel_type): throws a
+ * descriptive error telling the caller to /invite the bot.
  */
 export async function withAutoJoin<T>(
   client: WebClient,
@@ -25,6 +53,13 @@ export async function withAutoJoin<T>(
   } catch (error) {
     if (slackCode(error) !== "not_in_channel") throw error;
 
+    // Only block when Slack positively identifies an external channel.
+    if (await isKnownExternalChannel(client, channelId)) {
+      throw new Error(
+        `Cannot auto-join external channel ${channelId} — invite the bot with /invite @<bot-name> first.`,
+      );
+    }
+
     try {
       await client.conversations.join({ channel: channelId });
     } catch (joinError) {

package/src/slack/handlers.ts

@@ -490,8 +490,11 @@ export function registerMessageHandler(app: App): void {
     // Detect assistant thread context — file_share messages in DM assistant threads
     // bypass the assistant handler and land here instead. Treat them as implicit mentions
     // so they route to the lead agent rather than being silently dropped.
+    // Guard: suppress implicit mention when the message @-mentions someone else but NOT us —
+    // those messages are addressed to a different agent/user (e.g. Devin) and must not spawn.
     const isAssistantThread = !!msg.assistant_thread;
-    const isImplicitMention = isAssistantThread && !botMentioned;
+    const isImplicitMention =
+      isAssistantThread && !botMentioned && !hasOtherUserMention(effectiveText, botUserId);
 
     // ADDITIVE_SLACK: Check for !now command in threads
     const additiveSlack = process.env.ADDITIVE_SLACK === "true";

package/src/tasks/worker-follow-up.ts

@@ -6,6 +6,7 @@ import {
   getLeadAgent,
   getTaskAttachments,
   getTaskById,
+  hasNonTerminalRerouteDecisionChild,
 } from "../be/db";
 import { repointTrackerSyncBySwarmId } from "../be/db-queries/tracker";
 import { resolveTemplate } from "../prompts/resolver";
@@ -23,8 +24,33 @@ export const WORKER_LIVENESS_WINDOW_SECONDS = Number(
   process.env.WORKER_LIVENESS_WINDOW_SECONDS || "30",
 );
 
+/**
+ * Rollback switch (DES-523) for the same-agent crash-recovery pin. ON by
+ * default: `crash_recovery` resumes pin back to their original agent regardless
+ * of `lastActivityAt` freshness. Set `HEARTBEAT_PIN_CRASH_RESUME=0` to restore
+ * the pre-DES-523 behavior verbatim — `crash_recovery` then requires the 30s
+ * `fresh` window like every other reason, so at the ~5-min detection mark it
+ * falls back to the unassigned pool. A reversible kill-switch for this
+ * production crash-path change (no code revert needed if the pin misbehaves).
+ */
+export const HEARTBEAT_PIN_CRASH_RESUME = process.env.HEARTBEAT_PIN_CRASH_RESUME !== "0";
+
 export const RESUME_GENERATION_TAG_PREFIX = "resume-generation:";
 
+/**
+ * Tag set ONLY on a genuine same-agent `crash_recovery` pin (i.e. when the
+ * resume is actually assigned back to the original agent). The heartbeat reaper
+ * (`getStalePinnedResumes`) scopes its sweep to this tag so it cannot mistake a
+ * *pooled* resume that `autoAssignPoolTasks` later flips to `pending` — which
+ * keeps its original `createdAt` and would otherwise look identical to a stale
+ * pin — for an unreclaimed crash pin, and so it never escalates a
+ * `context_limits` / `manual_supersede` pin under a `crash_recovery` label.
+ *
+ * The literal is duplicated in `getStalePinnedResumes` (src/be/db.ts) rather
+ * than imported, to avoid a worker-follow-up ↔ db import cycle — keep them in sync.
+ */
+export const CRASH_RECOVERY_PIN_TAG = "crash-recovery-pin";
+
 export function getResumeGeneration(task: Pick<AgentTask, "tags">): number {
   const tag = task.tags.find((value) => value.startsWith(RESUME_GENERATION_TAG_PREFIX));
   if (!tag) return 0;
@@ -166,10 +192,25 @@ export type CreateResumeFollowUpResult =
  * at session-init. The resume task runs on the assignee agent's own model. See
  * the `model` carve-out comment in `createTaskExtended` (`src/be/db.ts`).
  *
- * Routing: the parent's assigned worker (`parent.agentId`) is preferred if
- * its `lastActivityAt` is within `WORKER_LIVENESS_WINDOW_SECONDS` AND it has
- * remaining capacity (`getActiveTaskCount < agent.maxTasks`). Otherwise the
- * resume task goes to the unassigned pool for any worker to pick up.
+ * Routing: the parent's assigned worker (`parent.agentId`) is preferred when
+ * the agent row still exists, is not `offline`, and has remaining capacity
+ * (`getActiveTaskCount < agent.maxTasks`). For `crash_recovery` the pin holds
+ * regardless of `lastActivityAt` freshness — the agent ID is stable across a
+ * restart and the crashed row survives intact, so a stale `lastActivityAt` at
+ * the ~5-min crash-detection mark means "restarting", not "gone". Pinning keeps
+ * the resume off the role-blind unassigned pool so no wrong-specialization
+ * worker can grab it (DES-523). For `context_limits` / `manual_supersede` the
+ * worker is alive, so `lastActivityAt` freshness is still required. The resume
+ * falls back to the unassigned pool only when the agent is genuinely gone
+ * (graceful close → `offline`) or its row is absent.
+ *
+ * Gone-agent / never-reclaimed case: a pin whose agent never returns is NOT
+ * re-pooled — the heartbeat's stale-resume reaper (`escalateUnreclaimedResumes`
+ * in `src/heartbeat/heartbeat.ts`) escalates it to a Lead re-delegation decision
+ * once `HEARTBEAT_RESUME_PIN_GRACE_MIN` lapses.
+ *
+ * The pin itself is gated by `HEARTBEAT_PIN_CRASH_RESUME` (default on); set it to
+ * `0` to restore the pre-DES-523 pool-fallback behavior.
  */
 export function createResumeFollowUp(args: {
   parentId: string;
@@ -183,24 +224,34 @@ export function createResumeFollowUp(args: {
     return { kind: "workflow-skip", stepId: parent.workflowRunStepId };
   }
 
-  // Routing decision — same DB process so the read-then-create window is
-  // small. Acceptable for v1 per the plan (the unassigned-pool fallback
-  // covers the race anyway).
+  // Routing decision — same DB process so the read-then-create window is small.
   //
-  // For `graceful_shutdown` specifically, force the unassigned-pool path:
-  // the parent worker is exiting and will call `closeAgent` (→ offline)
-  // moments after the supersede loop. At the moment of this check it
-  // still looks fresh + has capacity (the parent just terminal-
-  // transitioned), so the liveness branch would assign the resume task to
-  // a dying worker — leaving it orphaned in `pending` once the worker
-  // closes. Pool routing lets any live worker claim it.
+  // For `graceful_shutdown`, force the unassigned-pool path: the parent worker
+  // is exiting and will call `closeAgent` (→ offline) moments after the
+  // supersede loop. At this check it still looks fresh + has capacity (it just
+  // terminal-transitioned), so the liveness branch would pin the resume to a
+  // dying worker — orphaning it in `pending` once the worker closes. Pool
+  // routing lets any live worker claim it.
+  //
+  // For `crash_recovery`, deliberately PIN to the same (stable-ID) agent even
+  // when `lastActivityAt` is stale. This REVERSES the prior "let staleness pool
+  // it" behavior: crash detection only fires after STALL_THRESHOLD_NO_SESSION_MIN
+  // (~5 min), by which point a healthy-but-restarting worker is always >30s
+  // stale, so the old `fresh` gate dumped every crash resume into the role-blind
+  // pool where a wrong-specialization worker could grab it (DES-523). The agent
+  // ID is stable across restart and the crashed row survives intact, so here
+  // "stale" means "restarting", not "gone". We KEEP the `offline` guard — only a
+  // graceful close sets `offline`, i.e. genuinely gone → pool — and the capacity
+  // guard. An unreclaimed pin is escalated to a Lead decision by the heartbeat
+  // reaper, never silently re-pooled.
+  //
+  // Brittleness note: this relies on a hard crash NEVER marking the agent
+  // `offline` (only `POST /close` does). If future code offlines stale agents
+  // before remediation, this re-opens the pool path for `crash_recovery` —
+  // revisit the gate then.
   //
-  // Other reasons keep the liveness-aware routing:
-  //   - `crash_recovery`: parent worker is presumed dead → `lastActivityAt`
-  //     is stale or `status === "offline"`, so the existing check already
-  //     rejects it naturally.
   //   - `context_limits` / `manual_supersede`: the worker is alive and
-  //     can keep handling the resume task on a fresh session.
+  //     responsive, so keep requiring `fresh`.
   let preferredAgentId: string | undefined;
   if (parent.agentId && args.reason !== "graceful_shutdown") {
     const candidate = getAgentById(parent.agentId);
@@ -211,8 +262,17 @@ export function createResumeFollowUp(args: {
         Date.now() - lastActivity < WORKER_LIVENESS_WINDOW_SECONDS * 1000;
       const activeCount = getActiveTaskCount(candidate.id);
       const hasCap = activeCount < (candidate.maxTasks ?? 1);
-      if (fresh && hasCap) {
+      const isCrashRecovery = args.reason === "crash_recovery" && HEARTBEAT_PIN_CRASH_RESUME;
+      // crash_recovery pins regardless of `fresh` (unless the rollback switch is
+      // off); other reasons still require it.
+      if (hasCap && (isCrashRecovery || fresh)) {
         preferredAgentId = candidate.id;
+      } else if (isCrashRecovery && !hasCap) {
+        // The only reason a crash_recovery pin is skipped here is capacity —
+        // surface the pool fallback instead of letting it happen silently.
+        console.warn(
+          `[Heartbeat] crash_recovery resume for task ${parent.id.slice(0, 8)} NOT pinned: agent ${candidate.id.slice(0, 8)} at capacity (${activeCount}/${candidate.maxTasks ?? 1}); falling back to unassigned pool`,
+        );
       }
     }
   }
@@ -236,6 +296,14 @@ export function createResumeFollowUp(args: {
     `reason:${args.reason}`,
     `${RESUME_GENERATION_TAG_PREFIX}${getNextResumeGeneration(parent)}`,
   ];
+  // Mark a GENUINE same-agent crash pin (crash_recovery that actually pinned to
+  // the original agent) so the heartbeat reaper can scope to these only. A
+  // pooled resume — including a crash_recovery resume that fell to the pool at
+  // capacity — never gets this tag, so it can't be mistaken for a stale pin
+  // after autoAssignPoolTasks flips it to `pending`.
+  if (args.reason === "crash_recovery" && preferredAgentId !== undefined) {
+    tags.push(CRASH_RECOVERY_PIN_TAG);
+  }
 
   // Identity-shaped fields (dir, VCS provider/repo/number/url/etc.,
   // outputSchema, slack channel/thread/user, agentmail, mention, contextKey,
@@ -270,3 +338,96 @@ export function createResumeFollowUp(args: {
 
   return { kind: "created", task: created };
 }
+
+/** Result of `createRerouteDecisionTask`. */
+export type CreateRerouteDecisionResult =
+  | { kind: "created"; task: AgentTask }
+  | { kind: "skipped"; reason: "lead_not_found" | "duplicate_exists" };
+
+/**
+ * Hand the Lead a re-delegation DECISION task for a crash-recovery resume that
+ * was pinned to its original agent but never reclaimed within the grace window
+ * (DES-523). The Lead receives context — the crashed agent's identity + the
+ * original work — and must re-dispatch via `send-task` with an explicit
+ * `agentId`; it does NOT execute the work itself, and the work is never
+ * re-pooled. Mirrors `createWorkerTaskFollowUp`'s Lead-owned-follow-up shape.
+ *
+ * Invoked by the heartbeat reaper (`escalateUnreclaimedResumes`), NOT at crash
+ * time: "gone" can't be distinguished from "restarting" at detection time, so
+ * the Lead path is only reached after a pin has demonstrably failed to be
+ * reclaimed.
+ *
+ * Discriminator: `taskType: "reroute-decision"` (NOT "follow-up") so it is
+ * distinguishable from ordinary completion follow-ups for dedup and so the
+ * `send-task` Slack re-delegation guard (which only fires for `taskType ===
+ * "follow-up"`) never blocks the Lead's re-dispatch.
+ *
+ * Idempotent: skips when a non-terminal reroute-decision child already exists
+ * for the original. No lead → no-op (fail-safe), mirroring
+ * `createWorkerTaskFollowUp`.
+ *
+ * @param staleResume the failed pinned resume (R1). The generation budget for
+ *   the Lead's re-dispatch is derived from it (`gen(R1)+1`), NOT from the root
+ *   `original` (which carries no resume-generation tag and would reset to 1
+ *   every escalation cycle, defeating MAX_RESUME_GENERATIONS via the Lead path).
+ * @param maxGenerations passed in (rather than imported from heartbeat.ts) to
+ *   avoid a circular import — heartbeat.ts already imports this module.
+ */
+export function createRerouteDecisionTask(args: {
+  original: AgentTask;
+  staleResume: AgentTask;
+  reason: ResumeReason;
+  maxGenerations: number;
+}): CreateRerouteDecisionResult {
+  const { original, staleResume, reason, maxGenerations } = args;
+
+  const leadAgent = getLeadAgent();
+  if (!leadAgent) return { kind: "skipped", reason: "lead_not_found" };
+
+  // Idempotency: a prior sweep may already have escalated this original.
+  if (hasNonTerminalRerouteDecisionChild(original.id)) {
+    return { kind: "skipped", reason: "duplicate_exists" };
+  }
+
+  const crashedAgent = original.agentId ? getAgentById(original.agentId) : null;
+  const agentName = crashedAgent?.name || original.agentId?.slice(0, 8) || "unknown";
+  const identitySlice = crashedAgent?.identityMd
+    ? `${crashedAgent.identityMd.slice(0, 500)}${crashedAgent.identityMd.length > 500 ? "..." : ""}`
+    : "(no identity recorded)";
+  const attachmentsBlock = formatAttachmentsBlock(getTaskAttachments(original.id));
+
+  const decision = resolveTemplate("task.reroute.decision", {
+    original_agent_name: agentName,
+    original_agent_identity: identitySlice,
+    original_task_id: original.id,
+    reason,
+    task_desc: original.task.slice(0, 200),
+    // Derive from the FAILED PIN (staleResume), not `original` (the root with no
+    // generation tag) — otherwise every escalation resets to gen 1 and the
+    // MAX_RESUME_GENERATIONS cap is never reached on the Lead path.
+    generation_next: getNextResumeGeneration(staleResume),
+    max_generations: maxGenerations,
+    artifacts_block: attachmentsBlock,
+  });
+
+  // Lead-owned `pending` decision task (createTaskExtended derives `pending`
+  // from a set agentId). Slack/VCS/etc. context is inherited from the original
+  // via parentTaskId. taskType is the distinct "reroute-decision" marker.
+  const created = createTaskExtended(decision.text, {
+    agentId: leadAgent.id,
+    creatorAgentId: original.creatorAgentId,
+    source: "system",
+    taskType: "reroute-decision",
+    tags: ["reroute-decision"],
+    priority: Math.min(100, (original.priority ?? 50) + 10),
+    parentTaskId: original.id,
+    // Inherit Slack/VCS context from the original, but NOT its outputSchema: this
+    // is a control-plane task the Lead completes by re-delegating via send-task,
+    // not by producing the original work's structured output. Inheriting it would
+    // make store-progress reject the Lead's completion and strand the decision
+    // (blocking further escalation via the duplicate-decision guard) — DES-523.
+    inheritParentOutputSchema: false,
+  });
+
+  return { kind: "created", task: created };
+}

package/src/tests/claude-adapter-binary.test.ts

@@ -34,6 +34,7 @@ import {
   parseClaudeBridgeEnabled,
   preseedClaudeTrustDialog,
   resolveClaudeBinary,
+  resolveClaudeBinaryArgv,
   resolveClaudeBridgeEnabled,
 } from "../providers/claude-adapter";
 import type { ProviderSessionConfig } from "../providers/types";
@@ -217,6 +218,59 @@ describe("SWARM_USE_CLAUDE_BRIDGE boolean parsing", () => {
   });
 });
 
+describe("resolveClaudeBinaryArgv — claude-bridge requires an OAuth token", () => {
+  test("bridge requested + OAuth token present → routes to claude-bridge", () => {
+    const r = resolveClaudeBinaryArgv(
+      { SWARM_USE_CLAUDE_BRIDGE: "true", CLAUDE_CODE_OAUTH_TOKEN: "sk-ant-oat01-x" },
+      {},
+    );
+    expect(r.useClaudeBridge).toBe(true);
+    expect(r.argv).toEqual(["claude-bridge"]);
+    expect(r.bridgeRequestedWithoutOAuth).toBe(false);
+  });
+
+  test("bridge requested + no OAuth (only API key) → falls back to stock claude", () => {
+    const r = resolveClaudeBinaryArgv(
+      { SWARM_USE_CLAUDE_BRIDGE: "true", ANTHROPIC_API_KEY: "sk-ant-api" },
+      {},
+    );
+    expect(r.useClaudeBridge).toBe(false);
+    expect(r.argv).toEqual(["claude"]);
+    expect(r.bridgeRequestedWithoutOAuth).toBe(true);
+  });
+
+  test("bridge requested + no creds at all → stock claude, flag set", () => {
+    const r = resolveClaudeBinaryArgv({ SWARM_USE_CLAUDE_BRIDGE: "1" }, {});
+    expect(r.useClaudeBridge).toBe(false);
+    expect(r.bridgeRequestedWithoutOAuth).toBe(true);
+  });
+
+  test("OAuth token from fallbackEnv (container env) also enables the bridge", () => {
+    const r = resolveClaudeBinaryArgv(
+      { SWARM_USE_CLAUDE_BRIDGE: "true" },
+      { CLAUDE_CODE_OAUTH_TOKEN: "sk-ant-oat01-fallback" },
+    );
+    expect(r.useClaudeBridge).toBe(true);
+    expect(r.bridgeRequestedWithoutOAuth).toBe(false);
+  });
+
+  test("whitespace-only OAuth token does not count as present", () => {
+    const r = resolveClaudeBinaryArgv(
+      { SWARM_USE_CLAUDE_BRIDGE: "true", CLAUDE_CODE_OAUTH_TOKEN: "   " },
+      {},
+    );
+    expect(r.useClaudeBridge).toBe(false);
+    expect(r.bridgeRequestedWithoutOAuth).toBe(true);
+  });
+
+  test("bridge not requested → never flagged, stock claude", () => {
+    const r = resolveClaudeBinaryArgv({ CLAUDE_CODE_OAUTH_TOKEN: "sk-ant-oat01-x" }, {});
+    expect(r.useClaudeBridge).toBe(false);
+    expect(r.bridgeRequestedWithoutOAuth).toBe(false);
+    expect(r.argv).toEqual(["claude"]);
+  });
+});
+
 describe("preseedClaudeTrustDialog", () => {
   let homeDir: string;
 
@@ -581,6 +635,26 @@ describe("CLAUDE_BINARY env override", () => {
 
     expect(spawnedArgs[0][0]).toBe("claude");
   });
+
+  test("SWARM_USE_CLAUDE_BRIDGE=true without OAuth token falls back to stock claude", async () => {
+    const origApiKey = process.env.ANTHROPIC_API_KEY;
+    delete process.env.CLAUDE_CODE_OAUTH_TOKEN;
+    process.env.ANTHROPIC_API_KEY = "sk-ant-test";
+    process.env.SWARM_USE_CLAUDE_BRIDGE = "true";
+    try {
+      const adapter = new ClaudeAdapter();
+      await adapter.createSession(makeConfig());
+      // No OAuth token → bridge is skipped, stock claude is used (Claude Code
+      // authenticates fine from ANTHROPIC_API_KEY; the bridge can't).
+      expect(spawnedArgs[0][0]).toBe("claude");
+    } finally {
+      if (origApiKey === undefined) {
+        delete process.env.ANTHROPIC_API_KEY;
+      } else {
+        process.env.ANTHROPIC_API_KEY = origApiKey;
+      }
+    }
+  });
 });
 
 describe("Claude Bridge tmux fail-fast gate", () => {