@desplega.ai/agent-swarm 2.2.0 → 2.3.0

package/src/heartbeat/heartbeat.ts

@@ -48,6 +48,7 @@ import {
   settleSupersededTaskDependents,
   supersedeTask,
   updateAgentStatus,
+  upsertKv,
 } from "../be/db";
 import { repointTrackerSyncBySwarmId } from "../be/db-queries/tracker";
 import { poolTaskRunsOnHarness } from "../be/model-validation";
@@ -1461,7 +1462,10 @@ export function isEffectivelyEmpty(content: string): boolean {
 /**
  * Gather current system status as a markdown string for the lead's checklist task.
  */
-export async function gatherSystemStatus(options?: { isBootTriage?: boolean }): Promise<string> {
+export async function gatherSystemStatus(options?: {
+  isBootTriage?: boolean;
+  reportedFailures?: Array<{ id: string; line: string }>;
+}): Promise<string> {
   const stats = await getTaskStats();
   const stalledTasks = await getStalledInProgressTasks(stallThresholdMinutes());
   const agents = await getAllAgents();
@@ -1494,6 +1498,7 @@ export async function gatherSystemStatus(options?: { isBootTriage?: boolean }):
 
   // Recent failures with reasons and pattern detection (last 6 hours)
   const recentFailures = await getRecentFailedTasks(6);
+  const renderedFailures = recentFailures.slice(0, 10);
   if (recentFailures.length > 0) {
     sections.push("");
     sections.push("## Recent Failures (last 6h) [auto-generated]");
@@ -1520,12 +1525,12 @@ export async function gatherSystemStatus(options?: { isBootTriage?: boolean }):
 
     // List individual failures (max 10)
     sections.push("");
-    for (const task of recentFailures.slice(0, 10)) {
+    for (const task of renderedFailures) {
       const agentSlice = task.agentId?.slice(0, 8) ?? "unassigned";
       const reason = task.failureReason?.slice(0, 100) ?? "no reason";
-      sections.push(
-        `- [${task.id.slice(0, 8)}] "${task.task.slice(0, 50)}" — agent: ${agentSlice}, reason: ${reason}, at: ${task.finishedAt}`,
-      );
+      const line = `- [${task.id.slice(0, 8)}] "${task.task.slice(0, 50)}" — agent: ${agentSlice}, reason: ${reason}, at: ${task.finishedAt}`;
+      sections.push(line);
+      options?.reportedFailures?.push({ id: task.id, line });
     }
     if (recentFailures.length > 10) {
       sections.push(`- ... and ${recentFailures.length - 10} more`);
@@ -1786,7 +1791,8 @@ export async function checkHeartbeatChecklist(): Promise<void> {
     return;
   }
 
-  let systemStatus = await gatherSystemStatus();
+  const reportedFailures: Array<{ id: string; line: string }> = [];
+  let systemStatus = await gatherSystemStatus({ reportedFailures });
   // Shadow mode leaves the prompt untouched so the Lead's own quiet/non-quiet
   // outcome stays an independent check on the gate's verdict.
   if (gateMode === "enforce" && gate?.verdict === "wake" && gate.summary) {
@@ -1803,7 +1809,7 @@ export async function checkHeartbeatChecklist(): Promise<void> {
 
   if (result.skipped) return;
 
-  await createTaskExtended(result.text, {
+  const task = await createTaskExtended(result.text, {
     agentId: lead.id,
     routingReason: "skill",
     routingSource: "engine_default",
@@ -1815,6 +1821,18 @@ export async function checkHeartbeatChecklist(): Promise<void> {
     priority: 60,
   });
 
+  try {
+    await upsertKv({
+      namespace: "heartbeat-checklist:reported-failures",
+      key: task.id,
+      value: reportedFailures.filter(({ line }) => result.text.includes(line)).map(({ id }) => id),
+      valueType: "json",
+      expiresAt: Date.now() + 7 * 24 * 3600e3,
+    });
+  } catch (err) {
+    console.error(`[Heartbeat] Failed to save reported failures for checklist ${task.id}:`, err);
+  }
+
   console.log(`[Heartbeat] Checklist task created for lead ${lead.name}`);
 }
 

package/src/http/assets.ts

@@ -7,6 +7,7 @@ import { resolveHttpAuditUserId } from "../be/audit-user";
 import {
   getDb,
   getDbClient,
+  getRootTaskChain,
   getTaskById,
   listAssetSummaries,
   moveAssetKey,
@@ -120,10 +121,17 @@ function ensureOperator(req: IncomingMessage, res: ServerResponse): boolean {
 }
 
 const moveAssetBodySchema = z.object({ key: AssetKeySchema });
+const moveGenericAssetBodySchema = moveAssetBodySchema.extend({
+  cascade: z
+    .boolean()
+    .optional()
+    .describe("For tasks only, also move every descendant task recursively through parentTaskId."),
+});
 const moveAssetSuccessSchema = z.object({
   entityType: AssetEntityTypeSchema,
   id: z.string(),
   key: AssetKeySchema,
+  movedTaskIds: z.array(z.string()).optional(),
 });
 const moveAssetResponses = {
   200: { description: "Asset namespace updated", schema: moveAssetSuccessSchema },
@@ -168,7 +176,7 @@ const moveAssetRoute = route({
     "Updates namespace metadata only. Provider-backed files keep the same provider key, org, and drive; no remote move occurs. Personal keys are labels, not a privacy guarantee.",
   tags: ["Assets"],
   params: z.object({ entityType: AssetEntityTypeSchema, id: z.string().min(1) }),
-  body: moveAssetBodySchema,
+  body: moveGenericAssetBodySchema,
   responses: moveAssetResponses,
   rbac: {
     ungated:
@@ -302,17 +310,29 @@ export async function handleAssets(
   ) {
     const parsed = await moveAssetRoute.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
+    if (parsed.body.cascade && parsed.params.entityType !== "task") {
+      jsonError(res, "Cascade is only supported for task namespace moves", 400);
+      return true;
+    }
     if (parsed.params.entityType === "file" && !ensureOperator(req, res)) return true;
+    let descendantTaskIds: string[] | undefined;
     if (parsed.params.entityType === "task") {
       const task = await getTaskById(parsed.params.id);
       if (!task) {
         jsonError(res, "Asset not found", 404);
         return true;
       }
-      if (!(await canMutateTaskNamespace(task, myAgentId, req))) {
-        jsonError(res, "Not authorized to move this task namespace", 403);
-        return true;
+      // Only the tasks checked here move: a subtask created after this read stays put.
+      const tasks = parsed.body.cascade ? await getRootTaskChain(task.id) : [task];
+      for (const target of tasks) {
+        if (!(await canMutateTaskNamespace(target, myAgentId, req))) {
+          jsonError(res, "Not authorized to move this task namespace", 403);
+          return true;
+        }
       }
+      descendantTaskIds = tasks
+        .filter((target) => target.id !== task.id)
+        .map((target) => target.id);
     }
     if (parsed.params.entityType === "app") {
       if (!(await getApp(parsed.params.id))) {
@@ -344,6 +364,7 @@ export async function handleAssets(
         id: parsed.params.id,
         key,
         changedBy: actor ?? undefined,
+        descendantTaskIds,
       });
       if (!moved) {
         jsonError(res, "Asset not found", 404);
@@ -353,6 +374,7 @@ export async function handleAssets(
         entityType: parsed.params.entityType,
         id: parsed.params.id,
         key,
+        ...moved,
       });
     } catch (error) {
       if (error instanceof AssetKeyAuthorizationError) {

package/src/http/inbox-state.ts

@@ -1,6 +1,6 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
-import { listInboxState, upsertInboxState } from "../be/db";
+import { getDbClient, listInboxState, upsertInboxState } from "../be/db";
 import { InboxItemStateSchema, InboxItemStatusSchema, InboxItemTypeSchema } from "../types";
 import { route } from "./route-def";
 import { jsonError } from "./utils";
@@ -29,29 +29,60 @@ const listState = route({
   auth: { apiKey: true },
 });
 
+const inboxStateItemSchema = z.object({
+  itemType: InboxItemTypeSchema,
+  itemId: z.string().min(1),
+  status: InboxItemStatusSchema,
+  snoozeUntil: z.string().datetime().optional(),
+  readAt: z.string().datetime().optional(),
+  lastReadAt: z
+    .string()
+    .datetime()
+    .nullable()
+    .optional()
+    .describe(
+      "Omit to preserve the read cursor, send null to clear it, or send a timestamp to set it, including an earlier time.",
+    ),
+});
+
 const upsertState = route({
   method: "patch",
   path: "/api/inbox-state",
   pattern: ["api", "inbox-state"],
   summary: "Upsert per-user dismiss/snooze/done state for an inbox item",
   tags: ["Inbox State"],
+  body: inboxStateItemSchema.extend({ userId: z.string() }),
+  responses: {
+    200: {
+      description: "Upserted inbox state row",
+      schema: z.object({ item: InboxItemStateSchema }),
+    },
+    400: { description: "Validation error" },
+    401: { description: "Unauthorized" },
+  },
+  auth: { apiKey: true },
+});
+
+const bulkUpsertState = route({
+  method: "patch",
+  path: "/api/inbox-state/bulk",
+  pattern: ["api", "inbox-state", "bulk"],
+  summary: "Upsert inbox-item state in one transaction",
+  tags: ["Inbox State"],
   body: z.object({
     userId: z.string(),
-    itemType: InboxItemTypeSchema,
-    itemId: z.string().min(1),
-    status: InboxItemStatusSchema,
-    snoozeUntil: z.string().datetime().optional(),
-    readAt: z.string().datetime().optional(),
+    items: z.array(inboxStateItemSchema).min(1).max(200),
   }),
   responses: {
     200: {
-      description: "Upserted inbox state row",
-      schema: z.object({ item: InboxItemStateSchema }),
+      description: "Upserted inbox state rows in request order",
+      schema: z.object({ items: z.array(InboxItemStateSchema) }),
     },
     400: { description: "Validation error" },
     401: { description: "Unauthorized" },
   },
   auth: { apiKey: true },
+  rbac: { ungated: "per-user inbox UI state, same posture as PATCH /api/inbox-state" },
 });
 
 // ─── Handler ─────────────────────────────────────────────────────────────────
@@ -74,6 +105,24 @@ export async function handleInboxState(
     return true;
   }
 
+  if (bulkUpsertState.match(req.method, pathSegments)) {
+    const parsed = await bulkUpsertState.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    try {
+      const items = await getDbClient().transaction(async () => {
+        const rows = [];
+        for (const item of parsed.body.items) {
+          rows.push(await upsertInboxState({ ...item, userId: parsed.body.userId }));
+        }
+        return rows;
+      });
+      bulkUpsertState.respond(res, 200, { items });
+    } catch (err) {
+      jsonError(res, err instanceof Error ? err.message : "Failed to upsert inbox state", 500);
+    }
+    return true;
+  }
+
   if (upsertState.match(req.method, pathSegments)) {
     const parsed = await upsertState.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
@@ -85,6 +134,7 @@ export async function handleInboxState(
         status: parsed.body.status,
         snoozeUntil: parsed.body.snoozeUntil,
         readAt: parsed.body.readAt,
+        lastReadAt: parsed.body.lastReadAt,
       });
       upsertState.respond(res, 200, { item });
     } catch (err) {

package/src/kv-reserved-namespaces.ts

@@ -8,6 +8,7 @@ const RESERVED_FAMILIES = new Map([
   ["apps", "namespace is reserved for swarm apps; use the app row endpoints"],
   // step-9: Comb's "Send to swarm" claims (`comb:sent`).
   ["comb", "namespace is reserved for Comb; use POST /api/comb/review-batches"],
+  ["heartbeat-checklist", "namespace is reserved for heartbeat checklist receipts"],
   ["worker", "namespace is reserved for worker nudges"],
   // Durable dedupe for SLACK_BLOCK_EXTERNAL_CHANNELS alerts (src/slack/external-channel.ts).
   ["slack-external-alert", "namespace is reserved for Slack external channel alerts"],

package/src/providers/amp-adapter.ts

@@ -44,7 +44,7 @@ import type {
  * default; the image installs exactly this version and the per-task settings
  * set `amp.updates.mode: "disabled"`. Bump it deliberately, with a live run.
  */
-export const AMP_PACKAGE = "@ampcode/cli@0.0.1792238457-g6ec988";
+export const AMP_PACKAGE = "@ampcode/cli@0.0.1792296040-g5ce754";
 
 /** MCP server name. Amp exposes its tools as `agent_swarm` / `store_progress` (dashes become underscores). */
 const AMP_MCP_SERVER_NAME = "agent-swarm";

package/src/tests/asset-key-api.test.ts

@@ -11,8 +11,11 @@ import {
   createAgent,
   createTaskExtended,
   createUser,
+  getAssetKeyMappingByProvider,
   getDbClient,
+  getTaskById,
   initDb,
+  insertTaskAttachment,
 } from "../be/db";
 import { insertScript } from "../be/scripts/db";
 import { handleAssets } from "../http/assets";
@@ -343,4 +346,129 @@ describe("asset namespace REST contract", () => {
     expect(audit.body.structuralValid).toBe(true);
     expect(audit.body.warningCount).toBe(0);
   });
+
+  test("cascade moves descendants and sourced mappings without stamping task activity", async () => {
+    const root = await createTaskExtended("cascade root", { agentId, key: "shared/cascade/" });
+    const child = await createTaskExtended("cascade child", { agentId, parentTaskId: root.id });
+    const leaf = await createTaskExtended("cascade leaf", { agentId, parentTaskId: child.id });
+    const unchanged = await createTaskExtended("already moved", {
+      agentId,
+      parentTaskId: root.id,
+      key: "shared/cascade-target/",
+    });
+    const provider = { providerId: "agent-fs", providerKey: "cascade-file.md" };
+    await insertTaskAttachment({
+      taskId: leaf.id,
+      name: "cascade-file.md",
+      kind: "agent-fs",
+      ...provider,
+    });
+    const mapping = (await getAssetKeyMappingByProvider(provider))!;
+    const lastUpdatedAt = "2026-01-01T00:00:00.000Z";
+    for (const task of [root, child, leaf, unchanged]) {
+      await getDbClient().run("UPDATE agent_tasks SET lastUpdatedAt = ? WHERE id = ?", [
+        lastUpdatedAt,
+        task.id,
+      ]);
+    }
+    const move = await api(
+      "PATCH",
+      `/api/assets/task/${root.id}/key`,
+      {
+        key: "shared/cascade-target/",
+        cascade: true,
+      },
+      { agentId },
+    );
+    expect(move.status).toBe(200);
+    expect(move.body.movedTaskIds).toEqual([root.id, child.id, leaf.id]);
+    for (const task of [root, child, leaf, unchanged]) {
+      const moved = (await getTaskById(task.id))!;
+      expect(moved.key).toBe("shared/cascade-target/");
+      expect(moved.lastUpdatedAt).toBe(lastUpdatedAt);
+    }
+    expect((await getAssetKeyMappingByProvider(provider))?.key).toBe("shared/cascade-target/");
+    const history = await getDbClient().query<{ entity_id: string }>(
+      "SELECT entity_id FROM asset_key_history WHERE entity_id IN (?, ?, ?, ?, ?) AND new_key = ?",
+      [root.id, child.id, leaf.id, unchanged.id, mapping.id, "shared/cascade-target/"],
+    );
+    expect(history.map((row) => row.entity_id).sort()).toEqual(
+      [root.id, child.id, leaf.id, mapping.id].sort(),
+    );
+    expect(
+      (
+        await api(
+          "PATCH",
+          `/api/assets/task/${root.id}/key`,
+          {
+            key: "shared/cascade-target/",
+            cascade: true,
+          },
+          { agentId },
+        )
+      ).body.movedTaskIds,
+    ).toEqual([]);
+
+    // The root can already have the destination key while descendants still need a move.
+    await getDbClient().run('UPDATE agent_tasks SET "key" = ? WHERE id = ?', [
+      "shared/other-child/",
+      child.id,
+    ]);
+    expect(
+      (
+        await api(
+          "PATCH",
+          `/api/assets/task/${root.id}/key`,
+          {
+            key: "shared/cascade-target/",
+            cascade: true,
+          },
+          { agentId },
+        )
+      ).body.movedTaskIds,
+    ).toEqual([child.id]);
+  });
+
+  test("cascade denies the whole move when a descendant is not authorized", async () => {
+    const root = await createTaskExtended("allowed root", { agentId });
+    const child = await createTaskExtended("denied child", {
+      agentId: secondAgentId,
+      creatorAgentId: secondAgentId,
+      parentTaskId: root.id,
+    });
+    const move = await api(
+      "PATCH",
+      `/api/assets/task/${root.id}/key`,
+      {
+        key: "shared/must-not-move/",
+        cascade: true,
+      },
+      { agentId },
+    );
+    expect(move.status).toBe(403);
+    expect((await getTaskById(root.id))?.key).toBe(root.key);
+    expect((await getTaskById(child.id))?.key).toBe(child.key);
+    expect(
+      await getDbClient().query("SELECT id FROM asset_key_history WHERE entity_id IN (?, ?)", [
+        root.id,
+        child.id,
+      ]),
+    ).toEqual([]);
+  });
+
+  test("cascade is rejected for non-task entities", async () => {
+    for (const entityType of ["workflow", "schedule", "page", "file", "app", "script"]) {
+      const move = await api(
+        "PATCH",
+        `/api/assets/${entityType}/${crypto.randomUUID()}/key`,
+        {
+          key: "shared/invalid-cascade/",
+          cascade: true,
+        },
+        { operator: true },
+      );
+      expect(move.status).toBe(400);
+      expect(move.body.error).toContain("only supported for task");
+    }
+  });
 });

package/src/tests/asset-key-invariants.test.ts

@@ -9,6 +9,8 @@ import {
   createTaskExtended,
   createUser,
   createWorkflow,
+  deleteTask,
+  deleteTaskAttachment,
   getAssetKeyMappingByProvider,
   getDb,
   getDbClient,
@@ -166,6 +168,11 @@ describe("cross-entity asset namespace invariants", () => {
       ).sourceEntityType,
     ).toBe("task-attachment");
 
+    const lastUpdatedAt = "2026-01-01T00:00:00.000Z";
+    await getDbClient().run("UPDATE agent_tasks SET lastUpdatedAt = ? WHERE id = ?", [
+      lastUpdatedAt,
+      task.id,
+    ]);
     expect(
       await moveAssetKey({
         entityType: "task",
@@ -173,7 +180,8 @@ describe("cross-entity asset namespace invariants", () => {
         key: "shared/archive/",
         changedBy: userId,
       }),
-    ).toBe(true);
+    ).toEqual({ movedTaskIds: [task.id] });
+    expect((await getTaskById(task.id))?.lastUpdatedAt).toBe(lastUpdatedAt);
     expect((await getTaskById(task.id))?.key).toBe("shared/archive/");
     const after = await getAssetKeyMappingByProvider({
       providerId: "agent-fs",
@@ -251,7 +259,7 @@ describe("cross-entity asset namespace invariants", () => {
         key: "shared/products/",
         changedBy: userId,
       }),
-    ).toBe(true);
+    ).toEqual({});
     expect(
       await moveAssetKey({
         entityType: "script",
@@ -259,7 +267,7 @@ describe("cross-entity asset namespace invariants", () => {
         key: "shared/automation/",
         changedBy: userId,
       }),
-    ).toBe(true);
+    ).toEqual({});
 
     expect(
       await getDbClient().get<{ key: string }>('SELECT "key" AS key FROM apps WHERE id = ?', [
@@ -330,6 +338,174 @@ describe("cross-entity asset namespace invariants", () => {
     expect(auditAssetKeys(getDb()).warningCount).toBe(0);
   });
 
+  test("shared provider files allow moves and follow only their source task", async () => {
+    const first = await createTaskExtended("first attachment owner", {
+      agentId,
+      key: "shared/first/",
+    });
+    const source = await createTaskExtended("source attachment owner", {
+      agentId,
+      key: "shared/source/",
+    });
+    const provider = {
+      providerId: "agent-fs",
+      providerOrgId: "shared-org",
+      providerDriveId: "shared-drive",
+      providerKey: "shared-file.md",
+    };
+    for (const task of [first, source]) {
+      await insertTaskAttachment({
+        taskId: task.id,
+        name: "shared-file.md",
+        kind: "agent-fs",
+        providerId: provider.providerId,
+        providerKey: provider.providerKey,
+        orgId: provider.providerOrgId,
+        driveId: provider.providerDriveId,
+      });
+    }
+    const mapping = (await getAssetKeyMappingByProvider(provider))!;
+    expect(mapping.key).toBe(source.key);
+    const historyBefore = await getDbClient().query(
+      "SELECT id FROM asset_key_history WHERE entity_id = ? ORDER BY id",
+      [mapping.id],
+    );
+    expect(auditAssetKeys(getDb()).ok).toBe(true);
+
+    await moveAssetKey({ entityType: "task", id: first.id, key: "shared/first-moved/" });
+    expect(await getAssetKeyMappingByProvider(provider)).toEqual(mapping);
+    expect(auditAssetKeys(getDb()).ok).toBe(true);
+    expect(
+      await getDbClient().query(
+        "SELECT id FROM asset_key_history WHERE entity_id = ? ORDER BY id",
+        [mapping.id],
+      ),
+    ).toEqual(historyBefore);
+
+    await moveAssetKey({ entityType: "task", id: source.id, key: "shared/source-moved/" });
+    expect((await getAssetKeyMappingByProvider(provider))?.key).toBe("shared/source-moved/");
+    expect(auditAssetKeys(getDb()).ok).toBe(true);
+    expect(
+      await getDbClient().query("SELECT entity_type FROM asset_key_history WHERE entity_id = ?", [
+        mapping.id,
+      ]),
+    ).toHaveLength(historyBefore.length + 1);
+
+    await getDbClient().run(
+      `UPDATE asset_key_mappings SET "key" = 'shared/no-attaching-task/' WHERE id = ?`,
+      [mapping.id],
+    );
+    const drift = auditAssetKeys(getDb()).issues.filter(
+      (issue) => issue.code === "provider-mapping-drift",
+    );
+    expect(drift).toHaveLength(1);
+    expect(drift[0]?.entityId).toBe(mapping.id);
+    await expect(
+      moveAssetKey({ entityType: "task", id: first.id, key: "shared/blocked/" }),
+    ).rejects.toThrow("blocked until");
+    await getDbClient().run(
+      `UPDATE asset_key_mappings SET "key" = ?, source_entity_type = 'task-attachment', source_entity_id = ? WHERE id = ?`,
+      ["shared/source-moved/", mapping.sourceEntityId!, mapping.id],
+    );
+    expect(auditAssetKeys(getDb()).ok).toBe(true);
+  });
+
+  test("a task move takes only the descendants the caller passes", async () => {
+    const root = await createTaskExtended("partial root", { agentId, key: "shared/partial/" });
+    const checked = await createTaskExtended("checked child", { agentId, parentTaskId: root.id });
+    const unchecked = await createTaskExtended("unchecked child", {
+      agentId,
+      parentTaskId: root.id,
+    });
+
+    expect(
+      await moveAssetKey({
+        entityType: "task",
+        id: root.id,
+        key: "shared/partial-moved/",
+        descendantTaskIds: [checked.id],
+      }),
+    ).toEqual({ movedTaskIds: [root.id, checked.id] });
+    expect((await getTaskById(checked.id))?.key).toBe("shared/partial-moved/");
+    expect((await getTaskById(unchecked.id))?.key).toBe("shared/partial/");
+  });
+
+  test("deleting the source attachment of a shared file leaves moves open", async () => {
+    const [kept, deleted, removed] = await Promise.all(
+      ["shared/detach-a/", "shared/detach-b/", "shared/detach-c/"].map((key) =>
+        createTaskExtended(`detach ${key}`, { agentId, key }),
+      ),
+    );
+    const other = await createTaskExtended("unrelated move", { agentId, key: "shared/other/" });
+    const provider = {
+      providerId: "agent-fs",
+      providerOrgId: "shared-org",
+      providerDriveId: "shared-drive",
+      providerKey: "detach.md",
+    };
+    const attach = (taskId: string) =>
+      insertTaskAttachment({
+        taskId,
+        name: "detach.md",
+        kind: "agent-fs",
+        providerId: provider.providerId,
+        providerKey: provider.providerKey,
+        orgId: provider.providerOrgId,
+        driveId: provider.providerDriveId,
+      });
+    await attach(kept!.id);
+    const sourceAttachment = await attach(deleted!.id);
+    expect((await getAssetKeyMappingByProvider(provider))?.key).toBe("shared/detach-b/");
+
+    expect(await deleteTaskAttachment(sourceAttachment.id)).toBe(true);
+    expect(await getAssetKeyMappingByProvider(provider)).toMatchObject({
+      key: "shared/detach-b/",
+      sourceEntityType: "external",
+    });
+    expect(auditAssetKeys(getDb()).ok).toBe(true);
+    await moveAssetKey({ entityType: "task", id: other.id, key: "shared/other-moved/" });
+
+    await attach(removed!.id);
+    expect(await deleteTask(removed!.id)).toBe(true);
+    expect(await getAssetKeyMappingByProvider(provider)).toMatchObject({
+      key: "shared/detach-c/",
+      sourceEntityType: "external",
+    });
+    expect(auditAssetKeys(getDb()).ok).toBe(true);
+
+    await moveAssetKey({ entityType: "task", id: kept!.id, key: "shared/detach-moved/" });
+    expect((await getAssetKeyMappingByProvider(provider))?.key).toBe("shared/detach-moved/");
+    expect(auditAssetKeys(getDb()).ok).toBe(true);
+  });
+
+  test("an external mapping that a task still attaches follows that task's move", async () => {
+    const task = await createTaskExtended("external owner", { agentId, key: "shared/external/" });
+    const provider = {
+      providerId: "agent-fs",
+      providerOrgId: "shared-org",
+      providerDriveId: "shared-drive",
+      providerKey: "external.md",
+    };
+    await insertTaskAttachment({
+      taskId: task.id,
+      name: "external.md",
+      kind: "agent-fs",
+      providerId: provider.providerId,
+      providerKey: provider.providerKey,
+      orgId: provider.providerOrgId,
+      driveId: provider.providerDriveId,
+    });
+    const mapping = (await getAssetKeyMappingByProvider(provider))!;
+    await getDbClient().run(
+      "UPDATE asset_key_mappings SET source_entity_type = 'external', source_entity_id = NULL WHERE id = ?",
+      [mapping.id],
+    );
+
+    await moveAssetKey({ entityType: "task", id: task.id, key: "shared/external-moved/" });
+    expect((await getAssetKeyMappingByProvider(provider))?.key).toBe("shared/external-moved/");
+    expect(auditAssetKeys(getDb()).ok).toBe(true);
+  });
+
   test("personal namespace users are audited and missing users are repairable warnings", async () => {
     const task = await createTaskExtended("personal", {
       agentId,