@app-vitals/agent-runtime 0.0.1 → 0.1.0

package/slack-socket-mode-ping.integration.test.ts

@@ -0,0 +1,137 @@
+/**
+ * agent/src/runtime/slack-socket-mode-ping.integration.test.ts
+ *
+ * Regression coverage for the fleet-wide Slack reconnect-loop incident that
+ * followed the @slack/bolt 4.7.3 -> 5.0.0 bump (SSB-1.1, #3006): Bolt 5's
+ * bundled @slack/socket-mode@3.x builds its whole ping/pong heartbeat
+ * (SlackWebSocket's monitorPingToSlack / monitorPingFromSlack) on the real
+ * `undici` package's module-level `ping()` helper and its
+ * `undici:websocket:ping` / `undici:websocket:pong` diagnostics_channel
+ * events. Bun always intercepts the bare "undici" specifier with its own
+ * built-in polyfill — even though the real package is installed right
+ * alongside it — and that polyfill implements neither API
+ * (oven-sh/bun#37110, root-caused and reproduced by Bun's own team; fix in
+ * progress at PR #37111, unmerged as of this writing). Under Bun, every
+ * client-side ping tick threw `undici_1.ping is not a function` and
+ * immediately disconnected — a continuous ~5-7s reconnect loop across the
+ * whole agent fleet, not an intermittent Slack-side issue.
+ *
+ * patches/@slack%2Fsocket-mode@3.0.1.patch (see package.json
+ * `patchedDependencies`) fixes this by requiring `undici/index.js` (a
+ * subpath, which Bun's specifier interception does not match) instead of
+ * bare `"undici"` — resolving the real, complete undici package that
+ * already satisfies this file's own `peerDependencies: { undici: "^7.0.0"
+ * }` and sits right there as a sibling in its own resolved node_modules.
+ *
+ * No existing suite would catch a regression here:
+ *   - slack.integration.test.ts / slack-bolt-client.integration.test.ts
+ *     construct a real @slack/bolt App but never open a live socket-mode
+ *     connection, so they never reach SlackWebSocket's ping/pong cycle.
+ *   - A unit test mocking the websocket/undici surface would pass
+ *     regardless of which `undici` Bun actually resolves at runtime — the
+ *     whole failure mode is specific to Bun's real, unmocked module
+ *     resolution.
+ *
+ * This test opens a REAL local WebSocket server and drives @slack/bolt's
+ * actual bundled @slack/socket-mode's SlackWebSocket against it — resolved
+ * via require.resolve anchored at @slack/bolt's own location, so it
+ * exercises the exact same file and dependency resolution Bolt uses in
+ * production — asserting both ping directions succeed and the connection
+ * survives multiple ping/pong cycles without disconnecting.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { EventEmitter } from "node:events";
+import { WebSocketServer } from "ws";
+
+type SlackWebSocketCtor = new (options: {
+  url: string;
+  client: EventEmitter;
+  logger: {
+    getLevel: () => string;
+    debug: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+  };
+  pingInterval?: number;
+  clientPingTimeoutMS?: number;
+  serverPingTimeoutMS?: number;
+}) => {
+  connect: () => Promise<void>;
+  disconnect: () => void;
+};
+
+function resolveSlackWebSocket(): SlackWebSocketCtor {
+  const boltEntry = require.resolve("@slack/bolt");
+  const swPath = require.resolve(
+    "@slack/socket-mode/dist/src/SlackWebSocket.js",
+    {
+      paths: [boltEntry],
+    },
+  );
+  // biome-ignore lint/suspicious/noExplicitAny: dynamic require of an internal dist file
+  return (require(swPath) as any).SlackWebSocket;
+}
+
+describe("@slack/socket-mode SlackWebSocket — ping/pong heartbeat under Bun", () => {
+  test("client ping, server ping, and pong detection all work without disconnecting", async () => {
+    const server = new WebSocketServer({ port: 0 });
+    await new Promise<void>((resolve) => server.once("listening", resolve));
+    const port = (server.address() as { port: number }).port;
+
+    let serverGotClientPing = false;
+    let serverSentPing = false;
+    server.on("connection", (ws) => {
+      ws.on("ping", () => {
+        serverGotClientPing = true;
+      });
+      // Simulate Slack's own server-initiated pings.
+      const interval = setInterval(() => {
+        serverSentPing = true;
+        ws.ping(Buffer.from("srv"));
+      }, 300);
+      ws.on("close", () => clearInterval(interval));
+    });
+
+    const SlackWebSocket = resolveSlackWebSocket();
+    const client = new EventEmitter();
+    let disconnected = false;
+    client.on("close", () => {
+      disconnected = true;
+    });
+
+    const errors: string[] = [];
+    const sw = new SlackWebSocket({
+      url: `ws://localhost:${port}`,
+      client,
+      logger: {
+        getLevel: () => "info",
+        debug: () => {},
+        info: () => {},
+        warn: () => {},
+        error: (m: unknown) => {
+          errors.push(String(m));
+        },
+      },
+      pingInterval: 300,
+      clientPingTimeoutMS: 900,
+      serverPingTimeoutMS: 1500,
+    });
+
+    try {
+      await sw.connect();
+      // Long enough to cross several ping intervals in both directions —
+      // the original bug disconnected on the very first tick.
+      await new Promise((r) => setTimeout(r, 2000));
+
+      expect(errors).toEqual([]);
+      expect(serverGotClientPing).toBe(true);
+      expect(serverSentPing).toBe(true);
+      expect(disconnected).toBe(false);
+    } finally {
+      sw.disconnect();
+      server.close();
+    }
+  });
+});

package/slack-startup.ts

@@ -0,0 +1,170 @@
+/**
+ * agent/src/runtime/slack-startup.ts
+ *
+ * Decision logic + live-client box for (re)starting the Slack Bolt Socket
+ * Mode app once credentials are available — whether that happens at boot
+ * (Step 7 in index.ts) or later, when syncConfig() picks up a
+ * SLACK_BOT_TOKEN/SLACK_APP_TOKEN pair that was saved to the admin DB after
+ * the pod already started.
+ *
+ * Why this exists: before this module, both the Bolt `app` and the `slack`
+ * WebClient were built once at boot from a static config snapshot taken
+ * before syncConfig() ever ran. If credentials arrived even a few seconds
+ * late (a plausible race during provisioning), the boot-time
+ * hasSlackCredentials() check failed once and the agent stayed in permanent
+ * offline mode — syncConfig() re-applies process.env every tick but had no
+ * hook to retry Slack startup. This module gives syncConfig() (and the boot
+ * path) a single, shared, testable decision: "are credentials live now, and
+ * has Bolt not already started? If so, start it — exactly once."
+ *
+ * Kept dependency-injected and I/O-free itself (matches the project's
+ * no-`mock.module()` isolation rule) — real Slack/Bolt/DM calls are injected
+ * by the caller (index.ts), so this module's own tests use fakes/spies
+ * instead of hitting real Slack. Mirrors agent-repos-ref.ts /
+ * agent-slack-membership-ref.ts's get/set-ref style for the live client box,
+ * and the same style is reused here for the start-in-flight guard so no
+ * module-scope mutable state leaks across test cases (each test constructs
+ * its own guard via createSlackStartGuard()).
+ */
+
+import type { WebClient } from "@slack/web-api";
+
+/** Minimal shape `startSlackIfPossible` needs from a started Bolt App. */
+export interface StartableSlackApp {
+  start(): Promise<unknown>;
+}
+
+export interface SlackClientRef {
+  /** Returns the current live Slack WebClient, or undefined if Slack hasn't started yet. */
+  get(): WebClient | undefined;
+  /** Replaces the current live Slack WebClient. */
+  set(client: WebClient | undefined): void;
+}
+
+/** Creates a new, independent Slack client ref defaulting to undefined (no client yet). */
+export function createSlackClientRef(): SlackClientRef {
+  let client: WebClient | undefined;
+
+  return {
+    get(): WebClient | undefined {
+      return client;
+    },
+    set(next: WebClient | undefined): void {
+      client = next;
+    },
+  };
+}
+
+/**
+ * The process-wide Slack client ref. index.ts's cronDeps.slack and the
+ * back-online DM call site read through `.get()` rather than closing over a
+ * boot-time `const slack`, so a late (re)start via startSlackIfPossible()
+ * makes both see a live client without an agent restart.
+ */
+export const slackClientRef: SlackClientRef = createSlackClientRef();
+
+/**
+ * Guards startSlackIfPossible() against overlapping callers — e.g. two
+ * syncConfig() ticks racing because syncConfig() is dispatched via an
+ * unawaited setInterval, or a boot call racing a config-sync call. Kept as
+ * its own tiny ref (rather than a module-scope `let`) so tests can construct
+ * an independent, disposable guard instead of mutating shared state that
+ * would otherwise leak between test cases.
+ */
+interface SlackStartGuard {
+  isInFlight(): boolean;
+  set(inFlight: boolean): void;
+}
+
+export function createSlackStartGuard(): SlackStartGuard {
+  let inFlight = false;
+  return {
+    isInFlight: () => inFlight,
+    set: (next: boolean) => {
+      inFlight = next;
+    },
+  };
+}
+
+/**
+ * The process-wide start-in-flight guard used by index.ts's two real call
+ * sites (boot + syncConfig()). A single shared instance is required in
+ * production so a boot-time start and a config-sync-tick start can't race
+ * each other; tests should construct their own via createSlackStartGuard()
+ * instead of reusing this singleton.
+ */
+const slackStartGuard: SlackStartGuard = createSlackStartGuard();
+
+export interface StartSlackDeps {
+  /** Reads live env-derived Slack config (botToken/appToken/signingSecret) at call time — not a static snapshot. */
+  buildSlackConfig: () => {
+    botToken: string;
+    appToken: string;
+    signingSecret: string;
+  };
+  /** Same credential-completeness check used at boot — see slack.ts. */
+  hasSlackCredentials: (cfg: { botToken: string; appToken: string }) => boolean;
+  /** True once Bolt has already been started (by any prior call, boot or config-sync). */
+  isAppStarted: () => boolean;
+  /** Builds (but does not start) the Bolt app from live config. */
+  createSlackApp: () => StartableSlackApp;
+  /** Records the started Bolt app so isAppStarted() reflects it on the next call. */
+  setApp: (app: StartableSlackApp) => void;
+  /** Builds the WebClient to publish via the slack client ref once credentials are confirmed live. */
+  createSlackClient: () => WebClient;
+  setSlackClient: (client: WebClient | undefined) => void;
+  markSlackConnected: () => void;
+  sendBackOnlineDm: (client: WebClient) => Promise<void>;
+  /** Start-in-flight guard — defaults to the process-wide singleton; tests inject their own. */
+  guard?: SlackStartGuard;
+}
+
+/**
+ * Attempts to start the Slack Bolt app if — and only if — credentials are
+ * complete right now AND Bolt hasn't already been started. Safe to call on
+ * every boot attempt and every syncConfig() tick: a no-op when credentials
+ * are still incomplete, and a no-op once a prior call already started Bolt.
+ *
+ * Returns true iff this call actually started Bolt; false for every no-op
+ * path (incomplete credentials, already started, or a racing call that lost
+ * the in-flight guard).
+ *
+ * Errors from `createSlackApp()`/`app.start()` propagate to the caller (not
+ * swallowed here) so index.ts's two call sites can each decide how to
+ * handle a start failure consistently with their surrounding context — see
+ * the call sites in index.ts for the boot-vs-config-sync tradeoff.
+ */
+export async function startSlackIfPossible(
+  deps: StartSlackDeps,
+): Promise<boolean> {
+  const guard = deps.guard ?? slackStartGuard;
+
+  if (guard.isInFlight()) return false;
+  if (deps.isAppStarted()) return false;
+
+  const slackConfig = deps.buildSlackConfig();
+  if (!deps.hasSlackCredentials(slackConfig)) return false;
+
+  guard.set(true);
+  try {
+    // Re-check after acquiring the guard in case another call already
+    // started Bolt between the check above and here — defense in depth on
+    // top of the guard itself (JS has no preemption between the isInFlight
+    // check and the set(true) above, so this branch is unreachable today,
+    // but keeps the invariant obvious even if that ordering ever changes).
+    if (deps.isAppStarted()) return false;
+
+    const app = deps.createSlackApp();
+    await app.start();
+    deps.setApp(app);
+    deps.markSlackConnected();
+
+    const client = deps.createSlackClient();
+    deps.setSlackClient(client);
+
+    await deps.sendBackOnlineDm(client);
+    return true;
+  } finally {
+    guard.set(false);
+  }
+}

package/slack-startup.unit.test.ts

@@ -0,0 +1,300 @@
+/**
+ * agent/src/runtime/slack-startup.unit.test.ts
+ *
+ * Unit tests for startSlackIfPossible() and the Slack client ref — pure
+ * logic, no I/O. All Slack/Bolt/DM calls are fakes/spies injected via
+ * StartSlackDeps; no real network or `mock.module()` usage.
+ */
+
+import { describe, expect, it } from "bun:test";
+import type { WebClient } from "@slack/web-api";
+import {
+  createSlackClientRef,
+  createSlackStartGuard,
+  type StartableSlackApp,
+  type StartSlackDeps,
+  slackClientRef,
+  startSlackIfPossible,
+} from "./slack-startup.ts";
+
+/** Builds a minimal fake WebClient stand-in for identity/shape assertions. */
+function fakeClient(tag: string): WebClient {
+  return { fake: tag } as unknown as WebClient;
+}
+
+/**
+ * Builds a fresh, fully-independent set of fakes for one test case —
+ * mirrors production semantics (isAppStarted flips true only after setApp)
+ * but with no real Slack I/O, and returns spy call counters for assertions.
+ */
+function buildFakeDeps(overrides?: { botToken?: string; appToken?: string }) {
+  let appStarted: StartableSlackApp | undefined;
+  const calls = {
+    createSlackApp: 0,
+    appStart: 0,
+    setApp: 0,
+    markSlackConnected: 0,
+    createSlackClient: 0,
+    setSlackClient: 0,
+    sendBackOnlineDm: 0,
+  };
+
+  const clientRef = createSlackClientRef();
+  const guard = createSlackStartGuard();
+
+  const deps: StartSlackDeps = {
+    buildSlackConfig: () => ({
+      botToken: overrides?.botToken ?? "xoxb-live",
+      appToken: overrides?.appToken ?? "xapp-live",
+      signingSecret: "shh",
+    }),
+    hasSlackCredentials: (cfg) =>
+      cfg.botToken.trim() !== "" && cfg.appToken.trim() !== "",
+    isAppStarted: () => appStarted !== undefined,
+    createSlackApp: () => {
+      calls.createSlackApp++;
+      return {
+        start: async () => {
+          calls.appStart++;
+        },
+      };
+    },
+    setApp: (app) => {
+      calls.setApp++;
+      appStarted = app;
+    },
+    createSlackClient: () => {
+      calls.createSlackClient++;
+      // A minimal stand-in — startSlackIfPossible only threads this through
+      // to setSlackClient/sendBackOnlineDm, never calls real WebClient methods.
+      return fakeClient("started");
+    },
+    setSlackClient: (client) => {
+      calls.setSlackClient++;
+      clientRef.set(client);
+    },
+    markSlackConnected: () => {
+      calls.markSlackConnected++;
+    },
+    sendBackOnlineDm: async () => {
+      calls.sendBackOnlineDm++;
+    },
+    guard,
+  };
+
+  return {
+    deps,
+    calls,
+    clientRef,
+    guard,
+    isStarted: () => appStarted !== undefined,
+  };
+}
+
+describe("startSlackIfPossible", () => {
+  it("credentials complete on a later tick (not boot) triggers exactly one Slack start", async () => {
+    const { deps, calls, clientRef } = buildFakeDeps();
+
+    const started = await startSlackIfPossible(deps);
+
+    expect(started).toBe(true);
+    expect(calls.createSlackApp).toBe(1);
+    expect(calls.appStart).toBe(1);
+    expect(calls.setApp).toBe(1);
+    expect(calls.markSlackConnected).toBe(1);
+    expect(calls.createSlackClient).toBe(1);
+    expect(calls.sendBackOnlineDm).toBe(1);
+    expect(clientRef.get()).toBeDefined();
+    expect((clientRef.get() as unknown as { fake: string }).fake).toBe(
+      "started",
+    );
+  });
+
+  it("a later tick with the app already started does not re-trigger a start", async () => {
+    const { deps, calls } = buildFakeDeps();
+
+    const first = await startSlackIfPossible(deps);
+    const second = await startSlackIfPossible(deps);
+
+    expect(first).toBe(true);
+    expect(second).toBe(false);
+    expect(calls.createSlackApp).toBe(1);
+    expect(calls.appStart).toBe(1);
+    expect(calls.setApp).toBe(1);
+    expect(calls.markSlackConnected).toBe(1);
+    expect(calls.sendBackOnlineDm).toBe(1);
+  });
+
+  it("a tick with still-incomplete credentials (missing app token) does not attempt a start", async () => {
+    const { deps, calls } = buildFakeDeps({
+      botToken: "xoxb-live",
+      appToken: "",
+    });
+
+    const started = await startSlackIfPossible(deps);
+
+    expect(started).toBe(false);
+    expect(calls.createSlackApp).toBe(0);
+    expect(calls.appStart).toBe(0);
+    expect(calls.setApp).toBe(0);
+    expect(calls.markSlackConnected).toBe(0);
+    expect(calls.createSlackClient).toBe(0);
+    expect(calls.sendBackOnlineDm).toBe(0);
+  });
+
+  it("a tick with still-incomplete credentials (missing bot token) does not attempt a start", async () => {
+    const { deps, calls } = buildFakeDeps({
+      botToken: "",
+      appToken: "xapp-live",
+    });
+
+    const started = await startSlackIfPossible(deps);
+
+    expect(started).toBe(false);
+    expect(calls.createSlackApp).toBe(0);
+    expect(calls.appStart).toBe(0);
+  });
+
+  it("a tick with both credentials missing does not attempt a start", async () => {
+    const { deps, calls } = buildFakeDeps({ botToken: "", appToken: "" });
+
+    const started = await startSlackIfPossible(deps);
+
+    expect(started).toBe(false);
+    expect(calls.createSlackApp).toBe(0);
+  });
+
+  it("overlapping/concurrent calls (two ticks racing before the first app.start() resolves) do not double-start", async () => {
+    const { deps, calls } = buildFakeDeps();
+
+    // Make app.start() hang until we let both calls race against it, so the
+    // second call's isAppStarted() check still sees "not started" while the
+    // first is mid-flight — the in-flight guard, not timing luck, must be
+    // what prevents a double start.
+    let releaseStart: () => void = () => {};
+    const startGate = new Promise<void>((resolve) => {
+      releaseStart = resolve;
+    });
+    deps.createSlackApp = () => {
+      calls.createSlackApp++;
+      return {
+        start: async () => {
+          await startGate;
+          calls.appStart++;
+        },
+      };
+    };
+
+    const firstCall = startSlackIfPossible(deps);
+    const secondCall = startSlackIfPossible(deps);
+
+    releaseStart();
+    const [first, second] = await Promise.all([firstCall, secondCall]);
+
+    expect([first, second].filter(Boolean)).toHaveLength(1);
+    expect(calls.createSlackApp).toBe(1);
+    expect(calls.appStart).toBe(1);
+    expect(calls.setApp).toBe(1);
+    expect(calls.markSlackConnected).toBe(1);
+    expect(calls.sendBackOnlineDm).toBe(1);
+  });
+
+  it("app already started before syncConfig's first tick (boot succeeded) is a no-op", async () => {
+    const { deps, calls } = buildFakeDeps();
+
+    // Simulate boot having already started Bolt.
+    await startSlackIfPossible(deps);
+    calls.createSlackApp = 0;
+    calls.appStart = 0;
+    calls.setApp = 0;
+    calls.markSlackConnected = 0;
+    calls.sendBackOnlineDm = 0;
+
+    const started = await startSlackIfPossible(deps);
+
+    expect(started).toBe(false);
+    expect(calls.createSlackApp).toBe(0);
+    expect(calls.appStart).toBe(0);
+    expect(calls.setApp).toBe(0);
+    expect(calls.markSlackConnected).toBe(0);
+    expect(calls.sendBackOnlineDm).toBe(0);
+  });
+
+  it("errors from app.start() propagate to the caller rather than being swallowed", async () => {
+    const { deps } = buildFakeDeps();
+    deps.createSlackApp = () => ({
+      start: async () => {
+        throw new Error("boom");
+      },
+    });
+
+    await expect(startSlackIfPossible(deps)).rejects.toThrow("boom");
+  });
+
+  it("errors from app.start() release the in-flight guard so a subsequent retry can proceed", async () => {
+    const { deps, calls, guard } = buildFakeDeps();
+    deps.createSlackApp = () => ({
+      start: async () => {
+        throw new Error("boom");
+      },
+    });
+
+    await expect(startSlackIfPossible(deps)).rejects.toThrow("boom");
+    expect(guard.isInFlight()).toBe(false);
+
+    // Retry with working deps — should succeed since the app never actually started.
+    deps.createSlackApp = () => {
+      calls.createSlackApp++;
+      return {
+        start: async () => {
+          calls.appStart++;
+        },
+      };
+    };
+    const started = await startSlackIfPossible(deps);
+    expect(started).toBe(true);
+  });
+});
+
+describe("SlackClientRef", () => {
+  it("createSlackClientRef() defaults to undefined (no client yet)", () => {
+    const ref = createSlackClientRef();
+    expect(ref.get()).toBeUndefined();
+  });
+
+  it("set() replaces the current client, reflected by the next get()", () => {
+    const ref = createSlackClientRef();
+    const client = fakeClient("a");
+
+    ref.set(client);
+    expect(ref.get()).toBe(client);
+  });
+
+  it("multiple independent ref instances don't share state", () => {
+    const refA = createSlackClientRef();
+    const refB = createSlackClientRef();
+    const client = fakeClient("a");
+
+    refA.set(client);
+
+    expect(refA.get()).toBe(client);
+    expect(refB.get()).toBeUndefined();
+  });
+});
+
+describe("slackClientRef (process-wide singleton)", () => {
+  it("is a working ref that reflects set() through get(), independent of createSlackClientRef() instances", () => {
+    const independent = createSlackClientRef();
+    const leakClient = fakeClient("should-not-leak");
+    independent.set(leakClient);
+
+    const realClient = fakeClient("real");
+    slackClientRef.set(realClient);
+
+    expect(slackClientRef.get()).toBe(realClient);
+    expect(independent.get()).toBe(leakClient);
+
+    // Reset the process-wide singleton so this test doesn't leak state into siblings.
+    slackClientRef.set(undefined);
+  });
+});

package/slack-thread-status-tracker.ts

@@ -0,0 +1,70 @@
+/**
+ * agent/src/runtime/slack-thread-status-tracker.ts
+ *
+ * Per-thread reference counter used by all three Slack handlers in
+ * slack.ts (app.message, app_mention, reaction_added) around their own
+ * SlackProgress instance's start()/finish() calls.
+ *
+ * Each handler constructs its own SlackProgress and calls start()/finish()
+ * independently around its own runner() call, unconditionally — every
+ * message gets its own independent chat.startStream/appendStream/stopStream
+ * lifecycle regardless of the refcount. enter()/exit() are ALWAYS called by
+ * every handler — every enter() needs a matching exit(), or the refcount
+ * leaks upward forever — but their boolean return values are used only to
+ * select (STS2-1.1):
+ *
+ *   (a) the seed card's title ("Queued…" when enter() signals another
+ *       message on this thread is already in flight, "Thinking…"
+ *       otherwise), and
+ *   (b) the session_status stopStream closes with ("processing" when
+ *       exit() signals other messages are still in flight, "active" only
+ *       for the genuine last one — see SlackProgress.finish() in
+ *       slack-progress.ts).
+ *
+ * Construct one instance per createSlackApp() call (closure-scoped) — never
+ * module-level — so multiple app instances (e.g. in tests) stay isolated
+ * from each other's refcount state.
+ */
+
+export class ThreadStatusTracker {
+  private readonly counts = new Map<string, number>();
+
+  /**
+   * Marks a run as starting for `key`. Always called. Returns true only
+   * when this is the transition from 0 in-flight runs to 1 — false for any
+   * overlapping run beyond the first. Callers call progress.start()
+   * unconditionally and use this only to pick the seed card's title (see
+   * the module doc comment).
+   */
+  enter(key: string): boolean {
+    const current = this.counts.get(key) ?? 0;
+    const next = current + 1;
+    this.counts.set(key, next);
+    return current === 0;
+  }
+
+  /**
+   * Marks a run as finished for `key`. Always called — every enter() needs
+   * a matching exit(). Returns true only when this is the transition from 1
+   * in-flight run to 0 — false while other runs are still in flight.
+   * Callers call progress.finish() unconditionally and use this only to
+   * pick the session_status stopStream closes with (see the module doc
+   * comment).
+   *
+   * Calling exit() on a key that is already at 0 (never entered, or already
+   * fully drained) is a no-op that returns false rather than going negative
+   * or throwing.
+   */
+  exit(key: string): boolean {
+    const current = this.counts.get(key) ?? 0;
+    if (current === 0) return false;
+    const next = current - 1;
+    if (next === 0) {
+      // Clean up so the map doesn't grow unbounded with fully-drained keys.
+      this.counts.delete(key);
+      return true;
+    }
+    this.counts.set(key, next);
+    return false;
+  }
+}