@desplega.ai/agent-swarm 1.146.0 → 1.147.0

package/src/http/sessions.ts

@@ -2,7 +2,9 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
 import { countSessions, getRootTaskChain, getTaskById, listRecentSessions } from "../be/db";
 import { getTaskSteeringFields } from "../be/steering";
+import { mintSessionToken, revokeSessionToken } from "../be/users";
 import { AgentTaskSchema, AgentTaskStatusSchema, SteerModeSchema } from "../types";
+import { getRequestAuth } from "../utils/request-auth-context";
 import { route } from "./route-def";
 import { jsonError } from "./utils";
 
@@ -68,6 +70,57 @@ const TaskWithSteeringSchema = AgentTaskSchema.extend({
 
 // ─── Route Definitions ───────────────────────────────────────────────────────
 
+/** Maximum TTL for an ephemeral session token: 7 days. */
+const MAX_SESSION_TOKEN_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+const mintSessionTokenRoute = route({
+  method: "post",
+  path: "/api/sessions/tokens",
+  pattern: ["api", "sessions", "tokens"],
+  summary: "Mint an ephemeral session token for an ACP provider session",
+  description:
+    "Returns a short-lived aseph_ bearer for use by the ACP adapter in place of the full " +
+    "operator key. The token expires at the requested TTL and is actively revoked when the " +
+    "session ends. Only the operator key may mint session tokens.",
+  tags: ["Sessions"],
+  body: z.object({
+    agentId: z.string().min(1),
+    taskId: z.string().min(1),
+    ttlMs: z.number().int().positive().max(MAX_SESSION_TOKEN_TTL_MS),
+  }),
+  responses: {
+    200: {
+      description: "Minted token plaintext (returned once) and its stable token ID",
+      schema: z.object({
+        tokenId: z.string(),
+        plaintext: z.string(),
+      }),
+    },
+    400: { description: "Validation error" },
+    401: { description: "Unauthorized" },
+  },
+  auth: { apiKey: true },
+  rbac: { ungated: "operator-only: minting is gated on the full operator key in auth middleware" },
+});
+
+const revokeSessionTokenRoute = route({
+  method: "delete",
+  path: "/api/sessions/tokens/{tokenId}",
+  pattern: ["api", "sessions", "tokens", null],
+  summary: "Revoke an ephemeral session token",
+  description: "Revokes an aseph_ bearer token by ID. No-op if already revoked.",
+  tags: ["Sessions"],
+  params: z.object({ tokenId: z.string() }),
+  responses: {
+    204: { description: "Token revoked (or was already revoked)" },
+    401: { description: "Unauthorized" },
+  },
+  auth: { apiKey: true },
+  rbac: {
+    ungated: "operator-only: revocation is gated on the full operator key in auth middleware",
+  },
+});
+
 const listSessions = route({
   method: "get",
   path: "/api/sessions",
@@ -136,6 +189,35 @@ export async function handleSessions(
   pathSegments: string[],
   queryParams: URLSearchParams,
 ): Promise<boolean> {
+  if (mintSessionTokenRoute.match(req.method, pathSegments)) {
+    // Restrict to the full operator key — aseph_ and aswt_ bearers must not be
+    // able to mint new session tokens.
+    if (getRequestAuth(req)?.kind !== "operator") {
+      jsonError(res, "Unauthorized", 401);
+      return true;
+    }
+    const parsed = await mintSessionTokenRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const { agentId, taskId, ttlMs } = parsed.body;
+    const token = await mintSessionToken(agentId, taskId, ttlMs);
+    mintSessionTokenRoute.respond(res, 200, { tokenId: token.tokenId, plaintext: token.plaintext });
+    return true;
+  }
+
+  if (revokeSessionTokenRoute.match(req.method, pathSegments)) {
+    // Restrict revocation to the operator key as well.
+    if (getRequestAuth(req)?.kind !== "operator") {
+      jsonError(res, "Unauthorized", 401);
+      return true;
+    }
+    const parsed = await revokeSessionTokenRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    await revokeSessionToken(parsed.params.tokenId);
+    res.writeHead(204);
+    res.end();
+    return true;
+  }
+
   if (listSessions.match(req.method, pathSegments)) {
     const parsed = await listSessions.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;

package/src/http/tasks.ts

@@ -515,7 +515,9 @@ const listPausedTasks = route({
   responses: {
     200: {
       description: "Paused task list",
-      schema: z.object({ tasks: z.array(AgentTaskSchema) }),
+      schema: z.object({
+        tasks: z.array(AgentTaskSchema.extend({ attachments: z.array(TaskAttachmentSchema) })),
+      }),
     },
   },
 });
@@ -1449,7 +1451,13 @@ export async function handleTasks(
       return true;
     }
     const pausedTasks = await getPausedTasksForAgent(myAgentId);
-    listPausedTasks.respond(res, 200, { tasks: pausedTasks });
+    const tasks = await Promise.all(
+      pausedTasks.map(async (task) => ({
+        ...task,
+        attachments: await getTaskAttachments(task.id),
+      })),
+    );
+    listPausedTasks.respond(res, 200, { tasks });
     return true;
   }
 

package/src/prompts/session-templates.ts

@@ -74,7 +74,8 @@ Choose the path by the shape of the work:
 Store progress with \`store-progress\` at each milestone. A milestone is a result the lead could act on.
 The task is done when \`store-progress\` carries status \`completed\` and an \`output\` that names the result and every artifact link. On failure, status \`failed\` and a \`failureReason\` that names what you tried.
 When the task carries an \`outputSchema\`, \`output\` is JSON that matches it.
-When you are blocked after real effort, store the blocker with \`store-progress\` and keep working on what you can. When nothing is left to do, fail the task with a \`failureReason\` that names the blocker. The lead reads both.
+When you are blocked after real effort, store the blocker with \`store-progress\` and keep working on what you can.
+The task has four endings. When you are done: \`completed\`. When the answer needs time (a build, a deploy, a reply): \`defer-task\` with a summary of what you did, when to wake up, and what to check. It completes the task now; the wake-up task continues it. When a person must decide: \`request-human-input\`. When nothing else is possible: \`failed\` with the blocker.
 `,
   variables: [],
   category: "system",
@@ -89,9 +90,10 @@ registerTemplate({
 Your output is delegation and review. Workers implement, research, analyze, and write. Data gathering, even a quick query, goes to a worker. You answer simple factual questions yourself.
 
 \`get-swarm\` is the roster. Route by capability and load.
+Delegate with \`send-task\`. Read a child's result with \`get-task-details\`.
 A task states the goal, the repo URL when there is one, and the constraints. Workers know git, the skills, and \`store-progress\`.
 Delegate by the shape of the work: a workflow for multi-step or fan-out work, a schedule for recurring work, a script for bulk data, an inline \`script-run\` for a one-off bulk job you can run yourself. The \`workflow-iterate\`, \`scheduling\`, and \`swarm-scripts\` skills build them.
-Research or exploration: tell the worker to use \`/researching\`. A large feature: a \`/planning\` task first, then an \`/implementing\` task with \`parentTaskId\`. A small fix: direct implementation.
+Research or exploration: tell the worker to use the \`researching\` skill. A large feature: a task for the \`planning\` skill first, then a task for the \`implementing\` skill with \`parentTaskId\`. A small fix: direct implementation.
 A follow-up that continues earlier work carries \`parentTaskId\`. The worker receives the prior context.
 A task whose result depends on the workers' output: wait for the children with the \`wait-for-task\` script, then merge and complete the task yourself. A turn that ends with children still running leaves the task unfinished.
 

package/src/providers/acp-adapter.ts

@@ -12,6 +12,7 @@ import {
 } from "@agentclientprotocol/sdk";
 import pkg from "../../package.json";
 import type { AcpSessionConfigOption } from "../types";
+import { mintAcpSessionToken, revokeAcpSessionToken } from "../utils/acp-session-token";
 import { fetchInstalledMcpServers } from "../utils/mcp-server-fetcher";
 import {
   detachedProcessGroup,
@@ -176,6 +177,10 @@ class ACPSession implements ProviderSession {
   private output = "";
   private completionPromise: Promise<ProviderResult>;
   private completionResolve!: (result: ProviderResult) => void;
+  /** ID of the ephemeral aseph_ token minted for this session, or null when
+   * the fallback operator key is in use (e.g. during tests or if the API is
+   * not yet upgraded). Revoked in finish(). */
+  private ephemeralTokenId: string | null = null;
 
   constructor(
     private readonly connection: ClientSideConnection,
@@ -183,8 +188,10 @@ class ACPSession implements ProviderSession {
     private readonly config: ProviderSessionConfig,
     sessionId: string,
     providerMeta?: Record<string, unknown>,
+    ephemeralTokenId?: string,
   ) {
     this.sessionId = sessionId;
+    this.ephemeralTokenId = ephemeralTokenId ?? null;
     this.completionPromise = new Promise((resolve) => {
       this.completionResolve = resolve;
     });
@@ -338,6 +345,11 @@ class ACPSession implements ProviderSession {
     if (this.completed) return;
     this.completed = true;
     this.completionResolve(result);
+    // Revoke the ephemeral token now that the session is done. Best-effort:
+    // the token expires on its own, so a failure here is not critical.
+    if (this.ephemeralTokenId) {
+      void revokeAcpSessionToken(this.config.apiUrl, this.config.apiKey, this.ephemeralTokenId);
+    }
   }
 }
 
@@ -373,12 +385,23 @@ export class ACPAdapter implements ProviderAdapter {
     const stream = ndJsonStream(fileSinkWritableStream(proc.stdin), proc.stdout);
     const connection = new ClientSideConnection(() => client, stream);
 
+    let ephemeralToken: { tokenId: string; plaintext: string } | null = null;
     try {
       await connection.initialize({
         protocolVersion: PROTOCOL_VERSION,
         clientInfo: { name: "agent-swarm", version: pkg.version },
         clientCapabilities: { session: { configOptions: { boolean: {} } } },
       });
+      // Mint a short-lived session-scoped bearer so the ACP target receives
+      // an aseph_ token rather than the full operator key. Throws on failure
+      // so we fail closed instead of falling back to the operator key.
+      ephemeralToken = await mintAcpSessionToken(
+        config.apiUrl,
+        config.apiKey,
+        config.agentId,
+        config.taskId,
+      );
+
       const installedServers = await fetchInstalledMcpServers(
         config.apiUrl,
         config.apiKey,
@@ -388,7 +411,7 @@ export class ACPAdapter implements ProviderAdapter {
       // The v2 draft (@agentclientprotocol/sdk/experimental/v2) adds a fourth
       // `{ type: "acp", name, serverId }` variant where the client hosts the MCP
       // server itself and the agent tunnels MCP over the existing ACP connection
-      // (mcp/connect, mcp/message, mcp/disconnect) instead of a network hop — the
+      // (mcp/connect, mcp/message, mcp/disconnect) instead of a network hop -- the
       // shape for an ACP agent with no network route to the swarm API. Gated on
       // `mcpCapabilities.acp` and UNSTABLE; not adopted here.
       const newSession = await connection.newSession({
@@ -399,7 +422,7 @@ export class ACPAdapter implements ProviderAdapter {
             name: "swarm",
             url: `${config.apiUrl.replace(/\/+$/, "")}/mcp`,
             headers: [
-              { name: "Authorization", value: `Bearer ${config.apiKey}` },
+              { name: "Authorization", value: `Bearer ${ephemeralToken.plaintext}` },
               { name: "X-Agent-ID", value: config.agentId },
               { name: "X-Source-Task-Id", value: config.taskId },
             ],
@@ -413,13 +436,26 @@ export class ACPAdapter implements ProviderAdapter {
         newSession.configOptions ?? [],
         target.configuredOptions(config),
       );
-      session = new ACPSession(connection, proc, config, newSession.sessionId, {
-        target: target.target,
-        configOptions: sanitizeAcpConfigOptions(configOptions),
-      });
+      session = new ACPSession(
+        connection,
+        proc,
+        config,
+        newSession.sessionId,
+        {
+          target: target.target,
+          configOptions: sanitizeAcpConfigOptions(configOptions),
+        },
+        ephemeralToken.tokenId,
+      );
       for (const event of preSessionEvents) session.emitFromAcp(event);
       return session;
     } catch (err) {
+      // Revoke the ephemeral token before re-throwing if ACPSession has not yet
+      // taken ownership of it (i.e. setup failed after mint but before the
+      // ACPSession constructor ran).
+      if (ephemeralToken && !session) {
+        void revokeAcpSessionToken(config.apiUrl, config.apiKey, ephemeralToken.tokenId);
+      }
       await terminateProcessGroup(proc.pid);
       throw new Error(`ACP target failed during startup: ${scrubSecrets(formatError(err))}`);
     }

package/src/providers/pi-mono-adapter.ts

@@ -191,19 +191,36 @@ export async function checkPiMonoCredentials(
   env: Record<string, string | undefined>,
   opts: CredCheckOptions = {},
 ): Promise<CredStatus> {
-  // Determine Bedrock SDK mode:
-  //   - Explicit:  BEDROCK_AUTH_MODE=sdk
+  // Determine the Bedrock mode:
+  //   - Explicit:  BEDROCK_AUTH_MODE=sdk — the AWS SDK default credential chain
+  //   - Explicit:  BEDROCK_AUTH_MODE=bearer — an explicit Bedrock API key in
+  //                AWS_BEARER_TOKEN_BEDROCK, which the AWS SDK picks up as the
+  //                bearer identity for the Bedrock clients
   //   - Fallback:  BEDROCK_AUTH_MODE absent AND MODEL_OVERRIDE starts with
   //                "amazon-bedrock/" (preserves today's prefix-inference semantics)
-  // BEDROCK_AUTH_MODE=bearer is declared/validated but the full bearer-token
-  // path is not implemented yet — it falls through to the standard auth check.
+  // Both explicit modes share the region check and the enumeration probe; they
+  // differ in what has to be present up front and in how readiness is reported.
   const bedrockAuthMode = env.BEDROCK_AUTH_MODE?.toLowerCase();
+  const isBedrockBearer = bedrockAuthMode === "bearer";
   const isBedrockSdk =
     bedrockAuthMode === "sdk" ||
     (bedrockAuthMode === undefined &&
       env.MODEL_OVERRIDE?.toLowerCase().startsWith("amazon-bedrock/"));
 
-  if (isBedrockSdk) {
+  if (isBedrockBearer && !env.AWS_BEARER_TOKEN_BEDROCK) {
+    // The token is the whole point of this mode; without it there is nothing
+    // the probe could authenticate with, and the standard API keys do not
+    // apply to Bedrock, so do not fall through to them.
+    return {
+      ready: false,
+      missing: ["AWS_BEARER_TOKEN_BEDROCK"],
+      hint: "BEDROCK_AUTH_MODE=bearer requires AWS_BEARER_TOKEN_BEDROCK (a Bedrock API key); set it, or use BEDROCK_AUTH_MODE=sdk to authenticate through the AWS credential chain.",
+      bedrockModels: [],
+      bedrockRegion: env.AWS_REGION ?? "",
+    };
+  }
+
+  if (isBedrockSdk || isBedrockBearer) {
     const region = env.AWS_REGION;
     if (!region) {
       // Do NOT fabricate a region. A guessed `us-east-1` can differ from where
@@ -231,7 +248,7 @@ export async function checkPiMonoCredentials(
       return {
         ready: true,
         missing: [],
-        satisfiedBy: "sdk-delegated",
+        satisfiedBy: isBedrockBearer ? "env" : "sdk-delegated",
         hint: `Bedrock models invocable in ${region} enumerated (${bedrockModels.length} usable; ListFoundationModels + ListInferenceProfiles).`,
         bedrockModels,
         bedrockRegion: region,

package/src/scheduler/scheduler.test.ts

@@ -1,7 +1,7 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { unlinkSync } from "node:fs";
-import { closeDb, createScheduledTask, initDb } from "../be/db";
-import { calculateNextRun } from "./scheduler";
+import { closeDb, createAgent, createScheduledTask, createTaskExtended, initDb } from "../be/db";
+import { calculateNextRun, createStandaloneScheduleTask } from "./scheduler";
 
 const TEST_DB_PATH = "./test-scheduler.sqlite";
 
@@ -151,3 +151,50 @@ describe("calculateNextRun", () => {
     expect(nextRun).toBe("2026-01-19T09:00:00.000Z");
   });
 });
+
+describe("createStandaloneScheduleTask", () => {
+  test("passes the schedule's parentTaskId through to the created task", async () => {
+    const agent = await createAgent({
+      name: "Deferred Wake-up Worker",
+      description: "Agent that owns the deferred task",
+      role: "worker",
+      isLead: false,
+      status: "idle",
+      maxTasks: 1,
+      capabilities: [],
+    });
+    const parent = await createTaskExtended("original work that needed time", {
+      agentId: agent.id,
+      source: "mcp",
+    });
+
+    const schedule = await createScheduledTask({
+      name: "test-deferred-parent",
+      taskTemplate: `Resume task ${parent.id}: the deploy should be green now`,
+      scheduleType: "one_time",
+      nextRunAt: new Date(Date.now() + 60_000).toISOString(),
+      targetAgentId: agent.id,
+      createdByAgentId: agent.id,
+      taskType: "deferred",
+      tags: ["deferred"],
+      parentTaskId: parent.id,
+    });
+
+    const task = await createStandaloneScheduleTask(schedule);
+    expect(task.parentTaskId).toBe(parent.id);
+    expect(task.taskType).toBe("deferred");
+    expect(task.tags).toContain("deferred");
+  });
+
+  test("a schedule without parentTaskId creates a parentless task", async () => {
+    const schedule = await createScheduledTask({
+      name: "test-no-parent",
+      taskTemplate: "Ordinary scheduled work",
+      cronExpression: "0 9 * * *",
+      timezone: "UTC",
+    });
+
+    const task = await createStandaloneScheduleTask(schedule);
+    expect(task.parentTaskId).toBeFalsy();
+  });
+});

package/src/scheduler/scheduler.ts

@@ -73,6 +73,10 @@ export async function createStandaloneScheduleTask(
     source: "schedule",
     requestedByUserId: schedule.createdBy,
     contextKey: scheduleContextKey({ scheduleId: schedule.id }),
+    // Set only by `defer-task`. An explicit parent wins over the sibling-awareness
+    // auto-wiring (see withSiblingAwareness in src/tasks/sibling-awareness.ts), so
+    // the wake-up run continues the deferred task rather than a random sibling.
+    parentTaskId: schedule.parentTaskId,
   });
 }
 

package/src/scripts-runtime/sdk-allowlist.ts

@@ -12,6 +12,7 @@ export const SDK_TOOL_NAME_MAP = {
   task_list: "get-tasks",
   task_get: "get-task-details",
   task_storeProgress: "store-progress",
+  task_defer: "defer-task",
   task_poll: "poll-task",
   task_send: "send-task",
   task_cancel: "cancel-task", // destructive

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

@@ -143,6 +143,14 @@ declare module "swarm-sdk" {
     task_list(args?: Record<string, unknown>): Promise<unknown>;
     task_get(args: { taskId: string }): Promise<unknown>;
     task_storeProgress(args: Record<string, unknown>): Promise<unknown>;
+    task_defer(args: {
+      taskId: string;
+      delayMs?: number;
+      runAt?: string;
+      summary: string;
+      note: string;
+      checks?: string[];
+    }): Promise<unknown>;
     task_poll(args?: Record<string, unknown>): Promise<unknown>;
     // --- kv ---
     kv_get<T = unknown>(args: {

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

@@ -125,6 +125,14 @@ declare module "swarm-sdk" {
     task_list(args?: Record<string, unknown>): Promise<unknown>;
     task_get(args: { taskId: string }): Promise<unknown>;
     task_storeProgress(args: Record<string, unknown>): Promise<unknown>;
+    task_defer(args: {
+      taskId: string;
+      delayMs?: number;
+      runAt?: string;
+      summary: string;
+      note: string;
+      checks?: string[];
+    }): Promise<unknown>;
     task_poll(args?: Record<string, unknown>): Promise<unknown>;
     // --- kv ---
     kv_get<T = unknown>(args: {

package/src/server.ts

@@ -26,6 +26,7 @@ import { registerCreateMetricTool } from "./tools/create-metric";
 import { registerCreatePageTool } from "./tools/create-page";
 import { registerCredentialBindingsTool } from "./tools/credential-bindings";
 import { registerDbQueryTool } from "./tools/db-query";
+import { registerDeferTaskTool } from "./tools/defer-task";
 import { registerDeleteChannelTool } from "./tools/delete-channel";
 import { registerDeletePageTool } from "./tools/delete-page";
 import { registerGetMetricsTool } from "./tools/get-metrics";
@@ -421,6 +422,7 @@ export async function createServer(opts: { scriptsOnly?: boolean; fullSurface?:
   if (hasCapability("scheduling")) {
     registerListSchedulesTool(server);
     registerCreateScheduleTool(server);
+    registerDeferTaskTool(server);
     registerUpdateScheduleTool(server);
     registerPatchScheduleTool(server);
     registerDeleteScheduleTool(server);

package/src/slack/assistant.ts

@@ -2,10 +2,17 @@ import { Assistant } from "@slack/bolt";
 import { getAgentWorkingOnThread, getLeadAgent, getMostRecentTaskInThread } from "../be/db";
 import { resolveTemplate } from "../prompts/resolver";
 import { slackContextKey } from "../tasks/context-key";
-import { createTaskWithSiblingAwareness } from "../tasks/sibling-awareness";
 import { ackSlackMessage, reactionName } from "./ack";
 import { resolveSlackUserId, rewriteSlackMentions } from "./enrich";
 import { wasEventSeen } from "./event-dedup";
+import type { SlackFile } from "./files";
+import {
+  bufferedFileFailures,
+  buildEffectiveText,
+  createSlackTaskWithFiles,
+  fetchSlackFiles,
+  notifySlackFileFailures,
+} from "./inbound-files";
 import { ensureSlackThreadTree, isSlackRenderV2Enabled } from "./render-v2";
 import { hasOtherUserMention } from "./router";
 import { bufferThreadMessage, getBufferMessageCount } from "./thread-buffer";
@@ -80,12 +87,10 @@ export function createAssistant(): Assistant {
         const threadTs = (msg.thread_ts as string) || message.ts;
         const channelId = message.channel;
         const messageText = (msg.text as string) || "";
+        // `file_share` messages land here too: an image sent with no caption
+        // arrives with empty `text` and everything in `files`.
+        const files = msg.files as SlackFile[] | undefined;
         const userId = (msg.user as string) || "";
-        // Any in-body `<@U…>` mention the requester typed is rewritten via
-        // the identity primitive before it reaches agent-visible task text —
-        // never a raw Slack ID. Bot-mention routing checks below use the
-        // raw `messageText`, not this rendered copy.
-        const renderedMessageText = await rewriteSlackMentions(messageText);
 
         // Resolve the bot's own Slack user ID (cached after first call) so we can
         // check whether this message is actually addressed to us.
@@ -123,30 +128,55 @@ export function createAssistant(): Assistant {
         // 1. Check if an agent is already working in this thread
         const workingAgent = await getAgentWorkingOnThread(channelId, threadTs);
 
-        if (workingAgent && workingAgent.status !== "offline") {
-          // Follow-up message → route to the same agent
-          if (isAdditiveSlack()) {
-            bufferThreadMessage(channelId, threadTs, messageText, userId, message.ts);
-            const count = getBufferMessageCount(`${channelId}:${threadTs}`);
-            const event = count === 1 ? "accepted" : "buffered";
-            await ackSlackMessage(client, channelId, message.ts, reactionName(event), event);
-            await safeSetStatus("Queuing follow-up...");
-            return;
-          }
+        // Follow-up message → route to the same agent. Buffered follow-ups
+        // carry the `[File: …]` lines only; their files are not attached.
+        if (workingAgent && workingAgent.status !== "offline" && isAdditiveSlack()) {
+          const unattached = bufferedFileFailures(files);
+          bufferThreadMessage(
+            channelId,
+            threadTs,
+            buildEffectiveText(messageText, files, unattached),
+            userId,
+            message.ts,
+          );
+          const count = getBufferMessageCount(`${channelId}:${threadTs}`);
+          const event = count === 1 ? "accepted" : "buffered";
+          await ackSlackMessage(client, channelId, message.ts, reactionName(event), event);
+          await notifySlackFileFailures(client, channelId, threadTs, unattached);
+          await safeSetStatus("Queuing follow-up...");
+          return;
+        }
+
+        // Fetch shared files before the task text is final: a file that can't be
+        // downloaded is flagged in it.
+        if (files?.length) await safeSetStatus("Downloading attachments...");
+        await using inbound = await fetchSlackFiles(client, files);
+        // Any in-body `<@U…>` mention the requester typed is rewritten via
+        // the identity primitive before it reaches agent-visible task text —
+        // never a raw Slack ID. Bot-mention routing checks above use the
+        // raw `messageText`, not this rendered copy.
+        const renderedMessageText = await rewriteSlackMentions(
+          buildEffectiveText(messageText, inbound.files, inbound.failed),
+        );
 
+        if (workingAgent && workingAgent.status !== "offline") {
           // Otherwise, create a follow-up task for the working agent
           const latestTask = await getMostRecentTaskInThread(channelId, threadTs);
-          const task = await createTaskWithSiblingAwareness(renderedMessageText, {
-            agentId: workingAgent.id,
-            source: "slack",
-            slackChannelId: channelId,
-            slackThreadTs: threadTs,
-            slackTriggerMessageTs: message.ts,
-            slackUserId: userId,
-            parentTaskId: latestTask?.id,
-            requestedByUserId,
-            contextKey: slackContextKey({ channelId, threadTs }),
-          });
+          const { task, unattached } = await createSlackTaskWithFiles(
+            renderedMessageText,
+            {
+              agentId: workingAgent.id,
+              source: "slack",
+              slackChannelId: channelId,
+              slackThreadTs: threadTs,
+              slackTriggerMessageTs: message.ts,
+              slackUserId: userId,
+              parentTaskId: latestTask?.id,
+              requestedByUserId,
+              contextKey: slackContextKey({ channelId, threadTs }),
+            },
+            inbound,
+          );
           await ackSlackMessage(
             client,
             channelId,
@@ -154,6 +184,7 @@ export function createAssistant(): Assistant {
             reactionName("accepted"),
             "accepted",
           );
+          await notifySlackFileFailures(client, channelId, threadTs, unattached);
 
           if (isSlackRenderV2Enabled()) await ensureSlackThreadTree([task.id]);
 
@@ -182,15 +213,19 @@ export function createAssistant(): Assistant {
         const lead = await getLeadAgent();
         if (!lead) {
           // No lead — still queue the task
-          const task = await createTaskWithSiblingAwareness(renderedMessageText + channelContext, {
-            source: "slack",
-            slackChannelId: channelId,
-            slackThreadTs: threadTs,
-            slackTriggerMessageTs: message.ts,
-            slackUserId: userId,
-            requestedByUserId,
-            contextKey: slackContextKey({ channelId, threadTs }),
-          });
+          const { task, unattached } = await createSlackTaskWithFiles(
+            renderedMessageText + channelContext,
+            {
+              source: "slack",
+              slackChannelId: channelId,
+              slackThreadTs: threadTs,
+              slackTriggerMessageTs: message.ts,
+              slackUserId: userId,
+              requestedByUserId,
+              contextKey: slackContextKey({ channelId, threadTs }),
+            },
+            inbound,
+          );
           await ackSlackMessage(
             client,
             channelId,
@@ -198,6 +233,7 @@ export function createAssistant(): Assistant {
             reactionName("accepted"),
             "accepted",
           );
+          await notifySlackFileFailures(client, channelId, threadTs, unattached);
           if (isSlackRenderV2Enabled()) {
             await ensureSlackThreadTree([task.id]);
           } else {
@@ -207,17 +243,22 @@ export function createAssistant(): Assistant {
           return;
         }
 
-        const task = await createTaskWithSiblingAwareness(renderedMessageText + channelContext, {
-          agentId: lead.id,
-          source: "slack",
-          slackChannelId: channelId,
-          slackThreadTs: threadTs,
-          slackTriggerMessageTs: message.ts,
-          slackUserId: userId,
-          requestedByUserId,
-          contextKey: slackContextKey({ channelId, threadTs }),
-        });
+        const { task, unattached } = await createSlackTaskWithFiles(
+          renderedMessageText + channelContext,
+          {
+            agentId: lead.id,
+            source: "slack",
+            slackChannelId: channelId,
+            slackThreadTs: threadTs,
+            slackTriggerMessageTs: message.ts,
+            slackUserId: userId,
+            requestedByUserId,
+            contextKey: slackContextKey({ channelId, threadTs }),
+          },
+          inbound,
+        );
         await ackSlackMessage(client, channelId, message.ts, reactionName("accepted"), "accepted");
+        await notifySlackFileFailures(client, channelId, threadTs, unattached);
         if (isSlackRenderV2Enabled()) await ensureSlackThreadTree([task.id]);
         // setStatus shows typing indicator — watcher will post final result when done
       } catch (error) {

package/src/slack/handlers.test.ts

@@ -17,15 +17,13 @@ import { createAssistant } from "./assistant";
 import * as slackEnrichModule from "./enrich";
 import type { SlackFile } from "./files";
 import {
-  buildAttachmentText,
-  buildEffectiveText,
   checkUserAccess,
-  formatFileSize,
   isBotMessage,
   isSwarmThreadRoot,
   registerMessageHandler,
   type UserFilterConfig,
 } from "./handlers";
+import { buildAttachmentText, buildEffectiveText, formatFileSize } from "./inbound-files";
 import { SLACK_REACTION_CONFIG_KEYS } from "./reaction-shortcode";
 
 describe("checkUserAccess", () => {