@desplega.ai/agent-swarm 2.7.5 → 2.7.6

package/src/runtime-providers/docker.ts

@@ -4,6 +4,7 @@ import {
   type ConfigStatus,
   type ProvisionRequest,
   RUNTIME_LABELS,
+  type RuntimeCacheReference,
   type RuntimeHandle,
   type RuntimeProvider,
   type RuntimeStatus,
@@ -63,6 +64,22 @@ class DockerApiError extends Error {
   }
 }
 
+function isCacheMountError(error: unknown): boolean {
+  return error instanceof DockerApiError && /\b(?:mount\w*|volume\w*)\b/i.test(error.message);
+}
+
+type CacheVolume = { Name: string; Labels?: Record<string, string> };
+
+function assertCacheOwner(volume: CacheVolume, cache: RuntimeCacheReference): void {
+  if (
+    volume.Name !== cache.key ||
+    volume.Labels?.[RUNTIME_LABELS.owner] !== cache.ownerId ||
+    volume.Labels?.[RUNTIME_LABELS.poolId] !== cache.poolId ||
+    volume.Labels?.["swarm.cache"] !== "true"
+  )
+    throw new Error(`Cache volume ${cache.key} is not owned by this swarm and pool`);
+}
+
 async function dockerApi<T>(
   target: RuntimeTargetConfig,
   method: string,
@@ -119,7 +136,12 @@ async function dockerApi<T>(
 
 export class DockerRuntimeProvider implements RuntimeProvider {
   readonly kind = "docker" as const;
-  readonly traits = { canProvision: true, ephemeralDisk: true, supportsPause: false };
+  readonly traits = {
+    canProvision: true,
+    ephemeralDisk: true,
+    supportsPause: false,
+    persistentCache: true,
+  };
 
   checkConfig(target: RuntimeTargetConfig): ConfigStatus {
     try {
@@ -132,6 +154,29 @@ export class DockerRuntimeProvider implements RuntimeProvider {
 
   async provision(target: RuntimeTargetConfig, req: ProvisionRequest): Promise<RuntimeHandle> {
     try {
+      let cacheWarning: string | undefined;
+      let cacheMount: { Type: "volume"; Source: string; Target: string } | undefined;
+      if (req.cache) {
+        try {
+          const volume = await dockerApi<CacheVolume>(target, "POST", "/volumes/create", {
+            Name: req.cache.key,
+            Labels: {
+              [RUNTIME_LABELS.owner]: req.ownerId,
+              [RUNTIME_LABELS.poolId]: req.poolId,
+              "swarm.cache": "true",
+            },
+          });
+          // Docker reuses an existing name without replacing its labels.
+          assertCacheOwner(volume, {
+            key: req.cache.key,
+            poolId: req.poolId,
+            ownerId: req.ownerId,
+          });
+          cacheMount = { Type: "volume", Source: req.cache.key, Target: req.cache.mountPath };
+        } catch (error) {
+          cacheWarning = redactWithEnv(scrubSecrets(String(error)), req.env);
+        }
+      }
       const path = `/containers/create?name=${encodeURIComponent(`swarm-rt-${req.runtimeId}`)}`;
       const body = {
         Image: req.image,
@@ -154,40 +199,80 @@ export class DockerRuntimeProvider implements RuntimeProvider {
           NetworkMode: target.DOCKER_NETWORK,
           Memory: req.resources?.memoryMb ? req.resources.memoryMb * 1024 * 1024 : undefined,
           NanoCpus: req.resources?.cpu ? Math.round(req.resources.cpu * 1e9) : undefined,
+          ...(cacheMount ? { Mounts: [cacheMount] } : {}),
         },
       };
-      let created: { Id: string };
-      try {
-        created = await dockerApi(target, "POST", path, body);
-      } catch (err) {
-        if (
-          !(err instanceof DockerApiError) ||
-          err.statusCode !== 404 ||
-          !err.message.includes("No such image")
-        ) {
-          throw err;
+      const createAndStart = async (): Promise<string> => {
+        let created: { Id: string };
+        try {
+          created = await dockerApi(target, "POST", path, body);
+        } catch (err) {
+          if (
+            !(err instanceof DockerApiError) ||
+            err.statusCode !== 404 ||
+            !err.message.includes("No such image")
+          )
+            throw err;
+          const pullParams = new URLSearchParams({ fromImage: req.image });
+          if (
+            !req.image.includes("@") &&
+            req.image.lastIndexOf(":") <= req.image.lastIndexOf("/")
+          ) {
+            pullParams.set("tag", "latest");
+          }
+          await dockerApi(target, "POST", `/images/create?${pullParams}`, undefined, true);
+          created = await dockerApi(target, "POST", path, body);
         }
-        const pullParams = new URLSearchParams({ fromImage: req.image });
-        if (!req.image.includes("@") && req.image.lastIndexOf(":") <= req.image.lastIndexOf("/")) {
-          pullParams.set("tag", "latest");
+        try {
+          await dockerApi(target, "POST", `/containers/${created.Id}/start`);
+        } catch (err) {
+          try {
+            await dockerApi(target, "DELETE", `/containers/${created.Id}?force=true&v=true`);
+          } catch (cleanupError) {
+            if (
+              cacheMount &&
+              isCacheMountError(err) &&
+              !(cleanupError instanceof DockerApiError && cleanupError.statusCode === 404)
+            )
+              throw new Error(
+                `${String(err)}; failed-start cleanup failed: ${String(cleanupError)}`,
+              );
+          }
+          throw err;
         }
-        await dockerApi(target, "POST", `/images/create?${pullParams}`, undefined, true);
-        created = await dockerApi(target, "POST", path, body);
-      }
+        return created.Id;
+      };
+      let externalId: string;
       try {
-        await dockerApi(target, "POST", `/containers/${created.Id}/start`);
+        externalId = await createAndStart();
       } catch (err) {
-        await dockerApi(target, "DELETE", `/containers/${created.Id}?force=true&v=true`).catch(
-          () => {},
-        );
-        throw err;
+        if (!cacheMount || !isCacheMountError(err)) throw err;
+        cacheWarning = redactWithEnv(scrubSecrets(String(err)), req.env);
+        delete body.HostConfig.Mounts;
+        externalId = await createAndStart();
       }
-      return { kind: "docker", externalId: created.Id };
+      return {
+        kind: "docker",
+        externalId,
+        ...(cacheWarning ? { meta: { cacheWarning } } : {}),
+      };
     } catch (err) {
       throw new Error(redactWithEnv(String(err), req.env));
     }
   }
 
+  async releaseCache(target: RuntimeTargetConfig, cache: RuntimeCacheReference): Promise<void> {
+    const path = `/volumes/${encodeURIComponent(cache.key)}`;
+    try {
+      const volume = await dockerApi<CacheVolume>(target, "GET", path);
+      assertCacheOwner(volume, cache);
+      // A volume still attached to any container must remain intact (Docker returns 409).
+      await dockerApi(target, "DELETE", path);
+    } catch (error) {
+      if (!(error instanceof DockerApiError && error.statusCode === 404)) throw error;
+    }
+  }
+
   async terminate(target: RuntimeTargetConfig, handle: RuntimeHandle): Promise<void> {
     try {
       // v=true also removes the container's anonymous volumes (the worker image declares

package/src/runtime-providers/types.ts

@@ -19,6 +19,8 @@ export interface RuntimeProviderTraits {
   ephemeralDisk: boolean;
   /** Provider can pause and resume a runtime. */
   supportsPause: boolean;
+  /** Can mount a persistent cache shared by all runtimes of one pool. */
+  persistentCache?: boolean;
   /** Provider hard cap on runtime lifetime, if any. */
   maxTtlSec?: number;
   /** Continuous runtime limit for the configured infrastructure tier. */
@@ -45,11 +47,23 @@ export interface ProvisionRequest {
   /** Worker env: MCP_BASE_URL, AGENT_ID, API key or scoped token, pool env. */
   env: Record<string, string>;
   resources?: { cpu?: number; memoryMb?: number };
+  /** Provider-neutral cache identity, allocated by the API rather than the operator. */
+  cache?: { key: string; mountPath: string };
   ttlSec?: number;
   /** Ownership labels, used by list() to find runtimes this swarm started. */
   labels: Record<string, string>;
 }
 
+export interface RuntimeCacheReference {
+  key: string;
+  poolId: string;
+  ownerId: string;
+}
+
+export function poolCacheKey(poolId: string, generation?: string): string {
+  return `swarm-cache-${poolId}${generation ? `-${generation}` : ""}`;
+}
+
 export interface RuntimeHandle {
   kind: RuntimeProviderKind;
   /** Container id, sandbox id, or pod name. */
@@ -74,6 +88,8 @@ export interface RuntimeProvider {
   status(target: RuntimeTargetConfig, handle: RuntimeHandle): Promise<RuntimeStatus>;
   /** Every runtime this swarm owns on the target, found by labels. Used to reap orphans. */
   list(target: RuntimeTargetConfig, ownerId: string): Promise<RuntimeHandle[]>;
+  /** Remove an owned pool cache after its runtimes stop; never force detach. */
+  releaseCache?(target: RuntimeTargetConfig, cache: RuntimeCacheReference): Promise<void>;
   renew?(
     target: RuntimeTargetConfig,
     handle: RuntimeHandle,

package/src/script-workflows/workflow-ctx.ts

@@ -44,6 +44,14 @@ type AgentTaskConfig = {
   parentTaskId?: string;
   requestedByUserId?: string;
   outputSchema?: Record<string, unknown>;
+  /**
+   * Dispatch even when the follow-up re-delegation guard blocks this step.
+   * The guard applies only to a run launched from a follow-up task in a Slack
+   * thread, and decides once for the whole run at its first new step: it
+   * blocks a repeat of work already completed in the thread, or a run past the
+   * thread's dispatch cap. A blocked run's later new steps are blocked too.
+   */
+  allowRedelegation?: boolean;
   /**
    * Block until the dispatched task reaches a terminal status and journal
    * its real output. Defaults to `true` — this is the natural semantic for

package/src/scripts-runtime/types/stdlib.d.ts

@@ -63,6 +63,8 @@ declare module "swarm-sdk" {
     parentTaskId?: string;
     requestedByUserId?: string;
     outputSchema?: Record<string, unknown>;
+    /** Dispatch even when the follow-up re-delegation guard blocks this step (a run launched from a follow-up task in a Slack thread, checked at its first new step). */
+    allowRedelegation?: boolean;
     /** Wait for the dispatched task to reach a terminal status before resolving. Default: true. */
     waitForCompletion?: boolean;
     /** Max ms to wait for a terminal status before throwing. Default: 2h. Only used when waitForCompletion is true. */
@@ -760,6 +762,26 @@ declare module "swarm-sdk" {
       label: string,
       config: { prompt: string; model?: string; schema?: Record<string, unknown> },
     ): Promise<unknown>;
+    /**
+     * Dispatch a task and journal its result under `label`.
+     *
+     * Resolves to the task's OUTPUT on success: the stored output string (JSON
+     * text under `outputSchema`, so parse it yourself), or `null` when the task
+     * stored none. It is never a task record: on a string, `result.taskId` and
+     * `result.status` are undefined; on `null`, reading them throws a TypeError.
+     * Other shapes:
+     * - `failOnTaskFailure: false` and the task ends failed/cancelled/superseded:
+     *   `{ taskId, status: "failed", error }`.
+     * - `waitForCompletion: false`: the first call still waits up to ~30s while
+     *   the server polls the task. Done in that window: the output, as on
+     *   success. Failed or cancelled in that window: throws, or
+     *   `{ taskId, status: "failed", error }` with `failOnTaskFailure: false`.
+     *   Still running: `{ taskId, status }`.
+     *
+     * To get a step's task id, query by its context key:
+     * `SELECT id, status, output FROM agent_tasks WHERE contextKey = 'script-run:<runId>:<label>'
+     * AND taskType = 'script-run-step' ORDER BY createdAt DESC, rowid DESC LIMIT 1`.
+     */
     agentTask(label: string, config: AgentTaskStepConfig): Promise<unknown>;
     swarmScript(
       label: string,

package/src/scripts-runtime/types/swarm-sdk.d.ts

@@ -45,6 +45,8 @@ declare module "swarm-sdk" {
     parentTaskId?: string;
     requestedByUserId?: string;
     outputSchema?: Record<string, unknown>;
+    /** Dispatch even when the follow-up re-delegation guard blocks this step (a run launched from a follow-up task in a Slack thread, checked at its first new step). */
+    allowRedelegation?: boolean;
     /** Wait for the dispatched task to reach a terminal status before resolving. Default: true. */
     waitForCompletion?: boolean;
     /** Max ms to wait for a terminal status before throwing. Default: 2h. Only used when waitForCompletion is true. */
@@ -742,6 +744,26 @@ declare module "swarm-sdk" {
       label: string,
       config: { prompt: string; model?: string; schema?: Record<string, unknown> },
     ): Promise<unknown>;
+    /**
+     * Dispatch a task and journal its result under `label`.
+     *
+     * Resolves to the task's OUTPUT on success: the stored output string (JSON
+     * text under `outputSchema`, so parse it yourself), or `null` when the task
+     * stored none. It is never a task record: on a string, `result.taskId` and
+     * `result.status` are undefined; on `null`, reading them throws a TypeError.
+     * Other shapes:
+     * - `failOnTaskFailure: false` and the task ends failed/cancelled/superseded:
+     *   `{ taskId, status: "failed", error }`.
+     * - `waitForCompletion: false`: the first call still waits up to ~30s while
+     *   the server polls the task. Done in that window: the output, as on
+     *   success. Failed or cancelled in that window: throws, or
+     *   `{ taskId, status: "failed", error }` with `failOnTaskFailure: false`.
+     *   Still running: `{ taskId, status }`.
+     *
+     * To get a step's task id, query by its context key:
+     * `SELECT id, status, output FROM agent_tasks WHERE contextKey = 'script-run:<runId>:<label>'
+     * AND taskType = 'script-run-step' ORDER BY createdAt DESC, rowid DESC LIMIT 1`.
+     */
     agentTask(label: string, config: AgentTaskStepConfig): Promise<unknown>;
     swarmScript(
       label: string,

package/src/server-user.ts

@@ -130,6 +130,7 @@ export function createUserServer(user: User): McpServer {
       offerMode: false,
       leadOnly: false,
       allowDuplicate: false,
+      allowRedelegation: false,
       overrideSlackContext: false,
     });
   });

package/src/slack/commands.ts

@@ -2,6 +2,7 @@ import type { App } from "@slack/bolt";
 import { getAllAgents, getAllTasks } from "../be/db";
 import { isEnvFlagEnabled } from "../utils/env-flag";
 import { EXTERNAL_CHANNEL_BLOCKED_REPLY, shouldBlockChannel } from "./external-channel";
+import { isSlackLeaveThreadDisabled } from "./left-threads";
 
 export function registerCommandHandler(app: App): void {
   app.command("/agent-swarm-status", async ({ ack, respond, command, client }) => {
@@ -88,9 +89,12 @@ export function registerCommandHandler(app: App): void {
 • Follow-up tasks auto-depend on the active task in the thread for natural sequencing`);
     }
 
+    const leaveLine = isSlackLeaveThreadDisabled()
+      ? ""
+      : "\n• `!leave` in a thread - Make the swarm ignore that thread until someone @mentions it";
     sections.push(`*Commands:*
 • \`/agent-swarm-status\` - Show all agents and their current status
-• \`/agent-swarm-help\` - Show this help message`);
+• \`/agent-swarm-help\` - Show this help message${leaveLine}`);
 
     const blocks = [
       {

package/src/slack/handlers.ts

@@ -52,7 +52,13 @@ import {
   leaveExternalChannel,
   shouldBlockChannel,
 } from "./external-channel";
-import { shouldSkipLeftSlackThread } from "./left-threads";
+import {
+  isSlackLeaveThreadCommand,
+  isSlackLeaveThreadDisabled,
+  leaveSlackThread,
+  SLACK_LEFT_THREAD_CONFIRMATION,
+  shouldSkipLeftSlackThread,
+} from "./left-threads";
 import {
   collectSlackMessageFiles,
   extractSlackMessageText,
@@ -491,7 +497,36 @@ export function registerMessageHandler(app: App): void {
     // Check if bot was mentioned (in original text only)
     const botMentioned = !!cachedBotUserId && !!msg.text?.includes(`<@${cachedBotUserId}>`);
 
-    // A thread the swarm left (slack-leave-thread) stays silent until someone
+    // `!leave` in a thread the swarm is in: a human makes the swarm leave it,
+    // in code, with no workflow event, buffering, task, or model call.
+    // Any task bound to the thread counts, assigned or not, as does a thread
+    // the swarm started. Checked before the left-thread gate so `@bot !leave`
+    // leaves rather than rejoining. The confirmation is ephemeral, to the
+    // sender only.
+    if (
+      msg.thread_ts &&
+      !isSlackLeaveThreadDisabled() &&
+      isSlackLeaveThreadCommand(msg.text, cachedBotUserId) &&
+      ((await getMostRecentTaskInThread(msg.channel, msg.thread_ts)) !== null ||
+        (await wasThreadStartedBySwarm(client, msg.channel, msg.thread_ts)))
+    ) {
+      noteSlackInboundSideEffect("thread_leave");
+      await leaveSlackThread(msg.channel, msg.thread_ts, { slackUserId: msg.user });
+      console.log(`[Slack] Left thread ${msg.channel}/${msg.thread_ts}: !leave from ${msg.user}`);
+      try {
+        await client.chat.postEphemeral({
+          channel: msg.channel,
+          user: msg.user,
+          thread_ts: msg.thread_ts,
+          text: SLACK_LEFT_THREAD_CONFIRMATION,
+        });
+      } catch (error) {
+        console.error("[Slack] Failed to confirm !leave:", error);
+      }
+      return;
+    }
+
+    // A thread the swarm left (slack-leave-thread or `!leave`) stays silent until someone
     // @mentions the bot. Checked before the workflow event, buffering, routing,
     // or any AI call.
     if (await shouldSkipLeftSlackThread(msg.channel, msg.thread_ts, botMentioned)) {

package/src/slack/left-threads.ts

@@ -2,7 +2,8 @@ import { deleteKv, getKv, upsertKv } from "../be/db";
 import { isEnvFlagEnabled } from "../utils/env-flag";
 
 /**
- * Slack threads the swarm left via `slack-leave-thread`.
+ * Slack threads the swarm left, via the `slack-leave-thread` tool or a
+ * human's `!leave` in the thread.
  *
  * A left thread drops every inbound message that does not @mention the bot,
  * in code, before buffering, routing, or any AI call. A mention clears the
@@ -11,7 +12,7 @@ import { isEnvFlagEnabled } from "../utils/env-flag";
  */
 export const SLACK_LEFT_THREAD_KV_NAMESPACE = "slack-left-thread";
 
-/** Operator flag that turns the `slack-leave-thread` tool off. */
+/** Operator flag that turns leaving threads off: the tool and `!leave`. */
 export const SLACK_LEAVE_THREAD_DISABLE = "SLACK_LEAVE_THREAD_DISABLE";
 
 /**
@@ -22,19 +23,41 @@ export function isSlackLeaveThreadDisabled(): boolean {
   return isEnvFlagEnabled(SLACK_LEAVE_THREAD_DISABLE, false);
 }
 
+/** Ephemeral reply to the human who sent `!leave`. */
+export const SLACK_LEFT_THREAD_CONFIRMATION =
+  "Left this thread. @mention the swarm to bring it back.";
+
+/**
+ * True when a thread message is the `!leave` command: exactly `!leave`,
+ * optionally after @mentions of the bot. A message that mentions anyone else
+ * is not addressed to the swarm and does not match.
+ */
+export function isSlackLeaveThreadCommand(
+  text: string | undefined,
+  botUserId: string | null,
+): boolean {
+  const withoutBotMentions = botUserId
+    ? (text ?? "").replaceAll(`<@${botUserId}>`, "")
+    : (text ?? "");
+  return withoutBotMentions.trim() === "!leave";
+}
+
 function threadKey(channelId: string, threadTs: string): string {
   return `${channelId}:${threadTs}`;
 }
 
+/** Who left the thread: an agent via the tool, or a Slack user via `!leave`. */
+export type SlackThreadLeftBy = { agentId: string } | { slackUserId: string };
+
 export async function leaveSlackThread(
   channelId: string,
   threadTs: string,
-  agentId: string,
+  leftBy: SlackThreadLeftBy,
 ): Promise<void> {
   await upsertKv({
     namespace: SLACK_LEFT_THREAD_KV_NAMESPACE,
     key: threadKey(channelId, threadTs),
-    value: { agentId, leftAt: new Date().toISOString() },
+    value: { ...leftBy, leftAt: new Date().toISOString() },
     valueType: "json",
   });
 }

package/src/tasks/follow-up-redelegation-guard.ts

@@ -0,0 +1,155 @@
+/**
+ * Follow-up re-delegation guard, shared by every agent dispatch path that can
+ * run inside a follow-up session: MCP `send-task` and durable-run
+ * `ctx.step.agentTask` steps (`src/http/script-runs.ts`).
+ *
+ * When the dispatching session's source task is a `follow-up` in a Slack
+ * thread, two rules stop the cycle
+ * worker completes → follow-up → Lead re-delegates → repeat,
+ * while a distinct next step (step 2 of a chain, a fix round, a retry) passes:
+ *
+ * 1. same-work: the new task matches a completed task in the thread under the
+ *    dedup similarity rules. Bypassed when a task in the thread was cancelled
+ *    or failed after that completion: the work was interrupted or went wrong,
+ *    so re-dispatch is the correct response, not a deduped no-op.
+ * 2. loop-cap: the caller already made FOLLOW_UP_DISPATCH_CAP dispatches into
+ *    the thread within FOLLOW_UP_DISPATCH_WINDOW_MINUTES. A durable script run
+ *    counts once however many steps it dispatched. Independent of similarity,
+ *    so a loop that rewords each re-delegation still stops.
+ *
+ * Callers bypass both with `allowRedelegation` and log the override. Each
+ * caller evaluates the rules inside the write transaction that inserts the
+ * task, so two concurrent dispatches into one thread (send-task or a run's
+ * first step, in any mix) cannot both read the count below the cap.
+ */
+import {
+  countAgentDispatchesInThread,
+  findCompletedTasksInThread,
+  findRecentCancelledTaskInThread,
+  findRecentFailedTaskInThread,
+  getTaskById,
+} from "../be/db";
+import { type DedupMatch, matchSimilarTask } from "../tools/task-dedup";
+
+/** How far back the same-work rule looks for a completed task in the thread. */
+export const FOLLOW_UP_SAME_WORK_WINDOW_MINUTES = 2880; // 48 hours
+/**
+ * Loop cap: dispatches one agent may make into one Slack thread per window
+ * before a follow-up session needs allowRedelegation. A long legitimate chain
+ * (plan, implement, review, fix, re-review, fix, CI fix, retry) is about 8
+ * dispatches; a runaway loop makes one per worker run (minutes), so it hits
+ * 10 within a few hours and burns at most 10 worker sessions.
+ */
+export const FOLLOW_UP_DISPATCH_CAP = 10;
+export const FOLLOW_UP_DISPATCH_WINDOW_MINUTES = 360; // 6 hours
+
+/** Rows per page when the same-work rule scans a thread's completions. */
+export const FOLLOW_UP_SAME_WORK_PAGE_SIZE = 200;
+
+export type FollowUpThread = { channelId: string; threadTs: string; userId?: string };
+
+export type FollowUpRedelegationBlock = {
+  rule: "same-work" | "loop-cap";
+  message: string;
+};
+
+/**
+ * The Slack thread the guard applies to, or null when the source task is not
+ * a `follow-up` in a Slack thread. A `resume` source is intentionally exempt:
+ * a resume IS the legitimate re-dispatch.
+ */
+export async function followUpThreadForSourceTask(
+  sourceTaskId: string | null | undefined,
+): Promise<FollowUpThread | null> {
+  if (!sourceTaskId) return null;
+  const sourceTask = await getTaskById(sourceTaskId);
+  if (
+    sourceTask?.taskType !== "follow-up" ||
+    !sourceTask.slackChannelId ||
+    !sourceTask.slackThreadTs
+  ) {
+    return null;
+  }
+  return {
+    channelId: sourceTask.slackChannelId,
+    threadTs: sourceTask.slackThreadTs,
+    userId: sourceTask.slackUserId,
+  };
+}
+
+/**
+ * The most recent completed task in the thread's same-work window whose
+ * description matches this dispatch. Pages through every completion in the
+ * window (an older match can sit behind any number of newer unrelated ones),
+ * one bounded query per page, and stops at the first match.
+ */
+async function findMatchingCompletedWork(args: {
+  channelId: string;
+  threadTs: string;
+  taskDescription: string;
+  targetAgentId?: string;
+}): Promise<DedupMatch | null> {
+  let before: { lastUpdatedAt: string; id: string } | undefined;
+  for (;;) {
+    const page = await findCompletedTasksInThread(
+      args.channelId,
+      args.threadTs,
+      FOLLOW_UP_SAME_WORK_WINDOW_MINUTES,
+      FOLLOW_UP_SAME_WORK_PAGE_SIZE,
+      before,
+    );
+    for (const existing of page) {
+      const match = matchSimilarTask(existing, args);
+      if (match) return match;
+    }
+    const last = page.at(-1);
+    if (!last || page.length < FOLLOW_UP_SAME_WORK_PAGE_SIZE) return null;
+    before = { lastUpdatedAt: last.lastUpdatedAt, id: last.id };
+  }
+}
+
+/**
+ * The follow-up re-delegation rules. Returns the rule that blocks this
+ * dispatch, or null when it may proceed.
+ */
+export async function evaluateFollowUpRedelegation(args: {
+  channelId: string;
+  threadTs: string;
+  creatorAgentId: string;
+  taskDescription: string;
+  targetAgentId?: string;
+}): Promise<FollowUpRedelegationBlock | null> {
+  const { channelId, threadTs } = args;
+  const match = await findMatchingCompletedWork(args);
+  if (match) {
+    const existing = match.task;
+    const [cancelled, failed] = await Promise.all([
+      findRecentCancelledTaskInThread(channelId, threadTs, FOLLOW_UP_SAME_WORK_WINDOW_MINUTES),
+      findRecentFailedTaskInThread(channelId, threadTs, FOLLOW_UP_SAME_WORK_WINDOW_MINUTES),
+    ]);
+    const completedAt = new Date(existing.lastUpdatedAt).getTime();
+    const interruptedLater = [cancelled, failed].some(
+      (t) => t && new Date(t.lastUpdatedAt).getTime() > completedAt,
+    );
+    if (!interruptedLater) {
+      return {
+        rule: "same-work",
+        message: `Blocked by the follow-up re-delegation guard (same-work rule): this task matches completed task ${existing.id.slice(0, 8)} in this Slack thread (${match.reason}), so the work was already done. If it must run again, pass allowRedelegation: true.`,
+      };
+    }
+  }
+
+  const dispatched = await countAgentDispatchesInThread(
+    channelId,
+    threadTs,
+    args.creatorAgentId,
+    FOLLOW_UP_DISPATCH_WINDOW_MINUTES,
+  );
+  if (dispatched >= FOLLOW_UP_DISPATCH_CAP) {
+    return {
+      rule: "loop-cap",
+      message: `Blocked by the follow-up re-delegation guard (loop-cap rule): you already dispatched ${dispatched} times into this Slack thread in the last ${FOLLOW_UP_DISPATCH_WINDOW_MINUTES / 60} hours (cap ${FOLLOW_UP_DISPATCH_CAP}; a durable script run counts once). If this is a deliberate next step and not a re-delegation loop, pass allowRedelegation: true.`,
+    };
+  }
+  return null;
+}