feat(FN-1096): add task agent assignment persistence and API

- Add assignedAgentId to core task types, database schema migration, and TaskStore persistence flows
- Implement dashboard assignment API routes for setting and clearing task-to-agent assignments
- Expand core and dashboard test coverage for persistence, migration behavior, and assignment route handling
- Add a changeset for the published CLI package to document the assignment core update

packages/dashboard/src/routes.test.ts

@@ -1874,6 +1874,116 @@ describe("PATCH /tasks/:id", () => {
 });
 
 
+describe("PATCH /tasks/:id/assign and GET /agents/:id/tasks", () => {
+  let tempDir: string;
+  let fusionDir: string;
+  let agentId: string;
+  let store: TaskStore;
+
+  beforeEach(async () => {
+    tempDir = mkdtempSync(join(tmpdir(), "kb-routes-task-assign-"));
+    fusionDir = join(tempDir, ".fusion");
+    mkdirSync(fusionDir, { recursive: true });
+
+    const { AgentStore } = await import("@fusion/core");
+    const agentStore = new AgentStore({ rootDir: fusionDir });
+    await agentStore.init();
+    const agent = await agentStore.createAgent({
+      name: "Assignment test agent",
+      role: "executor",
+    });
+    agentId = agent.id;
+
+    store = createMockStore({
+      getFusionDir: vi.fn().mockReturnValue(fusionDir),
+      updateTask: vi.fn(),
+      listTasks: vi.fn().mockResolvedValue([]),
+    } as any);
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  function buildApp() {
+    const app = express();
+    app.use(express.json());
+    app.use("/api", createApiRoutes(store));
+    return app;
+  }
+
+  it("assigns a task to an existing agent", async () => {
+    (store.updateTask as ReturnType<typeof vi.fn>).mockResolvedValue({
+      ...FAKE_TASK_DETAIL,
+      id: "FN-200",
+      assignedAgentId: agentId,
+    });
+
+    const res = await REQUEST(buildApp(), "PATCH", "/api/tasks/FN-200/assign", JSON.stringify({ agentId }), {
+      "Content-Type": "application/json",
+    });
+
+    expect(res.status).toBe(200);
+    expect(store.updateTask).toHaveBeenCalledWith("FN-200", { assignedAgentId: agentId });
+    expect(res.body.assignedAgentId).toBe(agentId);
+  });
+
+  it("returns 404 when assigning to a non-existent agent", async () => {
+    const res = await REQUEST(
+      buildApp(),
+      "PATCH",
+      "/api/tasks/FN-200/assign",
+      JSON.stringify({ agentId: "agent-missing" }),
+      { "Content-Type": "application/json" },
+    );
+
+    expect(res.status).toBe(404);
+    expect(res.body.error).toBe("Agent not found");
+    expect(store.updateTask).not.toHaveBeenCalled();
+  });
+
+  it("unassigns a task when agentId is null", async () => {
+    (store.updateTask as ReturnType<typeof vi.fn>).mockResolvedValue({
+      ...FAKE_TASK_DETAIL,
+      id: "FN-200",
+      assignedAgentId: undefined,
+    });
+
+    const res = await REQUEST(
+      buildApp(),
+      "PATCH",
+      "/api/tasks/FN-200/assign",
+      JSON.stringify({ agentId: null }),
+      { "Content-Type": "application/json" },
+    );
+
+    expect(res.status).toBe(200);
+    expect(store.updateTask).toHaveBeenCalledWith("FN-200", { assignedAgentId: null });
+    expect(res.body.assignedAgentId).toBeUndefined();
+  });
+
+  it("returns tasks assigned to the specified agent", async () => {
+    (store.listTasks as ReturnType<typeof vi.fn>).mockResolvedValue([
+      { ...FAKE_TASK_DETAIL, id: "FN-001", assignedAgentId: agentId },
+      { ...FAKE_TASK_DETAIL, id: "FN-002", assignedAgentId: "agent-other" },
+      { ...FAKE_TASK_DETAIL, id: "FN-003" },
+    ]);
+
+    const res = await GET(buildApp(), `/api/agents/${agentId}/tasks`);
+
+    expect(res.status).toBe(200);
+    expect(res.body.map((task: { id: string }) => task.id)).toEqual(["FN-001"]);
+  });
+
+  it("returns 404 for /api/agents/:id/tasks when agent does not exist", async () => {
+    const res = await GET(buildApp(), "/api/agents/agent-missing/tasks");
+
+    expect(res.status).toBe(404);
+    expect(res.body.error).toBe("Agent not found");
+    expect(store.listTasks).not.toHaveBeenCalled();
+  });
+});
+
 describe("Attachment routes", () => {
   const FAKE_ATTACHMENT: TaskAttachment = {
     filename: "1234-screenshot.png",

packages/dashboard/src/routes.ts

@@ -2626,6 +2626,45 @@ export function createApiRoutes(store: TaskStore, options?: ServerOptions): Rout
     }
   });
 
+  // Assign or unassign a task to an explicit agent
+  router.patch("/tasks/:id/assign", async (req, res) => {
+    try {
+      const { agentId } = req.body as { agentId?: string | null };
+      if (agentId !== null && typeof agentId !== "string") {
+        res.status(400).json({ error: "agentId must be a string or null" });
+        return;
+      }
+      if (typeof agentId === "string" && agentId.trim().length === 0) {
+        res.status(400).json({ error: "agentId must be a non-empty string or null" });
+        return;
+      }
+
+      const scopedStore = await getScopedStore(req);
+      const { AgentStore } = await import("@fusion/core");
+      const agentStore = new AgentStore({ rootDir: scopedStore.getFusionDir() });
+      await agentStore.init();
+
+      if (typeof agentId === "string") {
+        const agent = await agentStore.getAgent(agentId);
+        if (!agent) {
+          res.status(404).json({ error: "Agent not found" });
+          return;
+        }
+      }
+
+      const task = await scopedStore.updateTask(req.params.id, {
+        assignedAgentId: agentId === null ? null : agentId,
+      });
+      res.json(task);
+    } catch (err: any) {
+      if (err?.code === "ENOENT" || err?.message?.includes("not found")) {
+        res.status(404).json({ error: err.message ?? "Task not found" });
+      } else {
+        res.status(500).json({ error: err.message });
+      }
+    }
+  });
+
   // Delete task
   router.delete("/tasks/:id", async (req, res) => {
     try {
@@ -7168,6 +7207,30 @@ Output ONLY the prompt text (no markdown, no explanations).`;
     }
   });
 
+  /**
+   * GET /api/agents/:id/tasks
+   * List tasks explicitly assigned to the given agent.
+   */
+  router.get("/agents/:id/tasks", async (req, res) => {
+    try {
+      const scopedStore = await getScopedStore(req);
+      const { AgentStore } = await import("@fusion/core");
+      const agentStore = new AgentStore({ rootDir: scopedStore.getFusionDir() });
+      await agentStore.init();
+
+      const agent = await agentStore.getAgent(req.params.id);
+      if (!agent) {
+        res.status(404).json({ error: "Agent not found" });
+        return;
+      }
+
+      const tasks = await scopedStore.listTasks();
+      res.json(tasks.filter((task) => task.assignedAgentId === req.params.id));
+    } catch (err: any) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
   /**
    * POST /api/agents/:id/heartbeat
    * Record a heartbeat for an agent.