@desplega.ai/agent-swarm 1.69.0 → 1.70.0

package/src/slack/actions.ts

@@ -1,12 +1,7 @@
 import type { App } from "@slack/bolt";
-import {
-  cancelTask,
-  createTaskExtended,
-  getAgentById,
-  getLeadAgent,
-  getTaskById,
-  resolveUser,
-} from "../be/db";
+import { cancelTask, getAgentById, getLeadAgent, getTaskById, resolveUser } from "../be/db";
+import { slackContextKey } from "../tasks/context-key";
+import { createTaskWithSiblingAwareness } from "../tasks/sibling-awareness";
 import { buildCancelledBlocks, getTaskLink } from "./blocks";
 
 export function registerActionHandlers(app: App): void {
@@ -73,7 +68,7 @@ export function registerActionHandlers(app: App): void {
 
     const lead = getLeadAgent();
     const requestedByUserId = resolveUser({ slackUserId: body.user.id })?.id;
-    const followUpTask = createTaskExtended(followUpText, {
+    const followUpTask = createTaskWithSiblingAwareness(followUpText, {
       agentId: lead?.id,
       source: "slack",
       parentTaskId: taskId,
@@ -81,6 +76,12 @@ export function registerActionHandlers(app: App): void {
       slackThreadTs: originalTask.slackThreadTs,
       slackUserId: body.user.id,
       requestedByUserId,
+      contextKey: originalTask.slackThreadTs
+        ? slackContextKey({
+            channelId: originalTask.slackChannelId,
+            threadTs: originalTask.slackThreadTs,
+          })
+        : undefined,
     });
 
     const taskLink = getTaskLink(followUpTask.id);

package/src/slack/assistant.ts

@@ -1,12 +1,13 @@
 import { Assistant } from "@slack/bolt";
 import {
-  createTaskExtended,
   getAgentWorkingOnThread,
   getLeadAgent,
   getMostRecentTaskInThread,
   resolveUser,
 } from "../be/db";
 import { resolveTemplate } from "../prompts/resolver";
+import { slackContextKey } from "../tasks/context-key";
+import { createTaskWithSiblingAwareness } from "../tasks/sibling-awareness";
 import { bufferThreadMessage } from "./thread-buffer";
 // Side-effect import: registers all Slack event templates in the in-memory registry
 import "./templates";
@@ -82,7 +83,7 @@ export function createAssistant(): Assistant {
 
           // Otherwise, create a follow-up task for the working agent
           const latestTask = getMostRecentTaskInThread(channelId, threadTs);
-          createTaskExtended(messageText, {
+          createTaskWithSiblingAwareness(messageText, {
             agentId: workingAgent.id,
             source: "slack",
             slackChannelId: channelId,
@@ -90,6 +91,7 @@ export function createAssistant(): Assistant {
             slackUserId: userId,
             parentTaskId: latestTask?.id,
             requestedByUserId,
+            contextKey: slackContextKey({ channelId, threadTs }),
           });
 
           await safeSetStatus("Processing follow-up...");
@@ -114,25 +116,27 @@ export function createAssistant(): Assistant {
         const lead = getLeadAgent();
         if (!lead) {
           // No lead — still queue the task
-          createTaskExtended(messageText + channelContext, {
+          createTaskWithSiblingAwareness(messageText + channelContext, {
             source: "slack",
             slackChannelId: channelId,
             slackThreadTs: threadTs,
             slackUserId: userId,
             requestedByUserId,
+            contextKey: slackContextKey({ channelId, threadTs }),
           });
           const offlineResult = resolveTemplate("slack.assistant.offline", {});
           await say(offlineResult.text);
           return;
         }
 
-        createTaskExtended(messageText + channelContext, {
+        createTaskWithSiblingAwareness(messageText + channelContext, {
           agentId: lead.id,
           source: "slack",
           slackChannelId: channelId,
           slackThreadTs: threadTs,
           slackUserId: userId,
           requestedByUserId,
+          contextKey: slackContextKey({ channelId, threadTs }),
         });
         // setStatus shows typing indicator — watcher will post final result when done
       } catch (error) {

package/src/slack/handlers.ts

@@ -10,6 +10,8 @@ import {
   resolveUser,
 } from "../be/db";
 import { resolveTemplate } from "../prompts/resolver";
+import { slackContextKey } from "../tasks/context-key";
+import { createTaskWithSiblingAwareness } from "../tasks/sibling-awareness";
 import { workflowEventBus } from "../workflows/event-bus";
 import { buildTreeBlocks, type TreeNode } from "./blocks";
 import type { SlackFile } from "./files";
@@ -538,13 +540,14 @@ export function registerMessageHandler(app: App): void {
       }
 
       const lead = getLeadAgent();
-      createTaskExtended(fullTaskDescription, {
+      createTaskWithSiblingAwareness(fullTaskDescription, {
         agentId: lead?.id,
         source: "slack",
         slackChannelId: msg.channel,
         slackThreadTs: threadTs,
         slackUserId: msg.user,
         requestedByUserId,
+        contextKey: slackContextKey({ channelId: msg.channel, threadTs }),
       });
 
       await say({
@@ -610,7 +613,7 @@ export function registerMessageHandler(app: App): void {
       try {
         const latestTask = getMostRecentTaskInThread(msg.channel, threadTs);
         if (agent.isLead) {
-          const task = createTaskExtended(fullTaskDescription, {
+          const task = createTaskWithSiblingAwareness(fullTaskDescription, {
             agentId: agent.id,
             source: "slack",
             slackChannelId: msg.channel,
@@ -618,19 +621,21 @@ export function registerMessageHandler(app: App): void {
             slackUserId: msg.user,
             parentTaskId: latestTask?.id,
             requestedByUserId,
+            contextKey: slackContextKey({ channelId: msg.channel, threadTs }),
           });
           results.assigned.push({ agentName: agent.name, taskId: task.id });
           continue;
         }
 
         // Workers receive tasks as before
-        const task = createTaskExtended(fullTaskDescription, {
+        const task = createTaskWithSiblingAwareness(fullTaskDescription, {
           agentId: agent.id,
           source: "slack",
           slackChannelId: msg.channel,
           slackThreadTs: threadTs,
           slackUserId: msg.user,
           requestedByUserId,
+          contextKey: slackContextKey({ channelId: msg.channel, threadTs }),
         });
 
         // Check if agent has an in-progress task in this thread (queued follow-up)

package/src/slack/thread-buffer.ts

@@ -1,9 +1,7 @@
-import {
-  createTaskExtended,
-  getLatestActiveTaskInThread,
-  getLeadAgent,
-  getMostRecentTaskInThread,
-} from "../be/db";
+import { getLatestActiveTaskInThread, getLeadAgent, getMostRecentTaskInThread } from "../be/db";
+import { createAdditiveBuffer } from "../tasks/additive-buffer";
+import { slackContextKey } from "../tasks/context-key";
+import { createTaskWithSiblingAwareness } from "../tasks/sibling-awareness";
 import { getSlackApp } from "./app";
 import { buildBufferFlushBlocks } from "./blocks";
 import { registerTreeMessage } from "./watcher";
@@ -12,24 +10,30 @@ interface BufferedMessage {
   text: string;
   userId: string;
   ts: string;
-}
-
-interface BufferedThread {
   channelId: string;
   threadTs: string;
-  messages: BufferedMessage[];
-  timer: Timer;
-  slackUserId: string; // original requester (first message sender)
 }
 
-const threadBuffers = new Map<string, BufferedThread>();
-
 const BUFFER_TIMEOUT_MS = Number(process.env.ADDITIVE_SLACK_BUFFER_MS) || 10_000;
 
 function makeKey(channelId: string, threadTs: string): string {
   return `${channelId}:${threadTs}`;
 }
 
+function splitKey(key: string): { channelId: string; threadTs: string } | null {
+  const idx = key.indexOf(":");
+  if (idx === -1) return null;
+  return { channelId: key.slice(0, idx), threadTs: key.slice(idx + 1) };
+}
+
+const slackBuffer = createAdditiveBuffer<BufferedMessage>({
+  timeoutMs: BUFFER_TIMEOUT_MS,
+  label: "slack-thread",
+  onFlush: async (items, key, reason) => {
+    await slackFlush(items, key, reason === "manual");
+  },
+});
+
 /**
  * Add a message to the thread buffer. Resets the debounce timer.
  */
@@ -40,43 +44,27 @@ export function bufferThreadMessage(
   userId: string,
   ts: string,
 ): void {
-  const key = makeKey(channelId, threadTs);
-  const existing = threadBuffers.get(key);
-
-  if (existing) {
-    // Append to existing buffer, reset timer
-    existing.messages.push({ text, userId, ts });
-    clearTimeout(existing.timer);
-    existing.timer = setTimeout(() => flushBuffer(key, false), BUFFER_TIMEOUT_MS);
-    console.log(
-      `[Slack] Buffer append: ${key} (${existing.messages.length} messages, timer reset to ${BUFFER_TIMEOUT_MS}ms)`,
-    );
-  } else {
-    // Create new buffer entry
-    const timer = setTimeout(() => flushBuffer(key, false), BUFFER_TIMEOUT_MS);
-    threadBuffers.set(key, {
-      channelId,
-      threadTs,
-      messages: [{ text, userId, ts }],
-      timer,
-      slackUserId: userId,
-    });
-    console.log(`[Slack] Buffer created: ${key} (timer set to ${BUFFER_TIMEOUT_MS}ms)`);
-  }
+  slackBuffer.enqueue(makeKey(channelId, threadTs), {
+    text,
+    userId,
+    ts,
+    channelId,
+    threadTs,
+  });
 }
 
 /**
  * Check if a thread currently has a pending buffer.
  */
 export function isThreadBuffered(channelId: string, threadTs: string): boolean {
-  return threadBuffers.has(makeKey(channelId, threadTs));
+  return slackBuffer.isBuffered(makeKey(channelId, threadTs));
 }
 
 /**
  * Get the number of messages currently in the buffer for a thread key.
  */
 export function getBufferMessageCount(key: string): number {
-  return threadBuffers.get(key)?.messages.length ?? 0;
+  return slackBuffer.count(key);
 }
 
 /**
@@ -84,12 +72,7 @@ export function getBufferMessageCount(key: string): number {
  * and flushes with immediate=true (no dependsOn).
  */
 export async function instantFlush(key: string): Promise<void> {
-  const buffer = threadBuffers.get(key);
-  if (buffer) {
-    clearTimeout(buffer.timer);
-    console.log(`[Slack] Instant flush triggered: ${key}`);
-  }
-  await flushBuffer(key, true);
+  await slackBuffer.instantFlush(key);
 }
 
 /**
@@ -130,27 +113,34 @@ async function getThreadContextForBuffer(channelId: string, threadTs: string): P
 }
 
 /**
- * Flush the buffer: concatenate messages, create task with optional dependency chaining.
- * @param key - The buffer key (channelId:threadTs)
- * @param immediate - If true, skip dependency chaining (used by !now)
+ * Flush the Slack thread buffer: concatenate messages, create task with optional
+ * dependency chaining.
  */
-async function flushBuffer(key: string, immediate = false): Promise<void> {
-  const buffer = threadBuffers.get(key);
-  if (!buffer || buffer.messages.length === 0) {
-    threadBuffers.delete(key);
+async function slackFlush(
+  items: BufferedMessage[],
+  key: string,
+  immediate: boolean,
+): Promise<void> {
+  if (items.length === 0) return;
+
+  const split = splitKey(key);
+  if (!split) {
+    console.warn(`[Slack] Buffer flush: malformed key ${key}`);
     return;
   }
+  const { channelId, threadTs } = split;
+  // Buffer is guaranteed to have at least one item — the first carries the
+  // original requester's userId (same semantics as the pre-refactor version).
+  const originalRequesterId = items[0]!.userId;
 
-  console.log(
-    `[Slack] Flushing buffer: ${key} (${buffer.messages.length} messages, immediate=${immediate})`,
-  );
+  console.log(`[Slack] Flushing buffer: ${key} (${items.length} messages, immediate=${immediate})`);
 
   // Build combined task description
-  const combinedText = buffer.messages.map((m) => m.text).join("\n---\n");
-  const description = `[Thread follow-up — ${buffer.messages.length} message(s) buffered]\n\n${combinedText}`;
+  const combinedText = items.map((m) => m.text).join("\n---\n");
+  const description = `[Thread follow-up — ${items.length} message(s) buffered]\n\n${combinedText}`;
 
   // Find the latest active task in this thread for dependency chaining
-  const latestActiveTask = getLatestActiveTaskInThread(buffer.channelId, buffer.threadTs);
+  const latestActiveTask = getLatestActiveTaskInThread(channelId, threadTs);
   if (latestActiveTask) {
     console.log(
       `[Slack] Dependency chaining: latest active task ${latestActiveTask.id} (status: ${latestActiveTask.status})`,
@@ -160,7 +150,7 @@ async function flushBuffer(key: string, immediate = false): Promise<void> {
   const lead = getLeadAgent();
 
   // Thread context for the task
-  const threadContext = await getThreadContextForBuffer(buffer.channelId, buffer.threadTs);
+  const threadContext = await getThreadContextForBuffer(channelId, threadTs);
   const fullDescription = threadContext
     ? `<thread_context>\n${threadContext}\n</thread_context>\n\n${description}`
     : description;
@@ -169,15 +159,16 @@ async function flushBuffer(key: string, immediate = false): Promise<void> {
   // Otherwise, depend on the latest active task so it queues naturally.
   const dependsOn = !immediate && latestActiveTask ? [latestActiveTask.id] : undefined;
 
-  const mostRecentTask = getMostRecentTaskInThread(buffer.channelId, buffer.threadTs);
-  const task = createTaskExtended(fullDescription, {
+  const mostRecentTask = getMostRecentTaskInThread(channelId, threadTs);
+  const task = createTaskWithSiblingAwareness(fullDescription, {
     agentId: lead?.id,
     source: "slack",
-    slackChannelId: buffer.channelId,
-    slackThreadTs: buffer.threadTs,
-    slackUserId: buffer.slackUserId,
+    slackChannelId: channelId,
+    slackThreadTs: threadTs,
+    slackUserId: originalRequesterId,
     dependsOn,
     parentTaskId: mostRecentTask?.id,
+    contextKey: slackContextKey({ channelId, threadTs }),
   });
 
   console.log(
@@ -189,18 +180,18 @@ async function flushBuffer(key: string, immediate = false): Promise<void> {
   if (app) {
     const hasDependency = !immediate && !!latestActiveTask;
     const blocks = buildBufferFlushBlocks({
-      messageCount: buffer.messages.length,
+      messageCount: items.length,
       taskId: task.id,
       hasDependency,
     });
     const fallbackText = hasDependency
-      ? `${buffer.messages.length} follow-up message(s) queued pending completion of current task`
-      : `${buffer.messages.length} follow-up message(s) batched into task`;
+      ? `${items.length} follow-up message(s) queued pending completion of current task`
+      : `${items.length} follow-up message(s) batched into task`;
 
     try {
       const result = await app.client.chat.postMessage({
-        channel: buffer.channelId,
-        thread_ts: buffer.threadTs,
+        channel: channelId,
+        thread_ts: threadTs,
         text: fallbackText,
         // biome-ignore lint/suspicious/noExplicitAny: Block Kit objects
         blocks: blocks as any,
@@ -208,7 +199,7 @@ async function flushBuffer(key: string, immediate = false): Promise<void> {
 
       // Register the batching message as the tree message for this task
       if (result.ts && task) {
-        registerTreeMessage(task.id, buffer.channelId, buffer.threadTs, result.ts);
+        registerTreeMessage(task.id, channelId, threadTs, result.ts);
         console.log(
           `[Slack] Registered batched task ${task.id.slice(0, 8)} tree message from buffer flush`,
         );
@@ -217,6 +208,4 @@ async function flushBuffer(key: string, immediate = false): Promise<void> {
       console.error("[Slack] Failed to post buffer flush feedback:", error);
     }
   }
-
-  threadBuffers.delete(key);
 }

package/src/tasks/additive-buffer.ts

@@ -0,0 +1,152 @@
+/**
+ * Generic additive/debounce buffer, keyed on `contextKey` (or any string key).
+ *
+ * Phase 2 of cross-ingress sibling-task awareness — research §5.
+ *
+ * Extracted from `src/slack/thread-buffer.ts` so any ingress (AgentMail,
+ * GitHub/GitLab issue comments, Linear comments — NOT schedule/workflow) can
+ * coalesce rapid follow-up inputs into a single task.
+ *
+ * The primitive is a factory: each caller owns its own buffer registry with
+ * its own flush callback. That keeps flush semantics ingress-specific while
+ * the debounce / append / count plumbing is shared.
+ *
+ * Behavior:
+ *   - `enqueue(key, item)` appends `item` to the in-memory buffer for `key`.
+ *   - The debounce timer is reset on every append.
+ *   - When the timer fires, `onFlush(items, key, reason="timer")` is called
+ *     with the accumulated list.
+ *   - `instantFlush(key)` fires the callback immediately with
+ *     `reason="manual"` and clears the buffer.
+ *   - `cancel(key)` drops the buffer without flushing (used by ingress when
+ *     the underlying context becomes irrelevant — e.g. user cancels).
+ *
+ * Concurrency: single-process, single-event-loop. No cross-instance locking.
+ * Flush callbacks run sequentially per key (the buffer is cleared BEFORE the
+ * callback fires, so re-enqueues during `onFlush` create a fresh buffer).
+ */
+
+export type BufferFlushReason = "timer" | "manual";
+
+export interface AdditiveBufferOptions<T> {
+  /**
+   * Debounce timeout. Resets on every append. When it elapses without new
+   * appends, `onFlush` is called.
+   */
+  timeoutMs: number;
+  /**
+   * Called with the accumulated items when the buffer flushes. Receives the
+   * `contextKey` the buffer was created under and a `reason` indicating
+   * whether this was a timer-driven flush or a manual (`instantFlush`) one.
+   *
+   * Errors thrown here are caught and logged — they do NOT re-enter the
+   * buffer, because the buffer has already been cleared by the time `onFlush`
+   * is called. Callers that need retry semantics must implement them inside
+   * `onFlush`.
+   */
+  onFlush: (items: T[], contextKey: string, reason: BufferFlushReason) => void | Promise<void>;
+  /**
+   * Optional label, used in log lines (`[buffer:${label}]`). Helps when
+   * multiple buffers exist in the same process.
+   */
+  label?: string;
+}
+
+export interface AdditiveBuffer<T> {
+  /** Append an item, creating the buffer if needed. Resets the debounce timer. */
+  enqueue(contextKey: string, item: T): void;
+  /** True when a buffer exists for this key (i.e. at least one item is queued). */
+  isBuffered(contextKey: string): boolean;
+  /** Number of items currently queued for this key, or 0. */
+  count(contextKey: string): number;
+  /** Flush immediately with `reason="manual"`. No-op when no buffer exists. */
+  instantFlush(contextKey: string): Promise<void>;
+  /** Drop the buffer without flushing. No-op when no buffer exists. */
+  cancel(contextKey: string): boolean;
+  /** For tests / diagnostics. */
+  keys(): string[];
+}
+
+interface BufferEntry<T> {
+  items: T[];
+  timer: ReturnType<typeof setTimeout>;
+}
+
+export function createAdditiveBuffer<T>(options: AdditiveBufferOptions<T>): AdditiveBuffer<T> {
+  const { timeoutMs, onFlush, label } = options;
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new Error(`additive-buffer: timeoutMs must be a positive number, got ${timeoutMs}`);
+  }
+
+  const buffers = new Map<string, BufferEntry<T>>();
+  const prefix = label ? `[buffer:${label}]` : "[buffer]";
+
+  function scheduleFlush(key: string) {
+    return setTimeout(() => {
+      void doFlush(key, "timer");
+    }, timeoutMs);
+  }
+
+  async function doFlush(key: string, reason: BufferFlushReason): Promise<void> {
+    const entry = buffers.get(key);
+    if (!entry || entry.items.length === 0) {
+      buffers.delete(key);
+      return;
+    }
+    clearTimeout(entry.timer);
+    buffers.delete(key);
+    try {
+      await onFlush(entry.items, key, reason);
+    } catch (error) {
+      console.error(`${prefix} onFlush threw for key=${key}:`, error);
+    }
+  }
+
+  return {
+    enqueue(contextKey: string, item: T): void {
+      if (!contextKey) {
+        throw new Error("additive-buffer: contextKey is required");
+      }
+      const existing = buffers.get(contextKey);
+      if (existing) {
+        clearTimeout(existing.timer);
+        existing.items.push(item);
+        existing.timer = scheduleFlush(contextKey);
+        console.log(
+          `${prefix} append: ${contextKey} (${existing.items.length} items, timer reset to ${timeoutMs}ms)`,
+        );
+      } else {
+        const entry: BufferEntry<T> = {
+          items: [item],
+          timer: scheduleFlush(contextKey),
+        };
+        buffers.set(contextKey, entry);
+        console.log(`${prefix} created: ${contextKey} (timer set to ${timeoutMs}ms)`);
+      }
+    },
+
+    isBuffered(contextKey: string): boolean {
+      return buffers.has(contextKey);
+    },
+
+    count(contextKey: string): number {
+      return buffers.get(contextKey)?.items.length ?? 0;
+    },
+
+    instantFlush(contextKey: string): Promise<void> {
+      return doFlush(contextKey, "manual");
+    },
+
+    cancel(contextKey: string): boolean {
+      const entry = buffers.get(contextKey);
+      if (!entry) return false;
+      clearTimeout(entry.timer);
+      buffers.delete(contextKey);
+      return true;
+    },
+
+    keys(): string[] {
+      return Array.from(buffers.keys());
+    },
+  };
+}

package/src/tasks/additive-ingress.ts

@@ -0,0 +1,125 @@
+/**
+ * Generic "additive ingress" helper for Phase 2 cross-ingress sibling-awareness.
+ *
+ * Wraps `createAdditiveBuffer` with the typical pattern used by comment-style
+ * ingress points (AgentMail threads, GitHub/GitLab issue comments, Linear
+ * comments): when a sibling task is already in flight for the same contextKey,
+ * debounce rapid follow-up inputs into a SINGLE follow-up task instead of
+ * spawning N tasks.
+ *
+ * This generalizes the Slack `ADDITIVE_SLACK` buffer — Slack's own buffer stays
+ * as-is to preserve exact behaviour; other ingress points opt in via env flags.
+ *
+ * Default: opt-in (env flag unset => all calls are no-ops; caller proceeds to
+ * create a task normally).
+ */
+
+import { type AdditiveBuffer, createAdditiveBuffer } from "./additive-buffer";
+
+export type IngressFlushReason = "timer" | "manual";
+
+export interface IngressBufferItem<T> {
+  payload: T;
+  enqueuedAt: number;
+}
+
+export interface IngressBufferOptions<T> {
+  /** Short identifier used in logs, e.g. "agentmail", "github-issue-comment". */
+  source: string;
+  /**
+   * Env flag name (e.g. `"ADDITIVE_AGENTMAIL"`). When the flag resolves to
+   * `"true"` the buffer is enabled; otherwise `maybeBuffer()` is a no-op.
+   */
+  envFlag: string;
+  /** Debounce timeout in ms. Reset on every enqueue. Default: 10000ms. */
+  timeoutMs?: number;
+  /**
+   * Called when the buffer flushes (timer expiry OR manual). Receives the
+   * payloads in arrival order, the contextKey, and the reason. Errors thrown
+   * here are logged and swallowed.
+   */
+  onFlush: (items: T[], contextKey: string, reason: IngressFlushReason) => Promise<void> | void;
+}
+
+export interface IngressBuffer<T> {
+  /**
+   * `true` when the env flag was set to `"true"` at construction time.
+   * Callers should still guard with `maybeBuffer` — this is informational.
+   */
+  enabled: boolean;
+  /**
+   * Attempt to buffer an input. Returns `true` when the item was buffered
+   * (caller MUST NOT create a task), `false` otherwise (caller proceeds).
+   *
+   * Params:
+   *   - `contextKey`  — uniform sibling key from Phase 1. Empty string disables.
+   *   - `siblingInFlight` — whether the caller already knows a sibling exists
+   *     for `contextKey`. Callers typically pass the boolean from
+   *     `getInProgressTasksByContextKey(contextKey).length > 0`.
+   *   - `payload` — the item to buffer.
+   */
+  maybeBuffer(contextKey: string, siblingInFlight: boolean, payload: T): boolean;
+  /** True if the key currently has a pending buffer (for debugging/tests). */
+  isBuffered(contextKey: string): boolean;
+  /** Count of items in the buffer for `contextKey`. */
+  count(contextKey: string): number;
+  /** Flush immediately, cancelling the debounce timer. */
+  instantFlush(contextKey: string): Promise<void>;
+  /** Drop buffered items without flushing. */
+  cancel(contextKey: string): void;
+  /** Raw underlying buffer — escape hatch for tests. */
+  _buffer: AdditiveBuffer<T>;
+}
+
+/**
+ * Read the env flag value lazily so tests can toggle it without re-importing.
+ */
+function envEnabled(flag: string): boolean {
+  return process.env[flag] === "true";
+}
+
+/**
+ * Create an ingress buffer. The wrapper records the env flag at construction
+ * time (not per-call) so behaviour is stable across a process run.
+ *
+ * Consumers typically:
+ *   1. Look up siblings for the contextKey (`getInProgressTasksByContextKey`).
+ *   2. Call `buffer.maybeBuffer(contextKey, siblings.length > 0, payload)`.
+ *   3. If `true`, stop — buffered. Otherwise, proceed to `createTaskWithSiblingAwareness`.
+ */
+export function createIngressBuffer<T>(opts: IngressBufferOptions<T>): IngressBuffer<T> {
+  const enabled = envEnabled(opts.envFlag);
+  const timeoutMs = opts.timeoutMs ?? 10_000;
+
+  const buffer = createAdditiveBuffer<T>({
+    timeoutMs,
+    label: opts.source,
+    onFlush: async (items, key, reason) => {
+      await opts.onFlush(items, key, reason);
+    },
+  });
+
+  return {
+    enabled,
+    maybeBuffer(contextKey, siblingInFlight, payload) {
+      if (!enabled) return false;
+      if (!contextKey) return false;
+      if (!siblingInFlight) return false;
+      buffer.enqueue(contextKey, payload);
+      return true;
+    },
+    isBuffered(contextKey) {
+      return buffer.isBuffered(contextKey);
+    },
+    count(contextKey) {
+      return buffer.count(contextKey);
+    },
+    instantFlush(contextKey) {
+      return buffer.instantFlush(contextKey);
+    },
+    cancel(contextKey) {
+      buffer.cancel(contextKey);
+    },
+    _buffer: buffer,
+  };
+}